@phnx-labs/agents-cli 1.22.65 → 1.22.68

package/dist/lib/browser/ipc.d.ts

@@ -4,24 +4,24 @@ import type { IPCRequest, IPCResponse } from './types.js';
 export interface IPCRequestOptions {
     autoStartDaemon?: boolean;
 }
-export declare class BrowserDaemonNotRunningError extends Error {
+export declare class BrowserServiceNotRunningError extends Error {
     constructor();
 }
-export declare function formatBrowserDaemonNotRunningError(): string;
+export declare function formatBrowserServiceNotRunningError(daemonRunning?: boolean): string;
 export declare function getSocketPath(): string;
 /** Is the daemon reachable? A real connect probe on every platform — a socket
  * file existing on disk is not proof a daemon is listening on it. */
-export declare function isDaemonReachable(): Promise<boolean>;
+export declare function isBrowserServiceReachable(): Promise<boolean>;
 /**
  * Is a *reachable* daemon actually responsive, or is its event loop wedged
- * (PHNX-3411)? Retries {@link probeDaemonResponsive} up to
+ * (PHNX-3411)? Retries {@link probeBrowserServiceResponsive} up to
  * {@link RESPONSIVENESS_PROBE_ATTEMPTS} times so a single transient miss (a GC
  * pause) never condemns a healthy daemon; returns true as soon as any attempt
  * gets a reply, and false only when every attempt fails.
  */
-export declare function isDaemonResponsive(endpoint?: string, attempts?: number): Promise<boolean>;
+export declare function isBrowserServiceResponsive(endpoint?: string, attempts?: number): Promise<boolean>;
 /**
- * Wait until the browser daemon is genuinely reachable, or throw.
+ * Wait until the browser service is genuinely reachable, or throw.
  *
  * Re-probes across the whole window rather than latching on the first accept, so
  * it survives an IPC-server restart that happens mid-wait (PHNX-3289): a restart
@@ -30,32 +30,35 @@ export declare function isDaemonResponsive(endpoint?: string, attempts?: number)
  * that never comes up throws a message naming the endpoint and the budget, never
  * a silent hang.
  */
-export declare function waitForSocket(_socketPath: string, timeoutMs?: number): Promise<void>;
-/** Outcome of {@link resetBrowserDaemon} — what the wedge-recovery actually did. */
-export interface BrowserDaemonResetResult {
-    /** The daemon was reachable before the reset and a stop was issued. */
+export declare function waitForBrowserService(_socketPath: string, timeoutMs?: number): Promise<void>;
+/** Outcome of {@link stopBrowserService} — what the service-scoped stop did. */
+export interface BrowserServiceStopResult {
+    /** The browser IPC service was reachable before the stop was requested. */
     wasRunning: boolean;
+    /** The shared daemon stayed running while only browser IPC was stopped. */
+    daemonRunning: boolean;
     /** A leftover `browser.sock` file was unlinked (POSIX only). */
     socketCleared: boolean;
 }
 /**
- * Clear a wedged browser daemon so a subsequent `start` comes up clean
- * (PHNX-3289). Stops the shared daemon (the same `stopDaemon` path
- * `reconcileDaemonVersion` uses for a stale-version restart), waits for the IPC
- * endpoint to stop accepting, then unlinks any stale `browser.sock` a
- * hard-crashed daemon left behind — the file a fresh `start` would otherwise
- * `unlink` blindly, racing whatever still holds it.
+ * Stop only the daemon-hosted browser IPC service so a subsequent `start` comes
+ * up clean (PHNX-3605). The short-lived browser client persists the
+ * `browser-ipc` service off and asks the daemon to apply that transition over
+ * its existing SIGHUP control path. It never stops or restarts the shared
+ * supervisor, so routines, usage sync, secrets, and every sibling service keep
+ * their process and in-flight work.
  *
- * Fails loud: if the endpoint is *still* reachable after the quiesce window, a
- * live server is holding it and clearing the socket under it would orphan two
- * servers on one path, so we throw rather than pretend the reset worked. The
- * daemon auto-restarts on the next browser command.
+ * Once the endpoint is quiet, a stale socket left by a hard-crashed browser
+ * service is removed. If the daemon event loop itself is wedged and cannot
+ * consume SIGHUP, the endpoint remains reachable and this fails loud with the
+ * deliberate operator-owned whole-daemon restart command; the client never
+ * escalates into that process-wide action itself.
  */
-export declare function resetBrowserDaemon(): Promise<BrowserDaemonResetResult>;
+export declare function stopBrowserService(): Promise<BrowserServiceStopResult>;
 /**
  * Remove a leftover browser socket FILE, but only when nothing is listening on
  * it — re-probing liveness IMMEDIATELY before the unlink to close the TOCTOU
- * window (PHNX-3289 review). Between {@link resetBrowserDaemon}'s quiesce loop
+ * window (PHNX-3289 review). Between {@link stopBrowserService}'s quiesce loop
  * deciding the endpoint was unreachable and this unlink, a concurrent
  * `browser start` could bind a NEW listener on the same path; an unconditional
  * unlink would then delete a LIVE daemon's socket — the exact two-servers orphan
@@ -65,7 +68,7 @@ export declare function resetBrowserDaemon(): Promise<BrowserDaemonResetResult>;
  */
 export declare function clearDeadSocketFile(endpoint: string, socketPath: string): Promise<boolean>;
 /**
- * One long-lived connection to the existing browser daemon. Requests are
+ * One long-lived connection to the existing browser service. Requests are
  * serialized so the daemon's newline-delimited responses always map to the
  * caller that produced them, while the process and socket stay warm between
  * actions.
@@ -85,6 +88,8 @@ export declare class BrowserIPCConnection {
 }
 export declare class BrowserIPCServer {
     private server;
+    /** Filesystem identity of the POSIX binding this server created. */
+    private socketIdentity;
     private service;
     /** Live client connections, so {@link stop} can end them rather than wait. */
     private connections;
@@ -128,21 +133,21 @@ export declare class BrowserIPCServer {
     private handleRequest;
 }
 /**
- * Decide whether a running daemon is stale and must be restarted.
+ * Decide whether a running daemon is stale enough to name an operator refresh.
  *
- * FORWARD ONLY: restart when the daemon is *older* than this CLI so a newer
- * install loads current code. An older CLI rides a newer daemon instead of
- * evicting it — two installs sharing one daemon dir (keyed off $HOME) must
- * not flap the daemon indefinitely.
+ * FORWARD ONLY: recommend a refresh when the daemon is *older* than this CLI.
+ * An older CLI rides a newer daemon without noise. A client never performs the
+ * refresh itself — two installs sharing one daemon dir (keyed off $HOME) must
+ * not flap the daemon or interrupt one another's hosted services.
  *
  * `undefined`/`'unknown'` means the daemon is too old to answer the `version`
- * action reliably — don't churn it on that ambiguous signal.
+ * action reliably — don't recommend an action on that ambiguous signal.
  *
  * When numeric compare cannot order two distinct strings (e.g. two
- * `0.0.0-dev.*` builds), treat the mismatch as a restart so a concrete
- * code change still loads.
+ * `0.0.0-dev.*` builds), surface the mismatch without deciding either client
+ * owns the shared process.
  */
-export declare function shouldRestartStaleDaemon(daemonVersion: string | undefined, clientVersion: string): boolean;
+export declare function shouldRecommendDaemonRefresh(daemonVersion: string | undefined, clientVersion: string): boolean;
 export declare function sendIPCRequest(request: IPCRequest, opts?: IPCRequestOptions): Promise<IPCResponse>;
 /**
  * Fill actor / launchId / sessionId from the calling process when the request