@timurproko/a1 0.2.7-dev.1241 → 0.2.7-dev.1245

package/README.md

@@ -113,13 +113,19 @@ a1 tabs doctor
 
 ## Update
 
-Install the release:
+Update on the channel you already use (release stays on release, develop stays on develop):
 
 ```text
 a1 update
 ```
 
-Install develop:
+Switch to the release:
+
+```text
+a1 update --release
+```
+
+Switch to develop:
 
 ```text
 a1 update --develop
@@ -159,6 +165,22 @@ The **Update** setting controls release discovery:
 
 <p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/readme/separator-dark.svg"><img src="docs/assets/readme/separator.svg" alt="" width="280"></picture></p>
 
+## Uninstall
+
+Remove A1 from this machine. It stops running tabs and asks before deleting your sessions and settings in `~/.a1`:
+
+```text
+a1 uninstall
+```
+
+Remove everything without questions:
+
+```text
+a1 uninstall --yes --purge
+```
+
+<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/readme/separator-dark.svg"><img src="docs/assets/readme/separator.svg" alt="" width="280"></picture></p>
+
 ## Extensions
 
 Install a package:

package/bin/cli.js

@@ -73,6 +73,23 @@ process.exitCode = await dispatchCli(process.argv.slice(2), {
     const { runTabsCommand } = await import("../dist/cli/tabs.js");
     return await runTabsCommand(request, { packageRoot: fileURLToPath(packageRoot) });
   },
+  uninstall: async request => {
+    const [{ runUninstall }, { createInterface }] = await Promise.all([
+      import("../dist/cli/uninstall.js"),
+      import("node:readline/promises"),
+    ]);
+    const interactive = process.stdin.isTTY === true && process.stdout.isTTY === true;
+    return await runUninstall(request, {
+      packageRoot: fileURLToPath(packageRoot),
+      output: { stdout: message => process.stdout.write(message), stderr: message => process.stderr.write(message) },
+      ...(interactive ? {
+        confirm: async question => {
+          const prompt = createInterface({ input: process.stdin, output: process.stdout });
+          try { return /^y(?:es)?$/iu.test((await prompt.question(question)).trim()); } finally { prompt.close(); }
+        },
+      } : {}),
+    });
+  },
 }, {
   stdout: message => process.stdout.write(message),
   stderr: message => process.stderr.write(message),

package/dist/app/session-shell/dock-chrome.js

@@ -1,7 +1,7 @@
 import { COPY_ACKNOWLEDGEMENT_DURATION_MS } from "../../ui/components/selection-copy.js";
 import { renderPiShellCommandMessage, renderPiShellReleaseUpdateBanner, renderPiShellStatusText, } from "../../integrations/pi/components/shell-presenters-info.js";
 import { PINNED_PI_LAYOUT, piTheme } from "../../integrations/pi/components/upstream/theme/theme.js";
-import { piShellTruncateToWidth, renderPiShellBlockedUpdateStatus, renderPiShellInstalledUpdateStatus } from "../../integrations/pi/components/shell-shared-facade.js";
+import { piShellTruncateToWidth, renderPiShellInstalledUpdateStatus } from "../../integrations/pi/components/shell-shared-facade.js";
 import { parseReleaseUpdateDiagnostic } from "./transcript-document.js";
 /**
  * The transient chrome around bare A1's dock: the one command notice above the editor, the release
@@ -87,9 +87,6 @@ export class DockChrome {
         if (diagnostics.some(diagnostic => diagnostic.code === "release-update-installed")) {
             return renderPiShellInstalledUpdateStatus(width) || undefined;
         }
-        if (diagnostics.some(diagnostic => diagnostic.code === "release-update-blocked")) {
-            return renderPiShellBlockedUpdateStatus(width) || undefined;
-        }
         return undefined;
     }
     renderReleaseBanner(diagnostics, width) {

package/dist/cli/capabilities.d.ts

@@ -1,6 +1,8 @@
 /** The Pi comparison launch is a prerelease development instrument, not product. */
 export interface CliCapabilities {
     readonly developmentComparison: boolean;
+    /** Bare `update` stays on this build's channel; absent means stable. */
+    readonly runningChannel?: "stable" | "next";
 }
 export declare function cliCapabilities(version: string): CliCapabilities;
 export declare function isPrereleaseVersion(version: string): boolean;

package/dist/cli/capabilities.js

@@ -1,6 +1,7 @@
 import { prerelease } from "semver";
 export function cliCapabilities(version) {
-    return Object.freeze({ developmentComparison: isPrereleaseVersion(version) });
+    const development = isPrereleaseVersion(version);
+    return Object.freeze({ developmentComparison: development, runningChannel: development ? "next" : "stable" });
 }
 export function isPrereleaseVersion(version) {
     return (prerelease(version)?.length ?? 0) > 0;

package/dist/cli/dispatch.d.ts

@@ -12,6 +12,11 @@ export interface CliHandlers {
     readonly packages: (request: PackageCommandRequest) => Promise<number>;
     readonly sessionContext: (request: SessionContextRequest) => Promise<number>;
     readonly tabs: (request: TabsRequest) => Promise<number>;
+    /** Removes A1 from the machine; absent in hosts that cannot uninstall. */
+    readonly uninstall?: (request: {
+        readonly yes: boolean;
+        readonly purge: boolean;
+    }) => Promise<number>;
 }
 export interface CliOutput {
     readonly stdout: (message: string) => void;
@@ -56,6 +61,12 @@ export type CliCommand = {
     readonly request: TabsRequest;
 } | {
     readonly kind: "tabs-help";
+} | {
+    readonly kind: "uninstall";
+    readonly request: {
+        readonly yes: boolean;
+        readonly purge: boolean;
+    };
 } | {
     readonly kind: "error";
     readonly message: string;

package/dist/cli/dispatch.js

@@ -13,12 +13,14 @@ export function cliUsage(capabilities) {
         "help",
         "version",
         "update",
+        "update --release",
         "update --develop [preview-or-version]",
         "update --models",
         "update --extensions",
         "update <source>",
         "install <source>",
         "remove <source>",
+        "uninstall [--yes] [--purge]",
         "uninstall <source>",
         "list",
         "session worktrees",
@@ -46,6 +48,7 @@ export function cliHelp(capabilities) {
         "",
         "Update:",
         `  ${command} update`,
+        `  ${command} update --release`,
         `  ${command} update --develop [preview-or-version]`,
         `  ${command} update --models`,
         `  ${command} update --extensions`,
@@ -54,6 +57,7 @@ export function cliHelp(capabilities) {
         "Packages:",
         `  ${command} install <source>`,
         `  ${command} remove <source>`,
+        `  ${command} uninstall [--yes] [--purge]`,
         `  ${command} uninstall <source>`,
         `  ${command} list`,
         "",
@@ -122,6 +126,8 @@ export async function dispatchCli(arguments_, handlers, output, capabilities) {
     }
     if (command.kind === "tabs")
         return await handlers.tabs(command.request);
+    if (command.kind === "uninstall")
+        return handlers.uninstall ? await handlers.uninstall(command.request) : 2;
     return await handlers.update(command.channel, command.target);
 }
 export function parseCliCommand(arguments_, capabilities) {
@@ -141,6 +147,11 @@ export function parseCliCommand(arguments_, capabilities) {
         return withoutArguments(rest, { kind: "help" });
     if (command === "version" || command === "--version" || command === "-v")
         return withoutArguments(rest, { kind: "version" });
+    // Compatibility: a source keeps `uninstall` as package removal; without one it removes A1.
+    if (command === "uninstall" && rest.every(value => value === "--yes" || value === "--purge")
+        && new Set(rest).size === rest.length) {
+        return { kind: "uninstall", request: { yes: rest.includes("--yes"), purge: rest.includes("--purge") } };
+    }
     if (command === "install" || command === "remove" || command === "uninstall" || command === "list") {
         return parsePackageCommand(arguments_, "direct");
     }
@@ -161,7 +172,7 @@ export function parseCliCommand(arguments_, capabilities) {
         }
     }
     if (command === "update")
-        return parseUpdate(rest);
+        return parseUpdate(rest, capabilities.runningChannel ?? "stable");
     if (command === "session")
         return parseSessionContext(rest);
     if (command === "tabs")
@@ -224,17 +235,22 @@ function parseSessionContext(rest) {
     return { kind: "error", message: PRODUCT_TEXT.diagnostic("session accepts worktrees, link-worktree <path>, or unlink-worktree.") };
 }
 /**
- * Stable update is the empty form. `--develop` selects the moving development
- * head or one immutable numbered preview, while model refresh remains a separate
- * operation that cannot be combined with either update channel.
+ * The empty form stays on the running channel; `--release` moves to stable. `--develop` selects
+ * the moving development head or one immutable numbered preview, while model refresh remains a
+ * separate operation that cannot be combined with either update channel.
  */
-function parseUpdate(rest) {
+function parseUpdate(rest, runningChannel) {
     if (rest.some(value => value === "--help" || value === "-h")) {
         return { kind: "package-help", verb: "update", namespace: "direct" };
     }
     if (rest.length === 0)
-        return { kind: "update", channel: "stable" };
+        return { kind: "update", channel: runningChannel };
     const [selector, ...values] = rest;
+    if (selector === "--release") {
+        if (values.length > 0)
+            return updateGrammarError("--release cannot be combined with another update selector.");
+        return { kind: "update", channel: "stable" };
+    }
     // Compatibility: removed notation is unsupported rather than deprecated.
     if (selector === "self")
         return { kind: "noop" };

package/dist/cli/package-messages.js

@@ -37,6 +37,7 @@ export function packageCommandHelp(verb, namespace = "pi", style = chalk) {
     const header = verb === "update" && namespace === "direct"
         ? `${style.bold("Usage:")}\n`
             + `  ${command} update\n`
+            + `  ${command} update --release\n`
             + `  ${command} update --develop [preview-or-version]\n`
             + `  ${command} update --models\n`
             + `  ${command} update --extensions\n`
@@ -58,7 +59,7 @@ Examples:
         case "remove":
             return header + `Remove a package and its source from settings.
 Alias: ${command} uninstall <source>
-
+${namespace === "direct" ? `\nRemove A1 from this machine (sessions and settings stay unless --purge):\n  ${command} uninstall [--yes] [--purge]\n` : ""}
 Examples:
   ${command} remove npm:@foo/bar
   ${command} uninstall npm:@foo/bar
@@ -70,11 +71,11 @@ Examples:
             return header + `${namespace === "direct" ? "Update A1, installed packages, or model catalogs." : "Update installed packages or model catalogs."}
 
 Options:
-${namespace === "direct" ? "  --develop [target]     Update to develop or one preview\n" : ""}  --extensions            Update installed packages only
+${namespace === "direct" ? "  --release              Update to the release\n  --develop [target]     Update to develop or one preview\n" : ""}  --extensions            Update installed packages only
   --models                Refresh model catalogs only
 
 Short forms:
-${namespace === "direct" ? `  ${command} update                Update A1 to the release\n  ${command} update --develop      Update A1 to develop\n` : ""}  ${command} update --extensions   Update installed packages only
+${namespace === "direct" ? `  ${command} update                Update A1 on its current channel\n  ${command} update --release      Update A1 to the release\n  ${command} update --develop      Update A1 to develop\n` : ""}  ${command} update --extensions   Update installed packages only
   ${command} update --models       Refresh model catalogs only
   ${command} update <source>       Update one package
 

package/dist/cli/session-context.js

@@ -29,7 +29,7 @@ export async function runSessionContextCommand(request, options = {}) {
     }
     catch (error) {
         const code = errorCode(error);
-        const detail = error instanceof Error ? error.message : String(error);
+        const detail = recoveryDetail(code) ?? (error instanceof Error ? error.message : String(error));
         stderr(`${PRODUCT_TEXT.diagnostic(`could not update session context${code === null ? "" : ` (${code})`}: ${detail}`)}\n`);
         return 1;
     }
@@ -42,6 +42,23 @@ function readIdentity(environment) {
         return null;
     return { sessionId, sessionFile, runtimeId };
 }
+/** Known coordination failures must not expose native paths or another session's identity. */
+function recoveryDetail(code) {
+    const details = {
+        "worktree-claim-busy": "another mutation is still running; runtime registration retries automatically, so retry this link shortly",
+        "worktree-legacy-recovery-required": "an older-format worktree lock requires safe recovery; stop all older A1 processes, move only session-worktree-claims/mutation.lock to a backup while stopped, then start the updated A1; keep all sessions and worktree claims",
+        "worktree-coordination-unavailable": "native worktree coordination is unavailable; repair or update this A1 installation, then retry",
+        "worktree-coordination-io": "worktree coordination could not access its files; check A1 data-directory permissions and filesystem availability, then retry",
+        "worktree-coordination-boundary": "unexpected worktree coordination entry; retain it for inspection, and do not delete the claim store",
+        "process-inspection-unavailable": "native process inspection is unavailable; repair the A1 installation before retrying; no ownership was overridden",
+        "session-runtime-unverifiable": "runtime identity could not be verified; check native process inspection and retry; no ownership was overridden",
+        "session-runtime-unavailable": "this session has not registered yet; updated A1 retries registration automatically; retry shortly and follow any specific coordination error if it persists",
+        "session-runtime-stopped": "this shell belongs to a stopped runtime; resume in a running A1 session before linking",
+        "worktree-active-in-another-session": "another live agent owns this worktree; use a different worktree or wait for its owner to release it",
+        "worktree-owner-unverifiable": "worktree ownership cannot be verified; retain the claim and use another worktree rather than forcing recovery",
+    };
+    return code === null ? undefined : details[code];
+}
 function errorCode(error) {
     if (error instanceof Error && "code" in error && typeof error.code === "string")
         return error.code;

package/dist/cli/uninstall.d.ts

@@ -0,0 +1,30 @@
+import { type ProductPaths } from "../foundation/lifecycle/index.js";
+export interface UninstallRequest {
+    /** Skips the program-removal question; user data is still kept unless `purge` is set. */
+    readonly yes: boolean;
+    /** Also removes sessions, settings, sign-ins, and prompt history. */
+    readonly purge: boolean;
+}
+export interface UninstallOutput {
+    readonly stdout: (message: string) => void;
+    readonly stderr: (message: string) => void;
+}
+export interface UninstallDependencies {
+    readonly packageRoot: string;
+    readonly output: UninstallOutput;
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+    readonly home?: string;
+    /** Asks one yes/no question; absent when no terminal can answer. */
+    readonly confirm?: (question: string) => Promise<boolean>;
+    readonly stopResidentHost?: (releaseRoot: string, paths: ProductPaths, profileRoot: string) => Promise<void>;
+    readonly stopSupervisors?: (paths: ProductPaths) => Promise<void>;
+    readonly removePackage?: (packageRoot: string, environment: NodeJS.ProcessEnv) => Promise<void>;
+    readonly remove?: (path: string) => Promise<void>;
+}
+/**
+ * Removes A1 from this machine: resident hosts and supervisors stop first, through each
+ * release's own maintenance contract, then the global package and every A1-owned state root go.
+ * Sessions and settings live in the profile home and leave only with explicit consent.
+ */
+export declare function runUninstall(request: UninstallRequest, dependencies: UninstallDependencies): Promise<number>;

package/dist/cli/uninstall.js

@@ -0,0 +1,117 @@
+import { spawn } from "node:child_process";
+import { readdir, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, parse, resolve, sep } from "node:path";
+import { resolveLaunchProfilePaths } from "../features/launch/index.js";
+import { resolveProductPaths } from "../foundation/lifecycle/index.js";
+import { cleanupVerifiedOwner, listRecordedEndpoints, npmPrefixForGlobalRoot, resolveNpmCli } from "../foundation/release/index.js";
+import { runTerminalHostMaintenance } from "../foundation/resident-tabs/index.js";
+import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../product-identity.js";
+/**
+ * Removes A1 from this machine: resident hosts and supervisors stop first, through each
+ * release's own maintenance contract, then the global package and every A1-owned state root go.
+ * Sessions and settings live in the profile home and leave only with explicit consent.
+ */
+export async function runUninstall(request, dependencies) {
+    const { output } = dependencies;
+    const environment = dependencies.environment ?? process.env;
+    const command = PRODUCT_TEXT.commandName;
+    if (environment[PRODUCT_IDENTITY.environment.tabId] !== undefined) {
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`${command} uninstall stops every tab, including this one. Run it from a terminal outside ${command}.`)}\n`);
+        return 1;
+    }
+    const globalRoot = managedGlobalRoot(dependencies.packageRoot);
+    if (globalRoot === null) {
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`${command} uninstall removes only an installed ${command}; this one runs from ${dependencies.packageRoot}.`)}\n`);
+        return 1;
+    }
+    const platform = dependencies.platform ?? process.platform;
+    const paths = resolveProductPaths(environment, platform);
+    const profileHome = resolveLaunchProfilePaths({ environment, platform, ...(dependencies.home === undefined ? {} : { home: dependencies.home }) }).managedStateRoot;
+    let purge = request.purge;
+    if (!request.yes) {
+        if (dependencies.confirm === undefined) {
+            output.stderr(`${PRODUCT_TEXT.diagnostic(`${command} uninstall needs a terminal to confirm. Run ${command} uninstall --yes to remove it.`)}\n`);
+            return 2;
+        }
+        if (!await dependencies.confirm(`Remove ${command} from this machine? Running Agents will stop. [y/N] `)) {
+            output.stdout(`${command} was not removed\n`);
+            return 1;
+        }
+        purge ||= await dependencies.confirm(`Also delete your sessions, settings, and sign-ins in ${profileHome}? [y/N] `);
+    }
+    const profileRoot = environment[PRODUCT_IDENTITY.environment.profileHome] ?? paths.configDir;
+    const stopResidentHost = dependencies.stopResidentHost ?? stopReleaseResidentHost;
+    for (const releaseRoot of await installedReleaseRoots(paths.dataDir)) {
+        await stopResidentHost(releaseRoot, paths, profileRoot).catch(() => undefined);
+    }
+    await (dependencies.stopSupervisors ?? stopRecordedSupervisors)(paths).catch(() => undefined);
+    try {
+        await (dependencies.removePackage ?? removeGlobalPackage)(dependencies.packageRoot, environment);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`${command} uninstall could not remove the package: ${reason}. Run npm uninstall --global ${PRODUCT_IDENTITY.packageName}, then ${command} uninstall again.`)}\n`);
+        return 1;
+    }
+    const remove = dependencies.remove ?? (async (path) => await rm(path, { recursive: true, force: true }));
+    const home = dependencies.home ?? environment.HOME ?? environment.USERPROFILE ?? homedir();
+    const owned = [paths.dataDir, paths.configDir, paths.runtimeDir, paths.endpointDirectory, ...(purge ? [profileHome] : [])];
+    for (const path of new Set(owned.filter((value) => value !== null))) {
+        if (removable(path, home))
+            await remove(path);
+    }
+    output.stdout(purge ? `${command} uninstalled\n` : `${command} uninstalled; your sessions and settings remain in ${profileHome}\n`);
+    return 0;
+}
+/** The npm global `node_modules` that holds this package, or null outside a managed install. */
+function managedGlobalRoot(packageRoot) {
+    const root = resolve(packageRoot);
+    const scope = dirname(root);
+    const modules = dirname(scope);
+    const [scopeName, packageName] = PRODUCT_IDENTITY.packageName.split("/");
+    return root.endsWith(`${sep}${packageName}`) && scope.endsWith(`${sep}${scopeName}`) && modules.endsWith(`${sep}node_modules`)
+        ? modules
+        : null;
+}
+/** Invariant: a state-root override never turns removal into deleting a home or volume root. */
+function removable(path, home) {
+    const target = resolve(path);
+    return target !== parse(target).root && target !== resolve(home) && !resolve(home).startsWith(`${target}${sep}`);
+}
+async function installedReleaseRoots(dataDir) {
+    const releases = resolve(dataDir, "releases");
+    const names = await readdir(releases).catch(() => []);
+    return names.map(name => resolve(releases, name));
+}
+async function stopReleaseResidentHost(releaseRoot, paths, profileRoot) {
+    // Invariant: each release stops only its own namespace, through its own verified host.
+    await runTerminalHostMaintenance({
+        action: "host-stop", profileRoot, dataDir: paths.dataDir, runtimeDir: paths.runtimeDir,
+        releaseRoots: [releaseRoot], environment: process.env, timeoutMs: 30_000,
+    });
+}
+async function stopRecordedSupervisors(paths) {
+    for (const endpoint of await listRecordedEndpoints(paths)) {
+        await cleanupVerifiedOwner(endpoint.metadata, { allowLiveInstances: true }).catch(() => undefined);
+    }
+}
+async function removeGlobalPackage(packageRoot, environment) {
+    const globalRoot = managedGlobalRoot(packageRoot);
+    if (globalRoot === null)
+        throw new Error("A1 is not a managed global installation");
+    const prefix = npmPrefixForGlobalRoot(globalRoot);
+    const npmCli = await resolveNpmCli(globalRoot, environment);
+    const code = await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(process.execPath, [npmCli, "uninstall", "--global", "--prefix", prefix,
+            "--loglevel=error", "--no-fund", "--no-audit", PRODUCT_IDENTITY.packageName], {
+            env: { ...environment, NO_UPDATE_NOTIFIER: "1", npm_config_update_notifier: "false" },
+            stdio: ["ignore", "ignore", "inherit"],
+            windowsHide: true,
+        });
+        child.once("error", rejectPromise);
+        child.once("close", value => resolvePromise(value ?? 1));
+    });
+    if (code !== 0)
+        throw new Error(`npm could not remove ${PRODUCT_IDENTITY.packageName} (exit ${code})`);
+}

package/dist/composition/release-update-observation.js

@@ -76,6 +76,8 @@ class ReleaseUpdateObservation {
                 const clientVersion = input.clientVersion?.();
                 if (version !== null && clientVersion && !releases.isNewerRelease(version, clientVersion))
                     return;
+                if (version !== null)
+                    this.#nextDelay = module.AUTOMATIC_UPDATE_ACTIVATION_RETRY_MS;
                 this.#announce(version === null ? "blocked-cleared" : "blocked", version ?? release.version);
             },
         }));

package/dist/composition/session-runtime-registry.d.ts

@@ -1,20 +1,17 @@
 import type { NativeProcessIdentity } from "../foundation/lifecycle/model.js";
 export interface SessionRuntimeRegistryOptions {
-    /** This runtime's id from the environment; absent outside a runtime that claims worktrees. */
+    /** Absent outside claim-owning runtimes. */
     readonly runtimeId: string | undefined;
-    /** Exact native process inspection; absent SDK seams publish no claims. */
+    /** Exact native inspection; absent SDK seams cannot claim. */
     readonly inspectProcess: ((pid: number) => Promise<NativeProcessIdentity | null>) | undefined;
     readonly refreshMs?: number;
 }
-/**
- * The live worktree claims this runtime's agents hold: each agent's session identity, the heartbeat
- * that keeps the claims fresh, and their release when the runtime is disposed.
- */
+/** Lifecycle-owned publication and retries for each agent's current session, serialized with disposal. */
 export declare class SessionRuntimeRegistry {
     #private;
     constructor(options: SessionRuntimeRegistryOptions);
     /** The repository context reader for one agent; undefined names the primary agent. */
     readerFor(agentId: string | undefined): (sessionId: string, sessionFile: string, signal: AbortSignal) => Promise<import("../foundation/lifecycle/session-repository-context.js").SessionRepositoryContext | null>;
-    /** Stops the heartbeat, waits for an in-flight refresh, and releases every claim this runtime holds. */
+    /** Drain publication before releasing claims; never republish after disposal. */
     dispose(): Promise<void>;
 }

package/dist/composition/session-runtime-registry.js

@@ -1,47 +1,49 @@
-const SESSION_RUNTIME_REFRESH_MS = 30_000;
-/**
- * The live worktree claims this runtime's agents hold: each agent's session identity, the heartbeat
- * that keeps the claims fresh, and their release when the runtime is disposed.
- */
+/** Lifecycle-owned publication and retries for each agent's current session, serialized with disposal. */
 export class SessionRuntimeRegistry {
     #options;
-    // Invariant: one entry per agent of this runtime; each agent holds its own claim, and the runtime's exit releases all.
     #identities = new Map();
+    #abort = new AbortController();
     #owner = null;
     #timer = null;
-    #refresh = Promise.resolve();
+    #work = Promise.resolve();
+    #refreshPending = false;
     #disposed = false;
-    constructor(options) {
-        this.#options = options;
-    }
+    constructor(options) { this.#options = options; }
     /** The repository context reader for one agent; undefined names the primary agent. */
     readerFor(agentId) {
         return async (sessionId, sessionFile, signal) => {
             const { runtimeId, inspectProcess } = this.#options;
-            const owner = await this.#ownerIdentity();
-            if (owner === null || runtimeId === undefined || inspectProcess === undefined)
+            if (this.#disposed || runtimeId === undefined || inspectProcess === undefined)
                 return null;
             const identity = { sessionId, sessionFile };
             this.#identities.set(agentId, identity);
-            const { activateSessionRepositoryContext } = await import("../foundation/lifecycle/session-repository-context.js");
-            const context = await activateSessionRepositoryContext(identity, runtimeId, owner, {
-                signal,
-                inspectProcess,
-                ...(agentId === undefined ? {} : { agentId }),
-            });
+            // Invariant: initial activation or inspection failure must not disable retries.
             this.#arm();
-            return context;
+            return await this.#enqueue(async () => {
+                const owner = await this.#ownerIdentity();
+                if (owner === null || !this.#current(agentId, identity))
+                    return null;
+                const { activateSessionRepositoryContext } = await import("../foundation/lifecycle/session-repository-context.js");
+                if (!this.#current(agentId, identity))
+                    return null;
+                return await activateSessionRepositoryContext(identity, runtimeId, owner, {
+                    signal: AbortSignal.any([signal, this.#abort.signal]),
+                    inspectProcess,
+                    ...(agentId === undefined ? {} : { agentId }),
+                });
+            });
         };
     }
-    /** Stops the heartbeat, waits for an in-flight refresh, and releases every claim this runtime holds. */
+    /** Drain publication before releasing claims; never republish after disposal. */
     async dispose() {
         this.#disposed = true;
+        this.#abort.abort();
         if (this.#timer !== null)
             clearInterval(this.#timer);
         this.#timer = null;
-        await this.#refresh;
+        await this.#work;
         const { runtimeId } = this.#options;
-        const owner = await this.#ownerIdentity();
+        const owner = await this.#owner;
         if (runtimeId === undefined || owner === null)
             return;
         await import("../foundation/lifecycle/session-repository-context.js")
@@ -49,37 +51,51 @@ export class SessionRuntimeRegistry {
             .catch(() => undefined);
     }
     async #ownerIdentity() {
-        const { runtimeId, inspectProcess } = this.#options;
-        if (runtimeId === undefined || inspectProcess === undefined)
+        const { inspectProcess } = this.#options;
+        if (this.#disposed || inspectProcess === undefined)
             return null;
-        this.#owner ??= inspectProcess(process.pid).catch(() => null);
-        return await this.#owner;
+        const pending = this.#owner ??= Promise.resolve().then(() => inspectProcess(process.pid))
+            .then(owner => owner?.pid === process.pid && owner.startIdentity.length > 0 ? owner : null)
+            .catch(() => null);
+        const owner = await pending;
+        // Performance: cache success, not failure.
+        if (owner === null && this.#owner === pending)
+            this.#owner = null;
+        return owner;
+    }
+    #current(agentId, identity) {
+        return !this.#disposed && this.#identities.get(agentId) === identity;
+    }
+    #enqueue(operation) {
+        const next = this.#work.then(operation);
+        this.#work = next.then(() => undefined, () => undefined);
+        return next;
     }
     #arm() {
         if (this.#timer !== null)
             return;
-        this.#timer = setInterval(() => this.#queueRefresh(), this.#options.refreshMs ?? SESSION_RUNTIME_REFRESH_MS);
+        this.#timer = setInterval(() => this.#queueRefresh(), this.#options.refreshMs ?? 30_000);
         this.#timer.unref();
     }
     #queueRefresh() {
         const { runtimeId, inspectProcess } = this.#options;
-        if (this.#disposed || this.#identities.size === 0 || runtimeId === undefined || inspectProcess === undefined)
+        if (this.#disposed || this.#refreshPending || runtimeId === undefined || inspectProcess === undefined)
             return;
-        this.#refresh = this.#refresh.then(async () => {
-            if (this.#disposed)
-                return;
+        this.#refreshPending = true;
+        void this.#enqueue(async () => {
             const owner = await this.#ownerIdentity();
-            if (owner === null)
+            if (owner === null || this.#disposed)
                 return;
             const { registerSessionRepositoryRuntime } = await import("../foundation/lifecycle/session-repository-context.js");
             for (const [agentId, identity] of this.#identities) {
-                if (this.#disposed)
-                    return;
+                if (!this.#current(agentId, identity))
+                    continue;
                 await registerSessionRepositoryRuntime(identity, runtimeId, owner, {
                     inspectProcess,
+                    signal: this.#abort.signal,
                     ...(agentId === undefined ? {} : { agentId }),
                 }).catch(() => undefined);
             }
-        }).catch(() => undefined);
+        }).catch(() => undefined).finally(() => { this.#refreshPending = false; });
     }
 }

package/dist/foundation/launch-guardian/exit-watcher.js

@@ -13,19 +13,28 @@ export async function runExitWatcher(arguments_, platform = process.platform, lo
     }
     try {
         await addon.waitForProcessExit(options.guardianPid);
-        if (platform === "win32") {
-            // Rationale: job termination is asynchronous; keep the runtime's final frame ahead of the notice.
-            await Promise.race([
-                addon.waitForProcessExit(options.runtimePid),
-                delay(2_000),
-            ]);
+        let cleanupFailure = null;
+        try {
+            if (platform === "win32") {
+                // Rationale: job termination is asynchronous; keep the runtime's final frame ahead of the notice.
+                await Promise.race([
+                    addon.waitForProcessExit(options.runtimePid),
+                    delay(2_000),
+                ]);
+            }
+            else if (options.processGroup !== null) {
+                addon.stopProcessGroup(options.processGroup);
+                if (options.foregroundGroup !== null)
+                    addon.restoreForegroundGroup(options.foregroundGroup);
+            }
         }
-        else if (options.processGroup !== null) {
-            addon.stopProcessGroup(options.processGroup);
-            if (options.foregroundGroup !== null)
-                addon.restoreForegroundGroup(options.foregroundGroup);
+        catch (error) {
+            cleanupFailure = error;
         }
+        // Invariant: an armed notice, such as the running-Agent reminder, survives a failed cleanup.
         addon.deliverExitNotice(options.noticePath, options.encodedModes);
+        if (cleanupFailure !== null)
+            throw cleanupFailure;
         return 0;
     }
     finally {