@cline/core 0.0.81 → 0.0.82

package/dist/hub/daemon/index.d.ts

@@ -51,3 +51,75 @@ export interface DetachedHubResolution {
 export declare function ensureDetachedHubServer(workspaceRoot: string, endpointOverrides?: HubEndpointOverrides & {
     allowPortFallback?: boolean;
 }): Promise<DetachedHubResolution>;
+export interface UpgradeManagedHubOptions {
+    workspaceRoot?: string;
+    /**
+     * How long to wait, after draining, for the hub's live sessions to finish
+     * before replacing it (`force`) or giving up (`still_busy`).
+     */
+    waitForIdleMs?: number;
+    /**
+     * Replace the hub even if sessions are still live once the wait expires.
+     * Only set this on a user-consented path: those sessions die mid-turn.
+     * Honored only once the hub has accepted the drain - a busy hub that
+     * refused the drain is never replaced, because the drain is what protects
+     * work started during the wait window.
+     */
+    force?: boolean;
+    /** Recorded as the hub's drain reason, visible in `hub.status`. */
+    reason?: string;
+}
+export type UpgradeManagedHubOutcome = 
+/** The running older hub was retired and a current-build hub is up. */
+"replaced"
+/** No live hub was found; a current-build hub was started. */
+ | "started"
+/** The running hub already matches this build; nothing to do. */
+ | "already_current"
+/**
+ * The running hub is newer than (or unorderable against) this build.
+ * Replacing it would downgrade another install's hub and reopen the
+ * mutual-retire loop (#13145), so it is refused; updating this client is
+ * the fix.
+ */
+ | "hub_not_older"
+/** `force` was not set and sessions never finished - or the hub's
+ * activity could never be confirmed, which counts as busy here; the hub
+ * was un-drained and left running. */
+ | "still_busy";
+export interface UpgradeManagedHubResult {
+    outcome: UpgradeManagedHubOutcome;
+    url?: string;
+    authToken?: string;
+    /**
+     * Live sessions observed on the old hub at decision time: the sessions
+     * that were interrupted (`replaced`) or that kept it running
+     * (`still_busy`). Omitted when the hub never answered the activity query.
+     */
+    activeSessionCount?: number;
+}
+/**
+ * Replace the managed local hub with one running this build, on the user's
+ * explicit say-so. This is the deliberate counterpart to the automatic
+ * replacement in `ensureDetachedHubServer`, which defers while the older hub
+ * is serving sessions: drain first (the hub refuses new work while in-flight
+ * turns get `waitForIdleMs` to finish), then the shared graceful retire
+ * ladder, then a fresh daemon. Drain-first is a guarantee, not a courtesy:
+ * this function retires a hub only under an accepted drain, because the
+ * drain is the admission barrier that keeps any busy or idle reading true
+ * through the retire. A hub that refuses the drain fails the upgrade
+ * outright - `force` does not override that, and neither does an idle
+ * reading, which without the drain is only a snapshot that a newly admitted
+ * session could invalidate before the retire lands. (Such a hub is still
+ * replaced by the automatic ensure path once idle at the next client
+ * startup, the pre-existing recovery route for hubs too old to serve
+ * /drain.) Activity readings that fail are treated as unknown, not idle:
+ * they never shorten the wait window, and without `force` an unconfirmed
+ * hub is handed back un-drained rather than retired.
+ *
+ * Never replaces a hub this build is not strictly newer than - the build
+ * total order guarantees at most one side of any install pair can reach the
+ * retire step, which is what keeps two mixed installs from taking turns
+ * "upgrading" the hub to their own build.
+ */
+export declare function upgradeManagedHub(options?: UpgradeManagedHubOptions): Promise<UpgradeManagedHubResult>;