@prohost/cli 0.16.6 → 0.16.8

package/CHANGELOG.md

@@ -6,6 +6,43 @@ builds via `prepack`, runs the suite, publishes, and tags `cli-v<version>`.
 
 ## Unreleased
 
+## 0.16.8
+
+- **A dedicated install never takes over a service home that holds another computer.** When the
+  service home already held a different computer's key, the install restarted that computer under
+  the label, left the invoking home's key where it was, and reported a takeover. It is now refused
+  before anything is installed, naming the computer it holds.
+- **A copy that isn't there afterwards is no takeover.** When the key the install copied into the
+  service home can't be read back as that computer's, the service is uninstalled and the command
+  fails, naming the file to check (no credential is deleted: which file this install wrote can't be
+  told from one it didn't). The invoking home keeps its key.
+- **`uninstall` says when a service is still stopping after it gives the key back.** The key goes
+  back at once, as before (the service's definition is already gone, so a later run could never
+  find it again). A stop that failed or is still draining (`launchctl bootout`, `systemctl disable
+  --now`) is then waited for up to 30 s, and a service still stopping fails the command with what
+  to wait for before running the computer from that home. A service copy that can't be deleted
+  after the give-back fails the command instead of leaving the key in two homes behind a success.
+- **Windows: a scheduled task that couldn't be deleted is a failure.** `uninstall` reported it as
+  "No host service was installed" and removed its files, so the key went back while the task could
+  start again on it. It now fails, keeps the task's files (a later uninstall still finds it), and
+  gives nothing back.
+
+## 0.16.7
+
+- **An undo whose cleanup fails says so.** When a dedicated install undoes itself (its hand-off
+  note could not be written) but a copy of the key it made can't be removed — on Windows the
+  administrators' copy — it reports a partial undo naming each leftover file, instead of "Undone".
+- README: the one-key guarantee names its exception (a service home that already held the key).
+- **Status reports with a terminal session are accepted again.** A live terminal went into
+  `running` with its runtime (`claude_code`) as `agent_id` and `started_at: ''`, which the server
+  refuses (422) for the whole report, so the computer showed offline. A terminal entry now sends
+  `agent_id: null`, `runtime`, and `started_at: null`; every string is clipped to the server's
+  limits.
+- **A refused status says why.** The server's reason (a 422 names the field) is logged, secrets
+  blanked, at the first refusal and again every 10 minutes with a count while it lasts.
+- The status body is pinned by a contract fixture (`shared/computers/tests/fixtures/cli_status_report.json`)
+  that the server's tests validate with `StatusReport`.
+
 ## 0.16.6
 
 - **A hand-off note that can't be written undoes the dedicated install.** The note is part of the
@@ -56,6 +93,15 @@ builds via `prepack`, runs the suite, publishes, and tags `cli-v<version>`.
   (`session_unknown`), another or no login (`login_changed`, `login_unavailable`), or past 10 minutes
   (`restart_expired`); a redelivery of one done is acked as done. Declared as
   `code_thread_restart_skip_permissions` beside `code_thread_skip_permissions`.
+- **A restarted Claude Code is ready for replies only once its own hook runs.** Each launch in a
+  thread's window now has an id (`PROHOST_LAUNCH_ID` in the agent's environment, which its hooks
+  inherit), recorded in `code-host/state/<terminal>.launch` as pending until the new process's own
+  first hook runs; meanwhile no other hook marks the window ready. A hook of the replaced process
+  that finishes after the restart can no longer mark the new one past its first-run screens, so a
+  relayed reply never types into its bypass confirmation, however late that hook runs. A launch the
+  daemon couldn't confirm stays pending (replies wait) until its own hook runs or the window is
+  restarted again. A start or restart whose launch can't be recorded launches nothing. Windows an
+  older build started keep the old rule.
 - Enable disabled macOS services before loading them, and report enable failures instead of claiming the install succeeded.
 
 ## 0.16.4

package/README.md

@@ -248,8 +248,12 @@ or `$SUDO_USER`'s) keeps only a note — `{handed_to: {label, service_user, serv
 computer_id, name, account, code_host_home?}`, no key — written as that home's owner.
 `host status` there reports `handed_to`; `unpair`, `pair` and a personal `install` refuse and
 name the service. The note is part of the takeover: if it can't be written, the install is
-undone (the service uninstalled, the key it copied removed) and fails, so the key is never left in
-both homes; a failed install leaves the key where it was. `sudo prohost host uninstall --label <id>` gives the key back to
+undone (the service uninstalled, the key it copied removed) and fails, so it never leaves a second
+copy of the key behind. One exception: when the service home already held the key before this
+install (an older setup that copied it), that copy stays, so the key is in both homes until the
+note can be written — never run `prohost host unpair` from the original home meanwhile; `sudo
+prohost host uninstall --label <id>` then removes the service. A failed install leaves the key
+where it was. `sudo prohost host uninstall --label <id>` gives the key back to
 that home (so `prohost host install` runs it there again); `sudo prohost host unpair --label <id>`
 removes the computer. Both read the service's home from its installed definition (root's file),
 never from the note, which the home's owner can edit. **Updates drain:**

package/dist/codehost/filelock.d.ts

@@ -0,0 +1,44 @@
+/**
+ * A lock between processes on this Mac: a file beside what it guards, made by hard-linking a private
+ * file that already holds its owner's token (so a lock is never seen without one). Its holder
+ * releases it only while the file still holds that token, so it never removes a lock another
+ * process holds now. A lock left by a process that died holding it is taken over once it is
+ * `staleMs` old (see {@link takeOverStale}); with `liveHolders`, a lock whose holder still runs is
+ * never taken over, however old (a Mac asleep makes any lock look old).
+ */
+/** Whether the lock at `file` was left by a holder that died. */
+type StaleJudge = (file: string, nowMs: number) => boolean;
+/**
+ * When process `pid` started, in whole seconds, or `undefined` if that can't be told. From its
+ * elapsed time (`ps -o etime`), never a printed date: no time zone to get wrong.
+ */
+export declare function processStartSec(pid: number, nowMs?: number): number | undefined;
+/**
+ * Remove a stale lock without ever removing a live one: it is moved aside atomically first, then
+ * judged again. A file that is no longer stale is another process's fresh lock (it took over the
+ * same stale one a moment earlier) and is linked back, unless a lock exists again. Judged by age or
+ * holder, never by inode: Linux reuses a deleted file's inode for the next one made.
+ */
+export declare function takeOverStale(lock: string, staleMs: number, nowMs?: number, stale?: StaleJudge, judged?: string): void;
+export interface FileLockOptions {
+    /** A lock older than this was left by a holder that died (with `liveHolders`: see {@link holderGone}). */
+    staleMs: number;
+    /** Never take over a lock whose holder still runs, however old it is. */
+    liveHolders?: boolean;
+    /** How long to wait for another holder before giving up. */
+    waitMs: number;
+    now?: () => number;
+    /** When a process started (seconds); `ps` by default. */
+    processStart?: (pid: number) => number | undefined;
+}
+/**
+ * Run `work` holding `lock`. Returns `{ ok: false }` when another process holds it past
+ * `waitMs` (the caller says what that means); errors creating the lock's folder or file throw.
+ */
+export declare function withFileLock<T>(lock: string, work: () => T, options: FileLockOptions): {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+};
+export {};

package/dist/codehost/filelock.js

@@ -0,0 +1,239 @@
+/**
+ * A lock between processes on this Mac: a file beside what it guards, made by hard-linking a private
+ * file that already holds its owner's token (so a lock is never seen without one). Its holder
+ * releases it only while the file still holds that token, so it never removes a lock another
+ * process holds now. A lock left by a process that died holding it is taken over once it is
+ * `staleMs` old (see {@link takeOverStale}); with `liveHolders`, a lock whose holder still runs is
+ * never taken over, however old (a Mac asleep makes any lock look old).
+ */
+import { execFileSync } from 'node:child_process';
+import { linkSync, readdirSync, readFileSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { ensurePrivateDir } from './settings.js';
+const olderThan = (staleMs) => (file, nowMs) => nowMs - statSync(file).mtimeMs > staleMs;
+let ownStart;
+/**
+ * When this process started, in whole seconds, as `ps` tells it (the same source a waiter checks it
+ * against, so a clock correction since can't set them apart); asked once per process. `0` (none)
+ * when `ps` can't tell: such a lock is then judged by its holder's pid alone.
+ */
+function ownStartSec() {
+    ownStart ??= processStartSec(process.pid) ?? 0;
+    return ownStart;
+}
+/** `<pid>.<start seconds>.<random>`: who holds the lock, and (with `withStart`) which incarnation of that pid. */
+function newToken(withStart) {
+    return `${process.pid}.${withStart ? ownStartSec() : 0}.${Math.random().toString(16).slice(2)}`;
+}
+/** The holder named in the lock at `file`, or `undefined` if its token can't be read. */
+function holderOf(file) {
+    try {
+        const [pidText, startText] = readFileSync(file, 'utf8').split('.');
+        const pid = Number.parseInt(pidText ?? '', 10);
+        if (!Number.isInteger(pid) || pid <= 0)
+            return undefined;
+        const startSec = Number.parseInt(startText ?? '', 10);
+        return { pid, startSec: Number.isInteger(startSec) && startSec > 0 ? startSec : undefined };
+    }
+    catch {
+        return undefined;
+    }
+}
+function readToken(file) {
+    try {
+        return readFileSync(file, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+function running(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/** `[[dd-]hh:]mm:ss`, as `ps -o etime` prints it, in seconds. */
+function elapsedSec(text) {
+    const match = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/.exec(text.trim());
+    if (!match)
+        return undefined;
+    const [, days, hours, minutes, seconds] = match;
+    return ((Number(days ?? 0) * 24 + Number(hours ?? 0)) * 60 + Number(minutes)) * 60 + Number(seconds);
+}
+/**
+ * When process `pid` started, in whole seconds, or `undefined` if that can't be told. From its
+ * elapsed time (`ps -o etime`), never a printed date: no time zone to get wrong.
+ */
+export function processStartSec(pid, nowMs = Date.now()) {
+    try {
+        const out = execFileSync('ps', ['-o', 'etime=', '-p', String(pid)], {
+            encoding: 'utf8',
+            timeout: 1_000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const elapsed = elapsedSec(out);
+        return elapsed === undefined ? undefined : Math.round(nowMs / 1000) - elapsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** When this Mac last booted, in ms. */
+const bootedAtMs = () => Date.now() - os.uptime() * 1000;
+/**
+ * Stale only once its holder is gone. A holder that still runs (suspended, say, while the Mac slept)
+ * keeps its lock. Gone: a lock from before the last boot; a holder pid that runs no process; or, for
+ * a lock past `staleMs`, a pid that now belongs to another process (it started at another time). A
+ * lock whose token can't be read is judged by age.
+ */
+const holderGone = (staleMs, startOf) => (file, nowMs) => {
+    const { mtimeMs } = statSync(file);
+    if (mtimeMs < bootedAtMs() - 60_000)
+        return true;
+    const holder = holderOf(file);
+    if (holder === undefined)
+        return nowMs - mtimeMs > staleMs;
+    if (!running(holder.pid))
+        return true;
+    if (nowMs - mtimeMs <= staleMs || holder.startSec === undefined)
+        return false;
+    // Old, and its pid runs: the same process only if it started when the holder did.
+    const started = startOf(holder.pid);
+    return started !== undefined && Math.abs(started - holder.startSec) > 2;
+};
+/**
+ * Remove a stale lock without ever removing a live one: it is moved aside atomically first, then
+ * judged again. A file that is no longer stale is another process's fresh lock (it took over the
+ * same stale one a moment earlier) and is linked back, unless a lock exists again. Judged by age or
+ * holder, never by inode: Linux reuses a deleted file's inode for the next one made.
+ */
+export function takeOverStale(lock, staleMs, nowMs = Date.now(), stale = olderThan(staleMs), judged) {
+    const aside = `${lock}.${process.pid}.${Math.random().toString(16).slice(2)}.stale`;
+    try {
+        renameSync(lock, aside);
+    }
+    catch {
+        return; // someone else moved or released it
+    }
+    try {
+        // Not the lock that was judged (`judged`: its token then): a successor took the path meanwhile,
+        // and its lock goes straight back, unjudged.
+        if ((judged !== undefined && readToken(aside) !== judged) || !stale(aside, nowMs)) {
+            try {
+                linkSync(aside, lock);
+            }
+            catch {
+                /* a newer lock is there: that one stands */
+            }
+        }
+    }
+    finally {
+        rmSync(aside, { force: true });
+    }
+}
+/**
+ * Drafts (`<lock>.<token>.tmp`) a holder left behind when it died between writing one and removing
+ * it: removed once older than `staleMs` and their writer runs no more. Run by a holder, after it
+ * has the lock, so the state folder never fills up with them.
+ */
+function sweepDrafts(lock, staleMs, nowMs) {
+    const dir = path.dirname(lock);
+    const prefix = `${path.basename(lock)}.`;
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (!name.startsWith(prefix) || !(name.endsWith('.tmp') || name.endsWith('.stale')))
+            continue;
+        const file = path.join(dir, name);
+        try {
+            if (nowMs - statSync(file).mtimeMs <= staleMs)
+                continue;
+            const pid = Number.parseInt(name.slice(prefix.length).split('.')[0] ?? '', 10);
+            if (Number.isInteger(pid) && pid > 0 && running(pid))
+                continue;
+            rmSync(file, { force: true });
+        }
+        catch {
+            /* gone meanwhile */
+        }
+    }
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Run `work` holding `lock`. Returns `{ ok: false }` when another process holds it past
+ * `waitMs` (the caller says what that means); errors creating the lock's folder or file throw.
+ */
+export function withFileLock(lock, work, options) {
+    ensurePrivateDir(path.dirname(lock));
+    const now = options.now ?? Date.now;
+    const deadline = now() + options.waitMs;
+    const stale = options.liveHolders
+        ? holderGone(options.staleMs, options.processStart ?? processStartSec)
+        : olderThan(options.staleMs);
+    // Released only while the file is still this one: never a lock another process holds now.
+    const token = newToken(options.liveHolders === true);
+    // The token is written first, privately; the lock appears only as a link to it, whole.
+    const draft = `${lock}.${token}.tmp`;
+    writeFileSync(draft, token, { mode: 0o600, flag: 'wx' });
+    try {
+        for (;;) {
+            try {
+                linkSync(draft, lock);
+                // The link carries the draft's age: made fresh now, then checked still ours (a waiter that
+                // judged it by that age a moment earlier may have taken it over; then this one tries again).
+                const at = new Date(now());
+                utimesSync(lock, at, at);
+                if (readFileSync(lock, 'utf8') === token)
+                    break;
+                continue;
+            }
+            catch (err) {
+                if (err.code === 'ENOENT')
+                    continue; // taken over meanwhile
+                if (err.code !== 'EEXIST')
+                    throw err;
+            }
+            try {
+                const judged = readToken(lock);
+                if (stale(lock, now())) {
+                    takeOverStale(lock, options.staleMs, now(), stale, judged);
+                    continue;
+                }
+            }
+            catch {
+                continue; // released between the link and the stat: try again at once
+            }
+            if (now() >= deadline)
+                return { ok: false };
+            sleepSync(10 + Math.floor(Math.random() * 20));
+        }
+    }
+    finally {
+        rmSync(draft, { force: true });
+    }
+    sweepDrafts(lock, options.staleMs, now());
+    try {
+        return { ok: true, value: work() };
+    }
+    finally {
+        try {
+            if (readFileSync(lock, 'utf8') === token)
+                rmSync(lock, { force: true });
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}

package/dist/codehost/folders.d.ts

@@ -65,19 +65,14 @@ export declare const TOUCH_LOCK_WAIT_MS = 100;
 export declare class FoldersBusyError extends Error {
     constructor();
 }
-/**
- * Remove a stale lock without ever removing a live one: it is moved aside atomically first, then
- * judged by its age again. A file that is no longer stale is another process's fresh lock (it took
- * over the same stale one a moment earlier) and is linked back, unless a lock exists again. Judged
- * by age, never by inode: Linux reuses a deleted file's inode for the next one made.
- */
+/** {@link takeOverStale} for the folders lock (its stale age). */
 export declare function takeOverStale(lock: string, nowMs?: number): void;
 /**
  * Run `work` (a read-modify-write of `folders.json`) holding the list's lock: `folders.json.lock`,
- * created exclusively. The desktop app's `folders add`, a second `folders add` and the daemon
- * moving a started folder to the front are separate processes; without it, two that read the same
- * list each write it back without the other's folder. A lock left by a process that died is taken
- * over once it is {@link FOLDERS_LOCK_STALE_MS} old.
+ * created exclusively ({@link withFileLock}). The desktop app's `folders add`, a second `folders add`
+ * and the daemon moving a started folder to the front are separate processes; without it, two that
+ * read the same list each write it back without the other's folder. A lock left by a process that
+ * died is taken over once it is {@link FOLDERS_LOCK_STALE_MS} old.
  *
  * @throws FoldersBusyError when another process holds it past {@link FOLDERS_LOCK_WAIT_MS}.
  */

package/dist/codehost/folders.js

@@ -19,10 +19,11 @@
  * segments: a symlink inside an opened folder that points out of it does not
  * count as inside.
  */
-import { closeSync, linkSync, openSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeSync } from 'node:fs';
+import { realpathSync, statSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { codeHostDir, ensurePrivateDir, readJsonObject, writePrivateJson } from './settings.js';
+import { takeOverStale as takeOverStaleLock, withFileLock } from './filelock.js';
+import { codeHostDir, readJsonObject, writePrivateJson } from './settings.js';
 export const FOLDERS_VERSION = 1;
 export const MAX_OPENED_FOLDERS = 50;
 /** The server's bound on a start's `folder` (CONTRACT: ≤ 1024 chars). */
@@ -109,93 +110,28 @@ export class FoldersBusyError extends Error {
         super('The opened-folders list is busy (another prohost is changing it). Try again.');
     }
 }
-/**
- * Remove a stale lock without ever removing a live one: it is moved aside atomically first, then
- * judged by its age again. A file that is no longer stale is another process's fresh lock (it took
- * over the same stale one a moment earlier) and is linked back, unless a lock exists again. Judged
- * by age, never by inode: Linux reuses a deleted file's inode for the next one made.
- */
+/** {@link takeOverStale} for the folders lock (its stale age). */
 export function takeOverStale(lock, nowMs = Date.now()) {
-    const aside = `${lock}.${process.pid}.${Math.random().toString(16).slice(2)}.stale`;
-    try {
-        renameSync(lock, aside);
-    }
-    catch {
-        return; // someone else moved or released it
-    }
-    try {
-        if (nowMs - statSync(aside).mtimeMs <= FOLDERS_LOCK_STALE_MS) {
-            try {
-                linkSync(aside, lock);
-            }
-            catch {
-                /* a newer lock is there: that one stands */
-            }
-        }
-    }
-    finally {
-        rmSync(aside, { force: true });
-    }
-}
-function sleepSync(ms) {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+    takeOverStaleLock(lock, FOLDERS_LOCK_STALE_MS, nowMs);
 }
 /**
  * Run `work` (a read-modify-write of `folders.json`) holding the list's lock: `folders.json.lock`,
- * created exclusively. The desktop app's `folders add`, a second `folders add` and the daemon
- * moving a started folder to the front are separate processes; without it, two that read the same
- * list each write it back without the other's folder. A lock left by a process that died is taken
- * over once it is {@link FOLDERS_LOCK_STALE_MS} old.
+ * created exclusively ({@link withFileLock}). The desktop app's `folders add`, a second `folders add`
+ * and the daemon moving a started folder to the front are separate processes; without it, two that
+ * read the same list each write it back without the other's folder. A lock left by a process that
+ * died is taken over once it is {@link FOLDERS_LOCK_STALE_MS} old.
  *
  * @throws FoldersBusyError when another process holds it past {@link FOLDERS_LOCK_WAIT_MS}.
  */
 export function withFoldersLock(env, work, options = {}) {
-    const lock = `${foldersPath(env)}.lock`;
-    ensurePrivateDir(path.dirname(lock));
-    const now = options.now ?? Date.now;
-    const deadline = now() + (options.waitMs ?? FOLDERS_LOCK_WAIT_MS);
-    // Released only while the file is still this one: never a lock another process holds now.
-    const token = `${process.pid}.${Math.random().toString(16).slice(2)}`;
-    for (;;) {
-        try {
-            const fd = openSync(lock, 'wx', 0o600);
-            try {
-                writeSync(fd, token);
-            }
-            finally {
-                closeSync(fd);
-            }
-            break;
-        }
-        catch (err) {
-            if (err.code !== 'EEXIST')
-                throw err;
-        }
-        try {
-            if (now() - statSync(lock).mtimeMs > FOLDERS_LOCK_STALE_MS) {
-                takeOverStale(lock, now());
-                continue;
-            }
-        }
-        catch {
-            continue; // released between the open and the stat: try again at once
-        }
-        if (now() >= deadline)
-            throw new FoldersBusyError();
-        sleepSync(10 + Math.floor(Math.random() * 20));
-    }
-    try {
-        return work();
-    }
-    finally {
-        try {
-            if (readFileSync(lock, 'utf8') === token)
-                rmSync(lock, { force: true });
-        }
-        catch {
-            /* already gone */
-        }
-    }
+    const held = withFileLock(`${foldersPath(env)}.lock`, work, {
+        staleMs: FOLDERS_LOCK_STALE_MS,
+        waitMs: options.waitMs ?? FOLDERS_LOCK_WAIT_MS,
+        now: options.now,
+    });
+    if (!held.ok)
+        throw new FoldersBusyError();
+    return held.value;
 }
 /** `folder` (a realpath) at the front, opened now; the oldest past the cap drops off. */
 function upsertFront(folder, env, now, waitMs) {

package/dist/codehost/ready.d.ts

@@ -8,23 +8,86 @@
  * screen, is what lets a relayed reply be typed: before it, the dialog may be
  * up or about to be drawn, and an Enter would answer it. The mark is a file,
  * so it outlives a daemon restart.
+ *
+ * A window's Claude Code can be replaced (a restart), and a hook of the old one
+ * may still be running when it is: one that writes the mark after the restart
+ * dropped it would say the new process is past screens it hasn't reached. So
+ * each launch has an id ({@link LAUNCH_ENV} in the process's environment, which
+ * its hooks inherit), recorded in `<state>/<terminal>.launch` as pending until
+ * the new process's own first hook runs; meanwhile no other hook marks the
+ * window, however late it runs. A launch the daemon couldn't confirm stays
+ * pending (no reply types) until its own hook runs or the window is restarted
+ * again. A window with no launch record (one an older build started) is judged
+ * by the mark alone, as before.
+ */
+/** The launch id a window's agent process runs under, in its environment (and so its hooks'). */
+export declare const LAUNCH_ENV = "PROHOST_LAUNCH_ID";
+/**
+ * `<state>/<terminal>.launch`: the launch the window runs (`launch`; `null` for a process with no
+ * launch id, such as one an older build started), and `next`, one about to replace it whose own
+ * hook hasn't run yet. `gen` changes with every write, and a mark counts only for the `gen` it was
+ * written under, so a mark whose writer looked before a launch began never counts after it.
  */
+interface LaunchRecord {
+    launch: string | null;
+    next?: string;
+    gen: number;
+}
 export declare function readyPath(terminalId: string, env?: NodeJS.ProcessEnv): string;
+export declare function launchPath(terminalId: string, env?: NodeJS.ProcessEnv): string;
 /**
- * Mark the terminal's Claude Code past its trust dialog (a hook ran). Atomic (`writePrivateJson`).
- * Returns whether it is marked afterwards; `false` means the write failed, and the caller says so.
+ * The launch the window runs now: its id, `null` for a process with no launch id or a window with no
+ * launch record, or `undefined` when the record can't be read.
+ */
+export declare function currentLaunch(terminalId: string, env?: NodeJS.ProcessEnv): string | null | undefined;
+/** The launch waiting for its first hook, if one is. */
+export declare function pendingLaunch(terminalId: string, env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * A hook of launch `launch` ran in the window (by default the caller's own, from its environment):
+ * mark the window past its trust dialog. Atomic (`writePrivateJson`).
+ *
+ * - The pending launch's own hook proves it runs: it becomes the window's launch, and is marked.
+ * - While a launch is pending, any other hook is of a process being replaced: it has no say, however
+ *   late it runs (a hook suspended while the Mac slept may resume long after).
+ * - With nothing pending, a hook of another launch is of the process the window runs (an older
+ *   build relaunched it since): its launch becomes the window's.
+ *
+ * Returns whether the window is marked afterwards, or that the hook had no say; `false` means the
+ * state couldn't be read or written, and the caller says so.
  */
-export declare function markReady(terminalId: string, env?: NodeJS.ProcessEnv): boolean;
+export declare function markReady(terminalId: string, env?: NodeJS.ProcessEnv, launch?: string | null, now?: number): boolean;
 /**
- * Forget the mark: the window's Claude Code was replaced (a restart), and the new one is past its
- * dialog only once its own first hook runs. Returns whether no mark is left.
+ * Forget the mark: the window's Claude Code is being replaced, and the new one is past its dialog
+ * only once its own first hook runs. Returns whether no mark is left.
  */
 export declare function clearReady(terminalId: string, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Launch `launch` is about to run in the window (a start or a restart): pending until its own first
+ * hook runs, and no other hook marks the window meanwhile. Recorded first, then the old mark dropped.
+ * Returns whether both were done; on `false` the caller must not launch.
+ */
+export declare function beginLaunch(terminalId: string, launch: string, env?: NodeJS.ProcessEnv, now?: number): boolean;
+/** What {@link restoreLaunch} puts back: the window's launch record and readiness before {@link beginLaunch}. */
+export interface LaunchState {
+    record: LaunchRecord | null | undefined;
+    ready: boolean | undefined;
+}
+export declare function launchState(terminalId: string, env?: NodeJS.ProcessEnv): LaunchState;
+/**
+ * The new launch never ran (nothing was replaced): the window's old process keeps its launch and,
+ * if it had it, its readiness. If that can't be written, the launch stays pending (no reply types)
+ * until the window is restarted again.
+ */
+export declare function restoreLaunch(terminalId: string, state: LaunchState, env?: NodeJS.ProcessEnv, now?: number): void;
 /**
  * The transcript files (`<session>.jsonl`) Claude Code keeps for `cwd` under `configDir`: one exists
  * for a session only once its first prompt ran. Empty when there are none or they can't be read.
  */
 export declare function claudeTranscripts(cwd: string, configDir: string): string[];
 export declare function claudeSessionSince(cwd: string, configDir: string, sinceMs: number): boolean;
-/** `true` past the dialog, `false` not yet, `undefined` when the state can't be read. */
+/**
+ * `true` past the dialog (a hook of the launch the window runs now ran, and no other launch is
+ * pending), `false` not yet, `undefined` when the state can't be read.
+ */
 export declare function isReady(terminalId: string, env?: NodeJS.ProcessEnv): boolean | undefined;
+export {};