@prohost/cli 0.16.7 → 0.16.10

package/CHANGELOG.md

@@ -6,6 +6,53 @@ builds via `prepack`, runs the suite, publishes, and tags `cli-v<version>`.
 
 ## Unreleased
 
+## 0.16.10
+
+- **A Code thread's terminal can be ended from ProhostAI.** `code_thread.end_requested` closes the
+  thread's viewers, its agent and shell windows (and a shell left without its agent window), and
+  whatever of their process groups is left (SIGTERM, then SIGKILL after 2 s). Its windows were the
+  only record of it, so it is never adopted again and drops out of `running`, freeing its slot; its
+  folder is left as it is. Idempotent (a terminal already gone is ended), taken whatever the remote
+  switch says (ending never types), refused as `end_expired` past 10 minutes, retried when tmux
+  doesn't answer. Declared as `code_thread_end_session`; an older CLI never declares it and acks
+  the event ignored.
+- An ended terminal leaves a mark (`state/<terminal>.ended`) holding its pane processes, each with
+  when it started and the boot it ran in: a start delivered again after a lost ack never relaunches
+  it, a retry after a kill whose answer was lost still reaps what it ran (never a pid since handed to
+  another process, or from before a restart), a late redelivery of a finished end is answered ended,
+  and a viewer's shell is never made once an end has begun.
+
+## 0.16.9
+
+- **Windows: a scheduled task counts as gone only when Task Scheduler says so.** An `uninstall`
+  whose `schtasks /Delete` failed, and whose `/Query` also failed for another reason (the scheduler
+  not answering), took the task as absent and gave the key back. Only a "cannot find" answer counts
+  as absent now; anything else is a failure that keeps the task's files and gives nothing back.
+- **A dedicated install undoing itself keeps the administrators' key copy on Windows** when it
+  can't tell that copy is its own (`uninstallService`'s new `keepKeyCopy`), as it already kept the
+  service home's file.
+
+## 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

package/dist/agent/run.js

@@ -53,7 +53,7 @@ import { SessionStore, sessionKeyFor } from './sessionstore.js';
 import { verifySignature } from './signature.js';
 import { VENUE_RUN_TOKEN_CAPABILITY, apiForRun, claudeSupportsVenueSessions, claudeVenueCommand, VENUE_PROGRESS, VENUE_SESSION_FEATURE, VENUE_SESSION_FRAME, VENUE_SESSION_OPEN_FRAME, VENUE_GRANT_CHECK_MS, VENUE_EXPIRY_MARGIN_MS, VENUE_GRANT_ENDED_ERROR, VENUE_GRANT_EXPIRED_ERROR, isVenueRun, venueEnv, venueGrantLive, venueGrantRemainingMs, venueRunFromSession, venueWorkdir, } from './venue.js';
 import { RUN_REPOS_ENV_VAR, WorktreeManager } from './worktrees.js';
-import { CODE_THREAD_FOLDERS_CAPABILITY, CODE_THREAD_RESTART_SKIP_PERMISSIONS_CAPABILITY, CODE_THREAD_SKIP_PERMISSIONS_CAPABILITY, CODE_THREADS_CAPABILITY, CodeHost, RefusedDeliveryError, REMOTE_TERMINAL_CAPABILITY, EVENT_CODE_THREAD_APPROVAL_DECIDED, EVENT_CODE_THREAD_INPUT_REQUESTED, EVENT_CODE_THREAD_RESTART_REQUESTED, EVENT_CODE_THREAD_START_REQUESTED, } from '../codehost/host.js';
+import { CODE_THREAD_FOLDERS_CAPABILITY, CODE_THREAD_END_SESSION_CAPABILITY, CODE_THREAD_RESTART_SKIP_PERMISSIONS_CAPABILITY, CODE_THREAD_SKIP_PERMISSIONS_CAPABILITY, CODE_THREADS_CAPABILITY, CodeHost, RefusedDeliveryError, REMOTE_TERMINAL_CAPABILITY, EVENT_CODE_THREAD_APPROVAL_DECIDED, EVENT_CODE_THREAD_INPUT_REQUESTED, EVENT_CODE_THREAD_END_REQUESTED, EVENT_CODE_THREAD_RESTART_REQUESTED, EVENT_CODE_THREAD_START_REQUESTED, } from '../codehost/host.js';
 import { loadSettings as loadCodeHostSettings } from '../codehost/settings.js';
 import { isWebhookEvent } from '../forward.js';
 import { DEFAULT_WS_URL } from '../listen.js';
@@ -1646,6 +1646,8 @@ export async function runAgentHarness(options) {
                     CODE_THREAD_FOLDERS_CAPABILITY,
                     codeHost.instanceCapability(),
                     ...(codeHost.agentCapabilities?.() ?? []),
+                    // Ending a thread's terminal (`code_thread.end_requested`): whatever the remote switch says.
+                    ...(codeHost.handleEnd ? [CODE_THREAD_END_SESSION_CAPABILITY] : []),
                 ]
                 : []),
             // Read on every frame, so `remote off` stops being declared at the next one.
@@ -2081,7 +2083,8 @@ export async function runAgentHarness(options) {
                 if (frame.event === EVENT_CODE_THREAD_START_REQUESTED ||
                     frame.event === EVENT_CODE_THREAD_INPUT_REQUESTED ||
                     frame.event === EVENT_CODE_THREAD_APPROVAL_DECIDED ||
-                    frame.event === EVENT_CODE_THREAD_RESTART_REQUESTED) {
+                    frame.event === EVENT_CODE_THREAD_RESTART_REQUESTED ||
+                    frame.event === EVENT_CODE_THREAD_END_REQUESTED) {
                     if (!codeHost) {
                         if (!codeHostIgnoredLogged) {
                             codeHostIgnoredLogged = true;
@@ -2123,7 +2126,9 @@ export async function runAgentHarness(options) {
                             ? codeHost.handleInput(data, frame.delivery_id)
                             : frame.event === EVENT_CODE_THREAD_RESTART_REQUESTED
                                 ? (codeHost.handleRestart?.(data, frame.delivery_id) ?? Promise.resolve(false))
-                                : codeHost.handleApproval(data, frame.delivery_id);
+                                : frame.event === EVENT_CODE_THREAD_END_REQUESTED
+                                    ? (codeHost.handleEnd?.(data) ?? Promise.resolve(false))
+                                    : codeHost.handleApproval(data, frame.delivery_id);
                     // Acknowledged once handled, never before: a start acked and then
                     // lost to a crash or a shutdown would leave its thread starting
                     // forever. A start that ran — or failed, which it reports — is 200;

package/dist/codehost/host.d.ts

@@ -14,11 +14,13 @@ import type { PtySpawn } from './pty.js';
 import type { PairingIdentity } from './relay.js';
 import type { CodeHostSettings } from './settings.js';
 import { CodeTerminals } from './terminals.js';
-import type { AccountEnvResult, ApprovalRequest, CodeAgent, InputRequest, RestartRequest, StartRequest, TmuxRunner } from './terminals.js';
+import type { AccountEnvResult, ApprovalRequest, CodeAgent, EndRequest, InputRequest, RestartRequest, StartRequest, TmuxRunner } from './terminals.js';
 export declare const EVENT_CODE_THREAD_START_REQUESTED = "code_thread.start_requested";
 export declare const EVENT_CODE_THREAD_INPUT_REQUESTED = "code_thread.input_requested";
 export declare const EVENT_CODE_THREAD_APPROVAL_DECIDED = "code_thread.approval_decided";
 export declare const EVENT_CODE_THREAD_RESTART_REQUESTED = "code_thread.restart_requested";
+/** Close a thread's terminal session for good (`CodeTerminals.end`); a CLI without it acks it ignored. */
+export declare const EVENT_CODE_THREAD_END_REQUESTED = "code_thread.end_requested";
 /**
  * Declared in `runtime_status.capabilities` while this harness hosts threads.
  * Versioned with the contract the server relies on (`remote_terminal`, 409
@@ -60,12 +62,21 @@ export declare const CODE_THREAD_SKIP_PERMISSIONS_CAPABILITY = "code_thread_skip
  * (`CodeTerminals.restart`). The server offers the restart only for a thread whose host said so.
  */
 export declare const CODE_THREAD_RESTART_SKIP_PERMISSIONS_CAPABILITY = "code_thread_restart_skip_permissions";
+/**
+ * Declared beside {@link CODE_THREADS_CAPABILITY} by a host that handles `code_thread.end_requested`:
+ * it closes a thread's windows and what they run, and forgets the terminal (`CodeTerminals.end`).
+ * Not tied to the remote switch: ending only stops things on this Mac, never types. The server
+ * offers "End session" only for a thread whose host said so.
+ */
+export declare const CODE_THREAD_END_SESSION_CAPABILITY = "code_thread_end_session";
 /** `code_thread.start_requested` data (camelCase per the contract), or `null`. */
 export declare function parseStartRequest(data: Record<string, unknown>): StartRequest | null;
 /** `code_thread.input_requested` data, or `null`. */
 export declare function parseInputRequest(data: Record<string, unknown>): InputRequest | null;
 /** `code_thread.restart_requested` data, or `null`. */
 export declare function parseRestartRequest(data: Record<string, unknown>): RestartRequest | null;
+/** `code_thread.end_requested` data, or `null`. */
+export declare function parseEndRequest(data: Record<string, unknown>): EndRequest | null;
 /** What the harness needs from a host; tests fake it. */
 export interface CodeHostLike {
     start(): Promise<void>;
@@ -80,6 +91,8 @@ export interface CodeHostLike {
     handleApproval(data: Record<string, unknown>, deliveryId?: string): Promise<boolean>;
     /** `code_thread.restart_requested`; a host without it acks the event as ignored. */
     handleRestart?(data: Record<string, unknown>, deliveryId?: string): Promise<boolean>;
+    /** `code_thread.end_requested`; a host without it acks the event as ignored (and never declares the capability). */
+    handleEnd?(data: Record<string, unknown>): Promise<boolean>;
     latestStats(): HostStats | undefined;
     /** The owner's remote-terminal switch as it is on disk now. */
     remoteTerminalAllowed(): boolean;
@@ -127,8 +140,8 @@ export declare function parseApprovalDecision(data: Record<string, unknown>): Ap
  * server hands the reply or decision back instead of counting it delivered).
  */
 export declare class RefusedDeliveryError extends Error {
-    readonly reason: 'remote_terminal_disabled' | 'reply_interrupted' | 'terminal_gone' | 'shell_window' | 'decision_unconfirmed' | 'trust_prompt' | 'prompt_local' | 'prompt_open' | 'session_unknown' | 'login_changed' | 'login_unavailable' | 'restart_expired' | 'restart_unconfirmed' | 'agent_exited';
-    constructor(reason: 'remote_terminal_disabled' | 'reply_interrupted' | 'terminal_gone' | 'shell_window' | 'decision_unconfirmed' | 'trust_prompt' | 'prompt_local' | 'prompt_open' | 'session_unknown' | 'login_changed' | 'login_unavailable' | 'restart_expired' | 'restart_unconfirmed' | 'agent_exited');
+    readonly reason: 'remote_terminal_disabled' | 'reply_interrupted' | 'terminal_gone' | 'shell_window' | 'decision_unconfirmed' | 'trust_prompt' | 'prompt_local' | 'prompt_open' | 'session_unknown' | 'login_changed' | 'login_unavailable' | 'restart_expired' | 'end_expired' | 'restart_unconfirmed' | 'agent_exited';
+    constructor(reason: 'remote_terminal_disabled' | 'reply_interrupted' | 'terminal_gone' | 'shell_window' | 'decision_unconfirmed' | 'trust_prompt' | 'prompt_local' | 'prompt_open' | 'session_unknown' | 'login_changed' | 'login_unavailable' | 'restart_expired' | 'end_expired' | 'restart_unconfirmed' | 'agent_exited');
 }
 export declare class UnreportedOutcomeError extends Error {
     constructor(codeThreadId: string);
@@ -171,6 +184,8 @@ export interface CodeHostOptions {
     paused?: () => boolean;
     tmux?: TmuxRunner;
     spawnPty?: () => PtySpawn | undefined;
+    /** What an end signals what a closed window left (`CodeTerminalsOptions.signalGroup`). */
+    signalGroup?: (pid: number, signal: NodeJS.Signals | 0) => boolean;
     events?: CodeThreadEventSink;
     relay?: boolean;
     localServer?: boolean;
@@ -319,6 +334,12 @@ export declare class CodeHost implements CodeHostLike {
      * A redelivery of one already done is acknowledged as done, without restarting again.
      */
     handleRestart(data: Record<string, unknown>, deliveryId?: string): Promise<boolean>;
+    /**
+     * Close the thread's terminal session for good (`CodeTerminals.end`): true once it is gone, whether
+     * it was here or not, so a redelivery is answered the same. Refused when it came too late; a tmux
+     * that didn't answer is retried (503).
+     */
+    handleEnd(data: Record<string, unknown>): Promise<boolean>;
     /** The terminal's menu state (`menuState`) once a hook that is still deciding has had a moment to finish. */
     private menuSettled;
     /**

package/dist/codehost/host.js

@@ -30,6 +30,8 @@ export const EVENT_CODE_THREAD_START_REQUESTED = 'code_thread.start_requested';
 export const EVENT_CODE_THREAD_INPUT_REQUESTED = 'code_thread.input_requested';
 export const EVENT_CODE_THREAD_APPROVAL_DECIDED = 'code_thread.approval_decided';
 export const EVENT_CODE_THREAD_RESTART_REQUESTED = 'code_thread.restart_requested';
+/** Close a thread's terminal session for good (`CodeTerminals.end`); a CLI without it acks it ignored. */
+export const EVENT_CODE_THREAD_END_REQUESTED = 'code_thread.end_requested';
 /**
  * Declared in `runtime_status.capabilities` while this harness hosts threads.
  * Versioned with the contract the server relies on (`remote_terminal`, 409
@@ -71,6 +73,13 @@ export const CODE_THREAD_SKIP_PERMISSIONS_CAPABILITY = 'code_thread_skip_permiss
  * (`CodeTerminals.restart`). The server offers the restart only for a thread whose host said so.
  */
 export const CODE_THREAD_RESTART_SKIP_PERMISSIONS_CAPABILITY = 'code_thread_restart_skip_permissions';
+/**
+ * Declared beside {@link CODE_THREADS_CAPABILITY} by a host that handles `code_thread.end_requested`:
+ * it closes a thread's windows and what they run, and forgets the terminal (`CodeTerminals.end`).
+ * Not tied to the remote switch: ending only stops things on this Mac, never types. The server
+ * offers "End session" only for a thread whose host said so.
+ */
+export const CODE_THREAD_END_SESSION_CAPABILITY = 'code_thread_end_session';
 function text(value) {
     return typeof value === 'string' ? value : undefined;
 }
@@ -118,6 +127,14 @@ export function parseRestartRequest(data) {
         ...(requestedAtMs !== undefined ? { requestedAtMs } : {}),
     };
 }
+/** `code_thread.end_requested` data, or `null`. */
+export function parseEndRequest(data) {
+    const { codeThreadId, terminalId } = data;
+    if (!isValidId(codeThreadId) || !isValidId(terminalId))
+        return null;
+    const requestedAtMs = typeof data.requestedAtMs === 'number' && Number.isFinite(data.requestedAtMs) ? data.requestedAtMs : undefined;
+    return { codeThreadId, terminalId, ...(requestedAtMs !== undefined ? { requestedAtMs } : {}) };
+}
 /** `code_thread.approval_decided` data, or `null`. */
 export function parseApprovalDecision(data) {
     const { codeThreadId, terminalId, approvalId, decision } = data;
@@ -216,6 +233,7 @@ export class CodeHost {
             agentInstalled: (agent) => resolvesOnPath(AGENT_BINARIES[agent], this.env),
             authorized: () => this.authorized(),
             remoteControlAllowed: () => this.settings().allowRemoteTerminal,
+            signalGroup: options.signalGroup,
             log: this.log,
         });
     }
@@ -547,11 +565,15 @@ export class CodeHost {
         // acknowledged as done, never refused (the server would then say the agent still asks).
         if (event === EVENT_CODE_THREAD_RESTART_REQUESTED)
             return true;
+        // Ending only stops what runs here, never types: taken whatever the remote switch says.
+        if (event === EVENT_CODE_THREAD_END_REQUESTED)
+            return true;
         return settings.allowRemoteTerminal;
     }
     refusal(event) {
-        if (event === EVENT_CODE_THREAD_START_REQUESTED || !this.authorized())
+        if (event === EVENT_CODE_THREAD_START_REQUESTED || event === EVENT_CODE_THREAD_END_REQUESTED || !this.authorized()) {
             return undefined;
+        }
         const settings = this.settings();
         return settings.allowRemoteTerminal ? undefined : 'remote_terminal_disabled';
     }
@@ -679,6 +701,24 @@ export class CodeHost {
             this.retryLater(outcome.release ? deliveryId : undefined, request.codeThreadId);
         return false;
     }
+    /**
+     * Close the thread's terminal session for good (`CodeTerminals.end`): true once it is gone, whether
+     * it was here or not, so a redelivery is answered the same. Refused when it came too late; a tmux
+     * that didn't answer is retried (503).
+     */
+    async handleEnd(data) {
+        const request = parseEndRequest(data);
+        if (!request)
+            return false;
+        const outcome = {};
+        if (await this.terminals.end(request, outcome))
+            return true;
+        if (outcome.refused)
+            throw new RefusedDeliveryError(outcome.refused);
+        if (outcome.retry)
+            this.retryLater(undefined, request.codeThreadId);
+        return false;
+    }
     /** The terminal's menu state (`menuState`) once a hook that is still deciding has had a moment to finish. */
     async menuSettled(terminalId) {
         if (!isValidId(terminalId))

package/dist/codehost/terminals.d.ts

@@ -162,6 +162,31 @@ export interface RestartRequest {
     /** Relaunched without its permission prompts (only an explicit `true`; see {@link agentCommandLine}). */
     skipPermissions: boolean;
 }
+/**
+ * How long an end may wait to reach this Mac: one that arrives later is refused (`end_expired`), so a
+ * Mac that wakes up the next day never closes a terminal someone has since gone back to. The server
+ * holds the same limit (`END_SESSION_MAX_AGE`).
+ */
+export declare const END_MAX_AGE_MS: number;
+/** After its windows close: how long what they ran has to exit on SIGTERM before it is killed. */
+export declare const END_KILL_GRACE_MS = 2000;
+/** `code_thread.end_requested`: close the thread's terminal session for good. */
+export interface EndRequest {
+    codeThreadId: string;
+    terminalId: string;
+    /** When it was asked (server clock): refused past {@link END_MAX_AGE_MS}. Absent: never stale. */
+    requestedAtMs?: number;
+}
+/**
+ * The mark an end leaves (`state/<terminal>.ended`): that terminal is never started or attached again,
+ * whatever comes later (a start whose first ack was lost and is delivered again, a viewer racing the end).
+ */
+export declare function endedPath(terminalId: string, env: NodeJS.ProcessEnv): string;
+/** Why an end did nothing (`refused`), or that it should come again (`retry`: tmux didn't answer in time). */
+export interface EndOutcome {
+    refused?: 'end_expired';
+    retry?: boolean;
+}
 export interface ApprovalRequest {
     codeThreadId: string;
     terminalId: string;
@@ -339,6 +364,11 @@ export interface CodeTerminalsOptions {
     agentInstalled?: (agent: InstalledAgent) => boolean;
     /** Seam for tests: the timers who-sizes-the-window settles with (`sizing.ts`). */
     setTimer?: (fn: () => void, ms: number) => () => void;
+    /**
+     * Seam for tests: signal the process group `pid` leads (`kill(-pid, signal)`; `0` only asks whether
+     * it still has a process). Returns whether it reached one. Default: `process.kill`.
+     */
+    signalGroup?: (pid: number, signal: NodeJS.Signals | 0) => boolean;
 }
 /** What the thread says while Claude Code waits on its trust dialog. */
 export declare const TRUST_PROMPT_NOTE = "Claude Code is asking whether to trust this folder before it starts. Answer in the terminal.";
@@ -363,6 +393,17 @@ export declare class CodeTerminals {
     private lastListUncertain;
     /** Each agent window's pane process at the last `adopt`: a restart is confirmed by its changing. */
     private panePids;
+    /** Every thread window's pane process at the last `adopt`, by window name: what an end makes sure exits. */
+    private windowPids;
+    /** Per terminal: how to close each viewer attached to it now (an end closes them before its windows). */
+    private readonly viewers;
+    /** Terminals an end has begun on (set before its first await): no viewer or shell window joins them. */
+    private readonly ending;
+    /**
+     * Per terminal: its window lifecycle (a viewer's shell being made, an end), one at a time. A shell is
+     * made only while no end has begun, and an end runs only once a shell being made exists to close.
+     */
+    private readonly lifecycle;
     /** Who sizes each window, and what its viewers are told (`sizing.ts`). */
     readonly sizing: TerminalSizing;
     private readonly log;
@@ -384,6 +425,8 @@ export declare class CodeTerminals {
      * terminal never interleave into "first, second, Enter, Enter".
      */
     private serialize;
+    /** Run `work` after every earlier job queued in `queues` for this terminal. */
+    private serializeOn;
     /**
      * Mark a thread's worktree lane as in use (`.last-used`, the marker every
      * {@link WorktreeManager} prunes by), so a long-lived terminal's checkout is
@@ -463,6 +506,48 @@ export declare class CodeTerminals {
      * (`session_unknown`). An agent that exited into its shell is relaunched all the same.
      * Serialized with the thread's replies, so it never lands between a paste and its Enter.
      */
+    /**
+     * End the thread's terminal session for good (`code_thread.end_requested`): every viewer attached to
+     * it is closed, then its windows (tmux hangs up what they run), then whatever of their process groups
+     * is still there gets SIGTERM, and SIGKILL after {@link END_KILL_GRACE_MS}. Its windows were the
+     * only record of it (`adopt` reads them), so it is never adopted again and drops out of `list()`.
+     * Its folder is left as it is: the work in it is the owner's.
+     *
+     * Idempotent: a terminal this host doesn't have (ended already, closed in tmux, never here) is
+     * ended, and so true. False with `outcome.refused` when it came too late, with `outcome.retry` when
+     * tmux didn't answer in time (nothing known either way: asked again). Queued behind any reply or
+     * restart in flight for it, and after a start of it still running.
+     */
+    end(request: EndRequest, outcome?: EndOutcome): Promise<boolean>;
+    /** Whether an end has begun on, or finished with, this terminal (`ending`, its `.ended` mark). */
+    private ended;
+    /** Whether an earlier end of this terminal left its `.ended` mark. */
+    private hasEndMark;
+    /** This terminal's `.ended` mark as an earlier end left it, or `undefined`. */
+    private readMark;
+    /**
+     * The panes an earlier, unfinished end of this terminal left to reap: only from this boot (after a
+     * restart of the Mac every pid is someone else's). Each is checked again before it is signaled.
+     */
+    private pendingReap;
+    private markEnded;
+    private endNow;
+    /**
+     * What a closed window ran and didn't exit on its hangup (a process ignoring SIGHUP, a child in its
+     * group): SIGTERM, then SIGKILL past {@link END_KILL_GRACE_MS}. Only each pane's own process group:
+     * never a process that left it on purpose (`setsid`, a daemon it started).
+     */
+    private reapGroups;
+    /** When each of `pids` started (`paneStarts`); empty when `ps` couldn't say. */
+    private startsOf;
+    /**
+     * Of panes an earlier attempt saved, those whose process group is still this terminal's. A group
+     * outlives its leader, and a pid is never handed out while a group of that id exists: so one whose
+     * leader pid runs no process now is ours if anything is left in it. One whose pid runs a process is
+     * ours only if that process started when the saved one did; one with no saved start, or when `ps`
+     * can't say, is left alone.
+     */
+    private stillOurs;
     restart(request: RestartRequest, outcome?: RestartOutcome, hooks?: RestartHooks): Promise<boolean>;
     /** Once every typing job and restart already queued for the terminal has finished (never rejects). */
     settled(terminalId: string): Promise<void>;

package/dist/codehost/terminals.js

@@ -21,7 +21,7 @@
  */
 import { execFile } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
-import { closeSync, openSync, utimesSync } from 'node:fs';
+import { closeSync, existsSync, openSync, readFileSync, utimesSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { shellQuote } from '../agent/shell.js';
@@ -33,12 +33,13 @@ import { claudeConfigDir, claudeTrusts, trustClaudeWorkspace } from './claude_tr
 import { event } from './events.js';
 import { readHistory } from './history.js';
 import { loginOf, readSession } from './session.js';
+import { codeHostDir, writePrivateJson } from './settings.js';
 import { CODE_THREAD_ID_ENV, TERMINAL_ID_ENV } from './hooks.js';
 import { MAX_OPEN_PTYS } from './pty.js';
 import { beginLaunch, claudeSessionSince, claudeTranscripts, currentLaunch, isReady, LAUNCH_ENV, launchState, markReady, restoreLaunch, } from './ready.js';
 import { defaultSizeArgs, HOLD_OPTION, holdChannel, holdCommand, resizeWindowArgs, TerminalSizing } from './sizing.js';
 import { noteInputTakeover } from './sizing.js';
-import { attachArgs, baseArgs, clampDim, DEFAULT_COLS, DEFAULT_ROWS, hasSessionArgs, isCopyModeExitKey, isHumanInput, isTypedText, isInterruptInput, isScrollGesture, leaveCopyModeArgs, mayEnterCopyMode, paneInModeArgs, isValidId, respawnPaneArgs, killSessionArgs, listWindowsArgs, newSessionArgs, newWindowArgs, parseListWindows, sendTextCommands, setWindowMetaArgs, TERMINAL_WINDOWS, DAEMON_ONLY_ENV, paneEnv, viewSessionName, windowName, windowTarget, } from './tmux.js';
+import { attachArgs, baseArgs, clampDim, DEFAULT_COLS, DEFAULT_ROWS, hasSessionArgs, isCopyModeExitKey, isHumanInput, isTypedText, isInterruptInput, isScrollGesture, leaveCopyModeArgs, mayEnterCopyMode, paneInModeArgs, isValidId, respawnPaneArgs, killSessionArgs, killWindowArgs, listWindowsArgs, newSessionArgs, newWindowArgs, parseListWindows, sendTextCommands, setWindowMetaArgs, TERMINAL_WINDOWS, DAEMON_ONLY_ENV, paneEnv, viewSessionName, windowName, windowTarget, } from './tmux.js';
 export const CODE_AGENTS = ['claude_code', 'codex', 'shell'];
 export const GOAL_ENV = 'PROHOST_CODE_THREAD_GOAL';
 /** Window option set when the agent exits and its window becomes a shell. */
@@ -109,6 +110,31 @@ export const RESTART_STOP_LATER_ATTEMPTS = 4;
 export const RESTART_STOP_LATER_PAUSE_MS = 15_000;
 /** How old a restart may be when it reaches this Mac (the server's `RESTART_MAX_AGE`). */
 export const RESTART_MAX_AGE_MS = 10 * 60_000;
+/**
+ * How long an end may wait to reach this Mac: one that arrives later is refused (`end_expired`), so a
+ * Mac that wakes up the next day never closes a terminal someone has since gone back to. The server
+ * holds the same limit (`END_SESSION_MAX_AGE`).
+ */
+export const END_MAX_AGE_MS = 10 * 60_000;
+/** After its windows close: how long what they ran has to exit on SIGTERM before it is killed. */
+export const END_KILL_GRACE_MS = 2_000;
+/** How far apart two readings of one process's start may be (`ps` gives whole seconds of elapsed time). */
+const PANE_START_SLACK_MS = 2_000;
+/** Two boot times this close are the same boot (`os.uptime` drifts with sleep and rounding). */
+const BOOT_FENCE_MS = 60_000;
+/** When this Mac last booted, in ms. */
+function bootedAtMs() {
+    return Date.now() - os.uptime() * 1000;
+}
+/**
+ * The mark an end leaves (`state/<terminal>.ended`): that terminal is never started or attached again,
+ * whatever comes later (a start whose first ack was lost and is delivered again, a viewer racing the end).
+ */
+export function endedPath(terminalId, env) {
+    if (!isValidId(terminalId))
+        throw new Error('invalid terminal id');
+    return path.join(codeHostDir(env), 'state', `${terminalId}.ended`);
+}
 /**
  * Whether an event post's status settles it (see {@link StartResult}): the
  * server applied it (2xx) or will refuse it the same way every time (404, 409,
@@ -169,6 +195,17 @@ export function agentCommandLine(agent, options) {
     }
     return `PROHOST_INVOCATION_PROTOCOL=0 ${claude} ${shellQuote(settings, 'darwin')}${goal}; ${after}`;
 }
+/** `kill(-pid, signal)`: whether the group still had a process to reach. */
+function signalProcessGroup(pid, signal) {
+    try {
+        process.kill(-pid, signal);
+        return true;
+    }
+    catch {
+        // ESRCH: nothing left in it. EPERM: not ours, never touched.
+        return false;
+    }
+}
 /**
  * A phrase as a first-run screen shows it: Claude Code wraps its own text inside a bordered box (a
  * narrow window breaks it anywhere, and `capture-pane -J` joins only tmux's wraps), so words may be
@@ -233,6 +270,17 @@ export class CodeTerminals {
     lastListUncertain = false;
     /** Each agent window's pane process at the last `adopt`: a restart is confirmed by its changing. */
     panePids = new Map();
+    /** Every thread window's pane process at the last `adopt`, by window name: what an end makes sure exits. */
+    windowPids = new Map();
+    /** Per terminal: how to close each viewer attached to it now (an end closes them before its windows). */
+    viewers = new Map();
+    /** Terminals an end has begun on (set before its first await): no viewer or shell window joins them. */
+    ending = new Set();
+    /**
+     * Per terminal: its window lifecycle (a viewer's shell being made, an end), one at a time. A shell is
+     * made only while no end has begun, and an end runs only once a shell being made exists to close.
+     */
+    lifecycle = new Map();
     /** Who sizes each window, and what its viewers are told (`sizing.ts`). */
     sizing;
     log;
@@ -284,13 +332,17 @@ export class CodeTerminals {
      * terminal never interleave into "first, second, Enter, Enter".
      */
     serialize(terminalId, work) {
-        const previous = this.typing.get(terminalId) ?? Promise.resolve();
+        return this.serializeOn(this.typing, terminalId, work);
+    }
+    /** Run `work` after every earlier job queued in `queues` for this terminal. */
+    serializeOn(queues, terminalId, work) {
+        const previous = queues.get(terminalId) ?? Promise.resolve();
         const next = previous.then(work, work);
         const tail = next.catch(() => undefined);
-        this.typing.set(terminalId, tail);
+        queues.set(terminalId, tail);
         void tail.then(() => {
-            if (this.typing.get(terminalId) === tail)
-                this.typing.delete(terminalId);
+            if (queues.get(terminalId) === tail)
+                queues.delete(terminalId);
         });
         return next;
     }
@@ -355,13 +407,17 @@ export class CodeTerminals {
         if (!listed.ok) {
             // No server or no session: nothing survived, and nothing is wrong.
             this.records.clear();
+            this.windowPids.clear();
             return 0;
         }
         const names = new Set();
         const found = new Map();
         const panes = new Map();
+        const windowPids = new Map();
         for (const window of parseListWindows(listed.stdout)) {
             names.add(window.name);
+            if (window.panePid)
+                windowPids.set(window.name, window.panePid);
             // Left by an earlier daemon, perhaps still holding its shell: released in time all the same.
             this.sizing.adopted(window.name);
             if (window.meta && window.name === windowName(window.meta.terminalId, 'agent')) {
@@ -378,6 +434,7 @@ export class CodeTerminals {
         for (const [id, record] of found)
             this.records.set(id, record);
         this.panePids = panes;
+        this.windowPids = windowPids;
         // Once per daemon start: the windows an older build left behind are all there now. Started by
         // the first call; every call waits for it, so none returns before those windows are marked. A
         // pass that fails (a keychain still locked right after login) never fails an adopt: it is
@@ -471,6 +528,11 @@ export class CodeTerminals {
     }
     async startOnce(request) {
         const reportStart = async () => isDefinitive(await this.options.events.post(request.codeThreadId, event('start', { terminalId: request.terminalId, agent: request.agent, branch: request.branch ?? null }, this.now())));
+        if (this.ended(request.terminalId)) {
+            // Ended from ProhostAI: a start delivered again (its first ack was lost) never brings it back.
+            this.log(`    ◦ code thread ${request.codeThreadId.slice(0, 12)}: not started again, its terminal was ended`);
+            return { ok: false, reason: 'terminal ended', reported: true };
+        }
         await this.adopt();
         // A redelivery (the first outcome never reached the server) reports again.
         if (this.records.has(request.terminalId))
@@ -655,6 +717,210 @@ export class CodeTerminals {
      * (`session_unknown`). An agent that exited into its shell is relaunched all the same.
      * Serialized with the thread's replies, so it never lands between a paste and its Enter.
      */
+    /**
+     * End the thread's terminal session for good (`code_thread.end_requested`): every viewer attached to
+     * it is closed, then its windows (tmux hangs up what they run), then whatever of their process groups
+     * is still there gets SIGTERM, and SIGKILL after {@link END_KILL_GRACE_MS}. Its windows were the
+     * only record of it (`adopt` reads them), so it is never adopted again and drops out of `list()`.
+     * Its folder is left as it is: the work in it is the owner's.
+     *
+     * Idempotent: a terminal this host doesn't have (ended already, closed in tmux, never here) is
+     * ended, and so true. False with `outcome.refused` when it came too late, with `outcome.retry` when
+     * tmux didn't answer in time (nothing known either way: asked again). Queued behind any reply or
+     * restart in flight for it, and after a start of it still running.
+     */
+    async end(request, outcome = {}) {
+        if (!isValidId(request.terminalId) || !isValidId(request.codeThreadId))
+            return false;
+        // Before any await: an attach that hasn't registered its viewer yet sees it and stops.
+        this.ending.add(request.terminalId);
+        try {
+            await this.starting.get(request.terminalId)?.catch(() => undefined);
+            // After any shell a viewer is making for it (`lifecycle`), then any reply or restart (`typing`).
+            return await this.serializeOn(this.lifecycle, request.terminalId, () => this.serialize(request.terminalId, () => this.endNow(request, outcome)));
+        }
+        finally {
+            this.ending.delete(request.terminalId);
+        }
+    }
+    /** Whether an end has begun on, or finished with, this terminal (`ending`, its `.ended` mark). */
+    ended(terminalId) {
+        return this.ending.has(terminalId) || this.hasEndMark(terminalId);
+    }
+    /** Whether an earlier end of this terminal left its `.ended` mark. */
+    hasEndMark(terminalId) {
+        try {
+            return existsSync(endedPath(terminalId, { PROHOST_HOME: this.options.home }));
+        }
+        catch {
+            return false;
+        }
+    }
+    /** This terminal's `.ended` mark as an earlier end left it, or `undefined`. */
+    readMark(terminalId) {
+        try {
+            const mark = JSON.parse(readFileSync(endedPath(terminalId, { PROHOST_HOME: this.options.home }), 'utf8'));
+            return {
+                bootMs: typeof mark.bootMs === 'number' ? mark.bootMs : 0,
+                completed: mark.completed === true,
+                pids: Array.isArray(mark.pids)
+                    ? mark.pids.filter((entry) => typeof entry === 'object' && entry !== null && Number.isInteger(entry.pid) && entry.pid > 1)
+                    : [],
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * The panes an earlier, unfinished end of this terminal left to reap: only from this boot (after a
+     * restart of the Mac every pid is someone else's). Each is checked again before it is signaled.
+     */
+    pendingReap(terminalId) {
+        const mark = this.readMark(terminalId);
+        if (!mark || mark.completed || Math.abs(mark.bootMs - bootedAtMs()) > BOOT_FENCE_MS)
+            return [];
+        return mark.pids;
+    }
+    markEnded(request, pids, completed) {
+        writePrivateJson(endedPath(request.terminalId, { PROHOST_HOME: this.options.home }), {
+            codeThreadId: request.codeThreadId,
+            endedAtMs: this.now(),
+            bootMs: bootedAtMs(),
+            completed,
+            pids,
+        });
+    }
+    async endNow(request, outcome) {
+        const short = request.codeThreadId.slice(0, 12);
+        // Too late to end a terminal someone may have gone back to; but one this host already ended (its
+        // 200 was lost, and the delivery comes again later) has nothing to go back to: finished, and said so.
+        // Only an end that finished: one that stopped partway (tmux didn't answer) is held to the age limit.
+        const endedAlready = this.readMark(request.terminalId)?.completed === true;
+        if (!endedAlready && request.requestedAtMs !== undefined && this.now() - request.requestedAtMs > END_MAX_AGE_MS) {
+            this.log(`    ! code thread ${short}: terminal not ended, the request arrived too late`);
+            outcome.refused = 'end_expired';
+            return false;
+        }
+        await this.adopt();
+        if (this.lastListUncertain) {
+            outcome.retry = true;
+            return false;
+        }
+        const record = this.records.get(request.terminalId);
+        // Another thread's terminal under this id is never touched, nor marked.
+        if (record && record.codeThreadId !== request.codeThreadId) {
+            this.log(`    ◦ code thread ${short}: terminal already ended`);
+            return true;
+        }
+        // Its windows: the record's, and a shell left without its agent window (the agent's closed some
+        // other way, or an earlier end got only that far): `adopt` keeps no record for a shell alone.
+        const windows = record ? [...record.windows] : [];
+        if (!windows.includes('shell') && this.windowPids.has(windowName(request.terminalId, 'shell')))
+            windows.push('shell');
+        // The shell first, the agent window last: the agent window is the record (`adopt`), so one kill that
+        // tmux didn't answer leaves it there for the retry to find, with the shell included if it's still up.
+        const order = [...windows.filter((w) => w !== 'agent'), ...windows.filter((w) => w === 'agent')];
+        const names = order.map((window) => windowName(request.terminalId, window));
+        // What to make sure exits: these windows' panes, as tmux lists them now, and what an earlier attempt
+        // closed but didn't finish reaping (its kill went through, then tmux's answer timed out). Each pane is
+        // saved with when its process started, so a later attempt never signals a pid handed to something else.
+        const listed = names.map((name) => this.windowPids.get(name)).filter((pid) => pid !== undefined);
+        const starts = await this.startsOf(listed);
+        const fresh = listed.map((pid) => ({ pid, ...(starts.has(pid) ? { startedAtMs: starts.get(pid) } : {}) }));
+        const saved = this.pendingReap(request.terminalId).filter((entry) => !listed.includes(entry.pid));
+        const pids = [...fresh, ...saved];
+        // Marked first, whether or not it is here, with those pids: whatever happens to the kills below,
+        // nothing starts or attaches it again (a start delivered late, or again after a lost ack), and a
+        // retry still reaps what they ran.
+        try {
+            this.markEnded(request, pids, false);
+        }
+        catch (err) {
+            this.log(`    ! code thread ${short}: couldn't record its end (${err instanceof Error ? err.message : String(err)})`);
+            outcome.retry = true;
+            return false;
+        }
+        for (const closeViewer of [...(this.viewers.get(request.terminalId) ?? [])])
+            closeViewer();
+        this.viewers.delete(request.terminalId);
+        for (const name of names) {
+            const killed = await this.tmux(killWindowArgs(name));
+            // A window already gone is what was asked; one tmux didn't answer for may still be there.
+            if (!killed.ok && killed.uncertain) {
+                outcome.retry = true;
+                return false;
+            }
+            this.windowPids.delete(name);
+        }
+        this.records.delete(request.terminalId);
+        this.panePids.delete(request.terminalId);
+        this.lastInterrupt.delete(request.terminalId);
+        await this.reapGroups(fresh.map((entry) => entry.pid), await this.stillOurs(saved));
+        try {
+            // Finished and reaped: nothing left for a retry to signal, and a late redelivery is answered ended.
+            this.markEnded(request, [], true);
+        }
+        catch {
+            /* the mark stays with its pids; only a recent one is ever reaped again */
+        }
+        this.log(`    ■ code thread ${short}: terminal ${names.length > 0 ? 'ended' : 'already ended'}`);
+        return true;
+    }
+    /**
+     * What a closed window ran and didn't exit on its hangup (a process ignoring SIGHUP, a child in its
+     * group): SIGTERM, then SIGKILL past {@link END_KILL_GRACE_MS}. Only each pane's own process group:
+     * never a process that left it on purpose (`setsid`, a daemon it started).
+     */
+    async reapGroups(fresh, saved = []) {
+        const signal = this.options.signalGroup ?? signalProcessGroup;
+        const left = [...new Set([...fresh, ...saved])].filter((pid) => signal(pid, 'SIGTERM'));
+        if (left.length === 0)
+            return;
+        const deadline = this.now() + END_KILL_GRACE_MS;
+        while (this.now() < deadline && left.some((pid) => signal(pid, 0)))
+            await this.sleep(100);
+        for (const pid of left)
+            if (signal(pid, 0))
+                signal(pid, 'SIGKILL');
+    }
+    /** When each of `pids` started (`paneStarts`); empty when `ps` couldn't say. */
+    async startsOf(pids) {
+        if (pids.length === 0)
+            return new Map();
+        try {
+            return await (this.options.paneStarts ?? paneStarts)(pids);
+        }
+        catch {
+            return new Map();
+        }
+    }
+    /**
+     * Of panes an earlier attempt saved, those whose process group is still this terminal's. A group
+     * outlives its leader, and a pid is never handed out while a group of that id exists: so one whose
+     * leader pid runs no process now is ours if anything is left in it. One whose pid runs a process is
+     * ours only if that process started when the saved one did; one with no saved start, or when `ps`
+     * can't say, is left alone.
+     */
+    async stillOurs(saved) {
+        if (saved.length === 0)
+            return [];
+        let starts;
+        try {
+            starts = await (this.options.paneStarts ?? paneStarts)(saved.map((entry) => entry.pid));
+        }
+        catch {
+            return [];
+        }
+        return saved
+            .filter((entry) => {
+            const now = starts.get(entry.pid);
+            if (now === undefined)
+                return true;
+            return entry.startedAtMs !== undefined && Math.abs(now - entry.startedAtMs) <= PANE_START_SLACK_MS;
+        })
+            .map((entry) => entry.pid);
+    }
     async restart(request, outcome = {}, hooks = {}) {
         if (!isValidId(request.terminalId) || !isValidId(request.codeThreadId))
             return false;
@@ -1155,6 +1421,8 @@ export class CodeTerminals {
     async attach(request) {
         if (!TERMINAL_WINDOWS.has(request.window))
             return { ok: false, reason: 'invalid_window' };
+        if (this.ended(request.terminalId))
+            return { ok: false, reason: 'unknown_terminal' };
         const record = await this.known(request.terminalId);
         if (!record)
             return { ok: false, reason: 'unknown_terminal' };
@@ -1165,10 +1433,17 @@ export class CodeTerminals {
         if (this.openPtys >= MAX_OPEN_PTYS)
             return { ok: false, reason: 'busy' };
         const size = { cols: clampDim(request.cols, DEFAULT_COLS), rows: clampDim(request.rows, DEFAULT_ROWS) };
-        if (request.window === 'shell' && !(await this.ensureShellWindow(record, size))) {
+        if (request.window === 'shell' &&
+            // Made under the terminal's lifecycle: never once an end has begun, and an end waits for it (and so
+            // finds it to close).
+            !(await this.serializeOn(this.lifecycle, record.terminalId, async () => this.ended(record.terminalId) ? false : this.ensureShellWindow(record, size)))) {
             return { ok: false, reason: 'unknown_terminal' };
         }
         const name = windowName(record.terminalId, request.window);
+        // An end began while this attach waited (`ending` is set before its first await): nothing joins it.
+        // From here to the viewer's registration nothing waits, so a later end finds this viewer to close.
+        if (this.ended(record.terminalId))
+            return { ok: false, reason: 'unknown_terminal' };
         const view = viewSessionName();
         let pty;
         try {
@@ -1208,11 +1483,20 @@ export class CodeTerminals {
             while (earlyBytes > MAX_EARLY_OUTPUT_BYTES && early.length > 1)
                 earlyBytes -= early.shift().length;
         });
+        // Closes this viewer and tells it the terminal is gone (an end): registered below.
+        const ended = () => {
+            close();
+            notifyExit();
+        };
         const close = () => {
             if (closed)
                 return;
             closed = true;
             this.openPtys -= 1;
+            const open = this.viewers.get(record.terminalId);
+            open?.delete(ended);
+            if (open?.size === 0)
+                this.viewers.delete(record.terminalId);
             sizer.leave();
             try {
                 pty.kill();
@@ -1223,11 +1507,21 @@ export class CodeTerminals {
             // destroy-unattached normally reaps it; this covers a pty killed before tmux attached.
             void this.tmux(killSessionArgs(view));
         };
-        pty.onExit(() => {
-            close();
+        let exitNotified = false;
+        const notifyExit = () => {
+            if (exitNotified)
+                return;
+            exitNotified = true;
             for (const listener of exitListeners)
                 listener();
+        };
+        pty.onExit(() => {
+            close();
+            notifyExit();
         });
+        const open = this.viewers.get(record.terminalId) ?? new Set();
+        open.add(ended);
+        this.viewers.set(record.terminalId, open);
         const isAgent = request.window === 'agent';
         let tookOver = false;
         /** A clear is queued and its result not yet known. */

package/dist/codehost/tmux.d.ts

@@ -125,6 +125,8 @@ export declare const DAEMON_ONLY_ENV: readonly ["ELECTRON_RUN_AS_NODE", "PROHOST
 /** {@link utf8Env}, without {@link DAEMON_ONLY_ENV}: the env every tmux this host runs gets. */
 export declare function paneEnv<T extends Record<string, string | undefined>>(env: T): T;
 export declare function killSessionArgs(viewName: string): string[];
+/** argv (after {@link baseArgs}) that closes one of a thread's windows, killing what its pane runs (tmux hangs it up). */
+export declare function killWindowArgs(name: string): string[];
 /**
  * Text relayed from a composer, as tmux commands: C0 control characters other
  * than newline and tab are dropped — a reply is text, never a key sequence —

package/dist/codehost/tmux.js

@@ -243,6 +243,10 @@ export function paneEnv(env) {
 export function killSessionArgs(viewName) {
     return ['kill-session', '-t', `=${viewName}`];
 }
+/** argv (after {@link baseArgs}) that closes one of a thread's windows, killing what its pane runs (tmux hangs it up). */
+export function killWindowArgs(name) {
+    return ['kill-window', '-t', windowTarget(name)];
+}
 /**
  * Text relayed from a composer, as tmux commands: C0 control characters other
  * than newline and tab are dropped — a reply is text, never a key sequence —

package/dist/host/command.js

@@ -520,6 +520,21 @@ export function serviceStillLoaded(spec, serviceIo, pidAlive = processAlive) {
         return true;
     }
 }
+/** How long a give-back waits for an uninstalled service to finish stopping. */
+const GIVE_BACK_WAIT_MS = 30_000;
+/** Whether `spec`'s service is gone, waiting up to {@link GIVE_BACK_WAIT_MS} for it to stop. */
+function waitUntilGone(spec, serviceIo) {
+    const now = serviceIo.now ?? Date.now;
+    const sleep = serviceIo.sleep ?? ((ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms));
+    const deadline = now() + GIVE_BACK_WAIT_MS;
+    for (;;) {
+        if (!serviceStillLoaded(spec, serviceIo))
+            return true;
+        if (now() >= deadline)
+            return false;
+        sleep(500);
+    }
+}
 function processAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -766,7 +781,18 @@ export async function runHost(subcommand, flags, printHelp, io = {}) {
                 for (const o of shown)
                     (o.ok ? out : err)(o.message);
                 let ok = shown.every((o) => o.ok);
-                if (note && fromHome && outcomes.some((o) => o.label === note.handed_to.label && o.ok)) {
+                // The key goes back at once: the service's definition is gone, so a later run could never
+                // find it again, and a key left only in its home (an interrupted wait, say) would be stranded.
+                // Uninstall ignores a stop that failed (`launchctl bootout`, `systemctl disable --now`), so the
+                // service may still be draining its runs on the old copy: that is waited for (bounded) only
+                // afterwards, to say so.
+                const handedSpec = note && handedTo ? { ...spec, label: note.handed_to.label, home: handedTo.home } : undefined;
+                // Its definition removed (its task deleted), whatever else failed after: on Windows a copy of
+                // the key that couldn't be deleted makes uninstall report not ok, yet the task is gone, and
+                // no later run could find the key again. Those failures still fail this command (`ok`).
+                const definitionGone = (o) => o.ok || o.message.includes('✓ Removed');
+                const handedOutcome = note ? outcomes.find((o) => o.label === note.handed_to.label && definitionGone(o)) : undefined;
+                if (note && fromHome && handedOutcome) {
                     const key = handedKeyLive;
                     if (key && key.computer_id === note.computer_id && handedTo) {
                         const problem = rewriteHomeCredential(platform, fromHome, `${JSON.stringify(key, null, 2)}\n`, io.serviceIo);
@@ -777,17 +803,28 @@ export async function runHost(subcommand, flags, printHelp, io = {}) {
                         else {
                             // On Windows the (administrators') service home keeps its copy: a later dedicated
                             // install finds that home and writes nothing into it, so it must still hold the key.
-                            if (platform !== 'win32')
-                                clearHandedHome(platform, handedTo.home, 'its key', io.serviceIo ?? {}, err);
+                            const cleared = platform === 'win32' || clearHandedHome(platform, handedTo.home, 'its key', io.serviceIo ?? {}, err);
+                            if (!cleared) {
+                                // Back here, and still there: the same key in two homes. Not done until that copy goes.
+                                ok = false;
+                                err(`  ✗ The key is back in ${fromHome} but also still in ${handedTo.home}: delete that copy before using either.`);
+                            }
                             out(`  The computer's key is back in ${fromHome}: prohost host install runs it there (prohost host unpair removes it).`);
                             if (platform === 'win32')
                                 out(`  To install it as a dedicated service again, first remove the folder ${handedTo.home}.`);
                         }
                     }
                     else {
-                        clearHandedHome(platform, fromHome, 'the note', io.serviceIo ?? {}, err);
+                        if (!clearHandedHome(platform, fromHome, 'the note', io.serviceIo ?? {}, err))
+                            ok = false;
                         out(`  ${fromHome} no longer points at ${note.handed_to.label}. Its key was not found: add the computer again with prohost host pair, or remove it on its page in ProhostAI.`);
                     }
+                    // Only now (the key is where it belongs): whether the service really stopped, bounded.
+                    if (handedSpec && !waitUntilGone(handedSpec, io.serviceIo ?? {})) {
+                        ok = false;
+                        err(`  ! ${note.handed_to.label} was still stopping after ${GIVE_BACK_WAIT_MS / 1000}s: wait until it has exited ` +
+                            `(${platform === 'darwin' ? `sudo launchctl print system/${note.handed_to.label}` : platform === 'win32' ? 'Task Manager' : `systemctl status ${systemdUnitOf(handedSpec)}`}) before running this computer from ${fromHome}.`);
+                    }
                 }
                 return ok ? 0 : 1;
             }
@@ -815,8 +852,17 @@ export async function runHost(subcommand, flags, printHelp, io = {}) {
                 (env.SUDO_USER && !env.PROHOST_HOME ? homeOfUser(platform, env.SUDO_USER) : ownHome);
             // The key this install takes over, read before it runs: only a copy it really made is retired.
             const handedFrom = dedicated && path.resolve(adoptFrom) !== path.resolve(home) ? tryLoadComputer({ ...env, PROHOST_HOME: adoptFrom }) : null;
-            // Whether the service home already held a key before this install (then it copies none).
-            const serviceHadKey = handedFrom ? serviceCredential(platform, home, serviceUser, io.serviceIo ?? {}, spec.label) !== null : false;
+            // The key the service home already holds, read before this install (then it copies none in).
+            const serviceBefore = handedFrom ? serviceCredential(platform, home, serviceUser, io.serviceIo ?? {}, spec.label) : null;
+            // Another computer's: installing would restart that computer under this label and leave this
+            // one's key where it is, reported as a takeover. Refused before anything is installed.
+            if (handedFrom && serviceBefore && serviceBefore.computer_id !== handedFrom.computer_id) {
+                err(`✗ ${home} already holds the key of another computer ("${serviceBefore.name}", ${serviceBefore.computer_id}), not ` +
+                    `${adoptFrom}'s ("${handedFrom.name}"): nothing was installed. Remove that computer first ` +
+                    `(sudo prohost host unpair --label ${spec.label}), then install again.`);
+                return 1;
+            }
+            const serviceHadKey = serviceBefore !== null;
             const outcome = installService(spec, io.serviceIo, {
                 ...(tokenFile ? { claudeTokenFile: tokenFile } : {}),
                 ...(dedicated ? { adoptFrom } : {}),
@@ -828,6 +874,38 @@ export async function runHost(subcommand, flags, printHelp, io = {}) {
                     ? `  ! ${home} has no computer yet (none in ${adoptFrom}): pair as yourself, then run this again — or pass --from-home <your PROHOST_HOME>.`
                     : `  This home (${home}) has no computer yet: run prohost host pair.`);
             }
+            // Undo this install (it copied a key in): the service uninstalled, every copy of the key it made
+            // removed, and the original home keeps its key. Returns the exit code.
+            const undoInstall = (options = { removeKeys: true }) => {
+                const undone = (() => {
+                    try {
+                        return uninstallService(spec, io.serviceIo, { keepKeyCopy: !options.removeKeys });
+                    }
+                    catch (e) {
+                        return { ok: false, message: e instanceof Error ? e.message : String(e) };
+                    }
+                })();
+                // Removed and no longer loaded, not just "nothing failed": a Windows task that would not
+                // stop removes nothing, and a launchd / systemd service whose stop failed may still run.
+                // (Not `undone.ok`: on Windows uninstall reports a key copy it couldn't remove as not ok
+                // although the task is gone — that copy is named by removeCopiedKeys below.)
+                const serviceGone = undone.message.includes('✓ Removed') && !serviceStillLoaded(spec, io.serviceIo ?? {});
+                if (!options.removeKeys) {
+                    // Which file this install copied can't be told from one it didn't: no credential is deleted.
+                    err(serviceGone
+                        ? `  ✗ ${spec.label} is uninstalled. Check ${path.join(home, 'host', 'computer.json')} before installing again; ${adoptFrom} keeps its key.`
+                        : `  ✗ Could not uninstall ${spec.label}: remove it (sudo prohost host uninstall --label ${spec.label}), then check ${path.join(home, 'host', 'computer.json')}.`);
+                    return 1;
+                }
+                const leftover = serviceGone ? removeCopiedKeys(spec, io.serviceIo ?? {}) : [];
+                err(serviceGone && leftover.length === 0
+                    ? `  ✗ Undone: ${spec.label} is uninstalled and ${home} holds no key; ${adoptFrom} keeps its key. Fix the problem above, then ` +
+                        (platform === 'win32' ? `remove the folder ${home} and install again.` : 'install again.')
+                    : serviceGone
+                        ? `  ✗ Partly undone: ${spec.label} is uninstalled, but its key is still in ${leftover.join(' and ')}: delete it yourself — never run \`prohost host unpair\` from ${adoptFrom} meanwhile.`
+                        : `  ✗ Could not fully undo it: remove ${spec.label} (sudo prohost host uninstall --label ${spec.label}) and ${path.join(home, 'host', 'computer.json')} yourself — never run \`prohost host unpair\` from ${adoptFrom} meanwhile.`);
+                return 1;
+            };
             if (outcome.ok && dedicated && handedFrom) {
                 // One key, one holder: the home it came from keeps a note of where the computer went, never
                 // the key — so an `unpair`, `pair` or personal `install` there can't revoke or run it twice.
@@ -868,27 +946,7 @@ export async function runHost(subcommand, flags, printHelp, io = {}) {
                             return 1;
                         }
                         else if (!serviceHadKey) {
-                            const undone = (() => {
-                                try {
-                                    return uninstallService(spec, io.serviceIo);
-                                }
-                                catch (e) {
-                                    return { ok: false, message: e instanceof Error ? e.message : String(e) };
-                                }
-                            })();
-                            // Removed and no longer loaded, not just "nothing failed": a Windows task that would not
-                            // stop removes nothing, and a launchd / systemd service whose stop failed may still run.
-                            // (Not `undone.ok`: on Windows uninstall reports a key copy it couldn't remove as not ok
-                            // although the task is gone — that copy is named by removeCopiedKeys below.)
-                            const serviceGone = undone.message.includes('✓ Removed') && !serviceStillLoaded(spec, io.serviceIo ?? {});
-                            const leftover = serviceGone ? removeCopiedKeys(spec, io.serviceIo ?? {}) : [];
-                            err(serviceGone && leftover.length === 0
-                                ? `  ✗ Undone: ${spec.label} is uninstalled and ${home} holds no key; ${adoptFrom} keeps its key. Fix the problem above, then ` +
-                                    (platform === 'win32' ? `remove the folder ${home} and install again.` : 'install again.')
-                                : serviceGone
-                                    ? `  ✗ Partly undone: ${spec.label} is uninstalled, but its key is still in ${leftover.join(' and ')}: delete it yourself — never run \`prohost host unpair\` from ${adoptFrom} meanwhile.`
-                                    : `  ✗ Could not fully undo it: remove ${spec.label} (sudo prohost host uninstall --label ${spec.label}) and ${path.join(home, 'host', 'computer.json')} yourself — never run \`prohost host unpair\` from ${adoptFrom} meanwhile.`);
-                            return 1;
+                            return undoInstall();
                         }
                         else {
                             err(`  ✗ ${home} already held this key before this install, so ${adoptFrom} still does too: never run \`prohost host unpair\` from that home. ` +
@@ -901,6 +959,20 @@ export async function runHost(subcommand, flags, printHelp, io = {}) {
                         out(`  The computer's key is the service's alone now: ${adoptFrom} keeps a note of where it went.`);
                     }
                 }
+                else if (!serviceHadKey) {
+                    // The copy this install made isn't there afterwards (or can't be read, or is another
+                    // computer's): no takeover happened, and the service must not run on whatever it holds.
+                    // Uninstalled; its files are left for a person to judge.
+                    err(`  ✗ ${spec.label} was installed, but ${home} does not hold ${adoptFrom}'s key afterwards ` +
+                        (serviceHas ? `(it holds ${serviceHas.computer_id}).` : "(it can't be read)."));
+                    return undoInstall({ removeKeys: false });
+                }
+                else {
+                    // It held this computer's key before the install and can't be read now: never reported done.
+                    err(`  ✗ ${home} held this computer's key before this install, but it can't be read now: check ` +
+                        `${path.join(home, 'host', 'computer.json')}, and never run \`prohost host unpair\` from ${adoptFrom} meanwhile.`);
+                    return 1;
+                }
             }
             if (outcome.ok && dedicated) {
                 out(`  Its status, for anyone on this computer: ${sharedDirFor(spec)}`);

package/dist/host/install.d.ts

@@ -219,6 +219,12 @@ export declare function aclPrincipals(icaclsOutput: string, dir: string): string
 /** The files a dedicated service publishes in its shared folder, and the pause switch. */
 export declare const SHARED_FILES: readonly ["state.json", "activity.json", "events.json"];
 export declare function installService(spec: ServiceSpec, io?: InstallIo, setup?: DedicatedSetup): InstallOutcome;
-export declare function uninstallService(spec: ServiceSpec, io?: InstallIo): InstallOutcome;
+/**
+ * `keepKeyCopy`: on Windows, leave the administrators' copy of the key (an install undoing itself
+ * that can't tell a copy it made from one it found keeps it for a person to judge).
+ */
+export declare function uninstallService(spec: ServiceSpec, io?: InstallIo, options?: {
+    keepKeyCopy?: boolean;
+}): InstallOutcome;
 /** Where a dedicated service user's `PROHOST_HOME` is by default. */
 export declare function serviceUserHome(platform: NodeJS.Platform, user: string): string;

package/dist/host/install.js

@@ -1002,7 +1002,13 @@ export function installService(spec, io = {}, setup = {}) {
         return { ok: false, file, message: `Created ${task}, but ${failed('schtasks /Run', start)}` };
     return { ok: true, file, message: `✓ Installed the ${task} task\n  logs: ${logs}` };
 }
-export function uninstallService(spec, io = {}) {
+/** `schtasks /Query /HResult`'s exit for a task that doesn't exist: HRESULT 0x80070002, signed or unsigned. */
+const TASK_NOT_FOUND = new Set([0x80070002, 0x80070002 - 0x100000000]);
+/**
+ * `keepKeyCopy`: on Windows, leave the administrators' copy of the key (an install undoing itself
+ * that can't tell a copy it made from one it found keeps it for a person to judge).
+ */
+export function uninstallService(spec, io = {}, options = {}) {
     const run = io.run ?? defaultServiceRunner;
     const remove = io.removeFile ?? ((file) => rmSync(file, { force: true }));
     const exists = io.exists ?? existsSync;
@@ -1048,13 +1054,30 @@ export function uninstallService(spec, io = {}) {
         const out = run('schtasks', ['/Delete', '/TN', task, '/F']);
         if (out.status === 0)
             removed.push(task);
-        for (const file of [serviceFilePath(spec), windowsWrapperPath(spec)]) {
-            if (exists(file))
-                remove(file);
+        // A delete that failed is a failure, never "nothing installed", unless the task is confirmed
+        // absent (Task Scheduler says it can't find it): the task can start again on its key. An error
+        // that can't tell (the scheduler not answering) counts as still there. Its files stay, so a
+        // later uninstall still finds it.
+        // `/HResult` makes the exit code the HRESULT, whatever the system's language: a task that isn't
+        // there is ERROR_FILE_NOT_FOUND (0x80070002), seen signed or unsigned. The English text is kept
+        // for a schtasks without the switch.
+        const query = out.status === 0 ? undefined : run('schtasks', ['/Query', '/TN', task, '/HResult']);
+        const confirmedAbsent = query !== undefined &&
+            query.status !== 0 &&
+            (TASK_NOT_FOUND.has(query.status ?? 0) || /cannot find|does not exist/i.test(`${query.stderr} ${query.stdout}`));
+        const stillThere = out.status !== 0 && !confirmedAbsent;
+        if (stillThere) {
+            notes.push(`could not delete the task ${task} (${(out.stderr || out.stdout || `exit ${out.status}`).trim()}): it is still installed`);
+        }
+        else {
+            for (const file of [serviceFilePath(spec), windowsWrapperPath(spec)]) {
+                if (exists(file))
+                    remove(file);
+            }
         }
         // The administrators' copy of its key goes with the service: a reinstall never finds an old one.
         const copy = windowsServiceCredentialPath(spec);
-        if (out.status === 0 && exists(copy)) {
+        if (out.status === 0 && !options.keepKeyCopy && exists(copy)) {
             try {
                 remove(copy);
             }

package/dist/host/service.js

@@ -38,7 +38,7 @@ import { HeartbeatLoop } from '../agent/heartbeat.js';
 import { executeHostedRun } from '../agent/run.js';
 import { SessionStore, sessionKeyFor } from '../agent/sessionstore.js';
 import { verifySignature } from '../agent/signature.js';
-import { CODE_THREAD_FOLDERS_CAPABILITY, CODE_THREAD_RESTART_SKIP_PERMISSIONS_CAPABILITY, CODE_THREAD_SKIP_PERMISSIONS_CAPABILITY, CODE_THREADS_CAPABILITY, CodeHost, EVENT_CODE_THREAD_APPROVAL_DECIDED, EVENT_CODE_THREAD_INPUT_REQUESTED, EVENT_CODE_THREAD_RESTART_REQUESTED, EVENT_CODE_THREAD_START_REQUESTED, REMOTE_TERMINAL_CAPABILITY, RefusedDeliveryError, } from '../codehost/host.js';
+import { CODE_THREAD_FOLDERS_CAPABILITY, CODE_THREAD_END_SESSION_CAPABILITY, CODE_THREAD_RESTART_SKIP_PERMISSIONS_CAPABILITY, CODE_THREAD_SKIP_PERMISSIONS_CAPABILITY, CODE_THREADS_CAPABILITY, CodeHost, EVENT_CODE_THREAD_APPROVAL_DECIDED, EVENT_CODE_THREAD_INPUT_REQUESTED, EVENT_CODE_THREAD_END_REQUESTED, EVENT_CODE_THREAD_RESTART_REQUESTED, EVENT_CODE_THREAD_START_REQUESTED, REMOTE_TERMINAL_CAPABILITY, RefusedDeliveryError, } from '../codehost/host.js';
 import { HostStatsSampler } from '../codehost/host_stats.js';
 import { TERMINAL_SESSIONS_ENV, loadSettings as loadCodeHostSettings, recordServiceSwitch } from '../codehost/settings.js';
 import { isWebhookEvent } from '../forward.js';
@@ -258,6 +258,9 @@ async function serveHost(options) {
         if (codeHost?.authorized() && config.terminal_sessions_enabled) {
             caps.push(CODE_THREADS_CAPABILITY, CODE_THREAD_FOLDERS_CAPABILITY, codeHost.instanceCapability());
             caps.push(...(codeHost.agentCapabilities?.() ?? []));
+            // Ending a thread's terminal (`code_thread.end_requested`): whatever the remote switch says.
+            if (codeHost.handleEnd)
+                caps.push(CODE_THREAD_END_SESSION_CAPABILITY);
             if (codeHost.remoteTerminalAllowed()) {
                 caps.push(REMOTE_TERMINAL_CAPABILITY, CODE_THREAD_SKIP_PERMISSIONS_CAPABILITY);
                 // Relaunching a running thread's agent without prompts (`code_thread.restart_requested`): the same rule.
@@ -998,7 +1001,8 @@ async function serveHost(options) {
                 if (frame.event === EVENT_CODE_THREAD_START_REQUESTED ||
                     frame.event === EVENT_CODE_THREAD_INPUT_REQUESTED ||
                     frame.event === EVENT_CODE_THREAD_APPROVAL_DECIDED ||
-                    frame.event === EVENT_CODE_THREAD_RESTART_REQUESTED) {
+                    frame.event === EVENT_CODE_THREAD_RESTART_REQUESTED ||
+                    frame.event === EVENT_CODE_THREAD_END_REQUESTED) {
                     if (!codeHost || !config.terminal_sessions_enabled) {
                         ack(ACK_IGNORED);
                         return;
@@ -1032,7 +1036,9 @@ async function serveHost(options) {
                             ? codeHost.handleInput(data, frame.delivery_id)
                             : frame.event === EVENT_CODE_THREAD_RESTART_REQUESTED
                                 ? (codeHost.handleRestart?.(data, frame.delivery_id) ?? Promise.resolve(false))
-                                : codeHost.handleApproval(data, frame.delivery_id);
+                                : frame.event === EVENT_CODE_THREAD_END_REQUESTED
+                                    ? (codeHost.handleEnd?.(data) ?? Promise.resolve(false))
+                                    : codeHost.handleApproval(data, frame.delivery_id);
                     background.push(handled
                         .then((ok) => {
                         ack(starting || ok ? ACK_ACCEPTED : ACK_IGNORED);

package/dist/version.d.ts

@@ -7,6 +7,6 @@
  * `package.json`, so a release bump that forgets this file fails the suite
  * instead of shipping a `User-Agent` that lies about which build is calling.
  */
-export declare const CLI_VERSION = "0.16.7";
+export declare const CLI_VERSION = "0.16.10";
 /** Sent on every HTTP request the CLI makes back into ProhostAI. */
-export declare const USER_AGENT = "prohost-cli/0.16.7";
+export declare const USER_AGENT = "prohost-cli/0.16.10";

package/dist/version.js

@@ -7,6 +7,6 @@
  * `package.json`, so a release bump that forgets this file fails the suite
  * instead of shipping a `User-Agent` that lies about which build is calling.
  */
-export const CLI_VERSION = '0.16.7';
+export const CLI_VERSION = '0.16.10';
 /** Sent on every HTTP request the CLI makes back into ProhostAI. */
 export const USER_AGENT = `prohost-cli/${CLI_VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prohost/cli",
-  "version": "0.16.7",
+  "version": "0.16.10",
   "description": "Run your own AI agent as a ProhostAI teammate, and stream your account's webhooks to your laptop.",
   "type": "module",
   "license": "MIT",