@snutils/snu 0.2.2 → 0.2.5

package/dist/cli/attachment.d.ts

@@ -0,0 +1,60 @@
+import { HealthResponse } from '../types.js';
+/**
+ * How an MCP server (or any client) should obtain a bridge.
+ *
+ * The old rule was "if discovery fails, take port 1978 and start our own". That
+ * conflates two very different failures. Discovery fails when the *descriptor*
+ * is missing, stale, or clobbered — which says nothing about whether a bridge
+ * is running. A healthy standalone bridge started by another MCP client whose
+ * port file had been removed was therefore stopped and replaced, which is the
+ * "multiple MCP clients reclaim each other's ports" failure exactly.
+ *
+ * A running bridge is proven by its health endpoint, not by a file. So an
+ * undiscoverable-but-serving bridge is attached to, never displaced; only a
+ * port held by something that answers nothing may be reclaimed.
+ *
+ * Pure decision logic with injected probes: no sockets, no process control.
+ */
+export type AttachmentMode = 
+/** Found through the normal port-descriptor path. */
+'attached-discovered'
+/** Serving, but its descriptor was missing or stale. Attached anyway. */
+ | 'attached-undiscoverable'
+/** No bridge was serving; this process must start one. */
+ | 'create-standalone';
+export interface BridgeAttachment {
+    mode: AttachmentMode;
+    /** HTTP port of the bridge to talk to, when one was found. */
+    port?: number;
+    pid?: number;
+    hostKind?: string;
+    /** Human-readable explanation, surfaced in MCP startup logs and diagnostics. */
+    reason: string;
+    /**
+     * True only when the caller is allowed to reclaim a held port before
+     * binding. Never true while any bridge is answering.
+     */
+    mayReclaimPorts: boolean;
+}
+export interface AttachmentProbes {
+    /** Normal discovery. Should reject the way discoverBridge does. */
+    discover: () => Promise<{
+        port: number;
+        pid: number;
+    } | undefined>;
+    /** Probe a port's health endpoint; undefined when nothing healthy answers. */
+    probeHealth: (port: number) => Promise<HealthResponse | undefined>;
+    /** Ports to check when discovery fails, in order. */
+    candidatePorts?: number[];
+}
+export declare const DEFAULT_HTTP_PORT = 1977;
+/**
+ * Decide how to obtain a bridge, without changing anything.
+ *
+ * Discovery failures that mean "no bridge" and failures that mean "a bridge is
+ * running but is not registered" are deliberately handled the same way here:
+ * both fall through to a health probe, because only the probe can tell them
+ * apart.
+ */
+export declare function resolveBridgeAttachment(probes: AttachmentProbes): Promise<BridgeAttachment>;
+//# sourceMappingURL=attachment.d.ts.map

package/dist/cli/attachment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment.d.ts","sourceRoot":"","sources":["../../src/cli/attachment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,cAAc;AACzB,qDAAqD;AACnD,qBAAqB;AACvB,yEAAyE;GACvE,yBAAyB;AAC3B,0DAA0D;GACxD,mBAAmB,CAAC;AAEvB,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,cAAc,CAAC;IACrB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,eAAe,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAChC,mEAAmE;IACnE,QAAQ,EAAE,MAAM,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,CAAC;IACnE,8EAA8E;IAC9E,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IACnE,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAuCjG"}

package/dist/cli/attachment.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_HTTP_PORT = void 0;
+exports.resolveBridgeAttachment = resolveBridgeAttachment;
+exports.DEFAULT_HTTP_PORT = 1977;
+/**
+ * Decide how to obtain a bridge, without changing anything.
+ *
+ * Discovery failures that mean "no bridge" and failures that mean "a bridge is
+ * running but is not registered" are deliberately handled the same way here:
+ * both fall through to a health probe, because only the probe can tell them
+ * apart.
+ */
+async function resolveBridgeAttachment(probes) {
+    try {
+        const found = await probes.discover();
+        if (found) {
+            return {
+                mode: 'attached-discovered',
+                port: found.port,
+                pid: found.pid,
+                reason: `Attached to the bridge registered on port ${found.port} (PID ${found.pid}).`,
+                mayReclaimPorts: false,
+            };
+        }
+    }
+    catch {
+        // Discovery says nothing about whether a bridge is running — only that
+        // no usable descriptor was found. Fall through and ask the ports.
+    }
+    const candidates = probes.candidatePorts ?? [exports.DEFAULT_HTTP_PORT];
+    for (const port of candidates) {
+        const health = await probes.probeHealth(port);
+        if (health) {
+            return {
+                mode: 'attached-undiscoverable',
+                port,
+                pid: health.pid,
+                hostKind: health.hostKind,
+                reason: `Attached to a healthy ${health.hostKind || 'unknown'} bridge on port ${port} (PID ${health.pid}) ` +
+                    `whose port descriptor was missing or stale. It was not replaced.`,
+                mayReclaimPorts: false,
+            };
+        }
+    }
+    return {
+        mode: 'create-standalone',
+        reason: 'No bridge is answering on the known ports; starting an in-process standalone bridge.',
+        mayReclaimPorts: true,
+    };
+}
+//# sourceMappingURL=attachment.js.map

package/dist/cli/attachment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment.js","sourceRoot":"","sources":["../../src/cli/attachment.ts"],"names":[],"mappings":";;;AA6DA,0DAuCC;AAjDY,QAAA,iBAAiB,GAAG,IAAI,CAAC;AAEtC;;;;;;;GAOG;AACI,KAAK,UAAU,uBAAuB,CAAC,MAAwB;IACrE,IAAI,CAAC;QACJ,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;QACtC,IAAI,KAAK,EAAE,CAAC;YACX,OAAO;gBACN,IAAI,EAAE,qBAAqB;gBAC3B,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,MAAM,EAAE,6CAA6C,KAAK,CAAC,IAAI,SAAS,KAAK,CAAC,GAAG,IAAI;gBACrF,eAAe,EAAE,KAAK;aACtB,CAAC;QACH,CAAC;IACF,CAAC;IAAC,MAAM,CAAC;QACR,uEAAuE;QACvE,kEAAkE;IACnE,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,CAAC,cAAc,IAAI,CAAC,yBAAiB,CAAC,CAAC;IAChE,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAC9C,IAAI,MAAM,EAAE,CAAC;YACZ,OAAO;gBACN,IAAI,EAAE,yBAAyB;gBAC/B,IAAI;gBACJ,GAAG,EAAE,MAAM,CAAC,GAAG;gBACf,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,MAAM,EACL,yBAAyB,MAAM,CAAC,QAAQ,IAAI,SAAS,mBAAmB,IAAI,SAAS,MAAM,CAAC,GAAG,IAAI;oBACnG,kEAAkE;gBACnE,eAAe,EAAE,KAAK;aACtB,CAAC;QACH,CAAC;IACF,CAAC;IAED,OAAO;QACN,IAAI,EAAE,mBAAmB;QACzB,MAAM,EAAE,sFAAsF;QAC9F,eAAe,EAAE,IAAI;KACrB,CAAC;AACH,CAAC"}

package/dist/cli/daemon.d.ts

@@ -26,5 +26,68 @@ export declare function inspectBridge(options?: DiscoveryOptions): Promise<Bridg
 export declare function assertStandaloneBridge(status: BridgeStatus): asserts status is ActiveBridgeStatus;
 export declare function requestStandaloneYield(status: BridgeStatus, fetchImpl?: YieldFetch): Promise<void>;
 export declare function waitForBridgeExit(pid: number, timeoutMs?: number, aliveCheck?: (pid: number) => boolean): Promise<void>;
+/**
+ * Send a lifecycle command to an editor-hosted bridge.
+ *
+ * The standalone bridge exposes /api/yield; the editor host routes everything
+ * through POST /api. Recovering an editor-hosted bridge used to be impossible
+ * from here — the CLI refused, and the user had to find and kill an extension
+ * host PID by hand. Asking the owning window to stand down is the safe
+ * equivalent: no signals are ever sent to an editor process.
+ */
+export declare function requestEditorBridgeLifecycle(status: ActiveBridgeStatus, command: 'yield' | 'restart', fetchImpl?: YieldFetch): Promise<void>;
+/**
+ * Wait for an editor-hosted bridge to go quiet.
+ *
+ * The extension-host process itself stays alive, so PID liveness proves
+ * nothing here — the health endpoint is the only honest signal.
+ */
+export declare function waitForBridgeUnreachable(port: number, timeoutMs?: number): Promise<void>;
+/** Wait for a bridge to answer again after a restart. */
+export declare function waitForBridgeReachable(port: number, timeoutMs?: number): Promise<HealthResponse>;
+/**
+ * Wait for a bridge to come back up after a restart.
+ *
+ * Two assumptions had to go.
+ *
+ * Waiting for it to go *unreachable* first looks natural and is wrong: the
+ * down-state is transient, and a stop/start that completes between two polls is
+ * never observed, so `snu restart --json` reported E_STOP_TIMEOUT for restarts
+ * that had already succeeded.
+ *
+ * Assuming the port is stable is also wrong. The bridge prefers 1977 and falls
+ * back to an ephemeral port when it is taken — which is exactly what happens
+ * right after a force takeover, while the displaced process still holds 1977.
+ * The restart then moves it back, and polling only the pre-restart port waited
+ * out the timeout against an address nothing was serving any more.
+ *
+ * So: poll every plausible port, and re-read discovery each round to pick up a
+ * port that only the descriptor knows about.
+ */
+export declare function waitForBridgeRestarted(ports: number | number[], previous: {
+    startedAt?: number;
+    pid?: number;
+}, options?: {
+    timeoutMs?: number;
+    /** Re-read the port descriptor, to catch a bridge that moved. */
+    rediscover?: () => Promise<number | undefined>;
+}): Promise<HealthResponse>;
+/**
+ * Wait, briefly and optimistically, for a restarted bridge to become
+ * discoverable again.
+ *
+ * Serving and discoverable are not the same state. The global descriptor
+ * (~/.sn-scriptsync/agent-port.json) is removed on every start and only
+ * re-written once the browser helper reconnects and reports a Pro licence, so
+ * for roughly a second after a restart the bridge answers health while no
+ * descriptor names it. `snu restart` reported success in that window and an
+ * immediate `snu status` then described a healthy orphan.
+ *
+ * This never fails the restart. A workspace-external caller without a Pro
+ * licence has no global descriptor at all, and blocking on one that is never
+ * coming would turn a working restart into a hang. The caller reports what is
+ * true instead: restarted yes, discoverable not yet.
+ */
+export declare function waitForDiscovery(options: DiscoveryOptions, timeoutMs?: number): Promise<boolean>;
 export {};
 //# sourceMappingURL=daemon.d.ts.map

package/dist/cli/daemon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../../src/cli/daemon.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhF,UAAU,aAAa;IACrB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,IAAI,OAAO,CAAC;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtD;AAED,KAAK,UAAU,GAAG,CAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IACJ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;CACrB,KACE,OAAO,CAAC,aAAa,CAAC,CAAC;AAE5B,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,IAAI,CAAC;IACd,SAAS,EAAE,eAAe,CAAC;IAC3B,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,KAAK,CAAC;CAChB;AAED,MAAM,MAAM,YAAY,GAAG,kBAAkB,GAAG,oBAAoB,CAAC;AAErE,wBAAsB,aAAa,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,YAAY,CAAC,CAezF;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,IAAI,kBAAkB,CAajG;AAED,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,YAAY,EACpB,SAAS,GAAE,UAA2C,GACrD,OAAO,CAAC,IAAI,CAAC,CAgCf;AAWD,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,SAAS,SAAQ,EACjB,UAAU,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAoB,GAChD,OAAO,CAAC,IAAI,CAAC,CAUf"}
+{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../../src/cli/daemon.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhF,UAAU,aAAa;IACrB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,IAAI,OAAO,CAAC;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtD;AAED,KAAK,UAAU,GAAG,CAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IACJ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;CACrB,KACE,OAAO,CAAC,aAAa,CAAC,CAAC;AAE5B,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,IAAI,CAAC;IACd,SAAS,EAAE,eAAe,CAAC;IAC3B,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,KAAK,CAAC;CAChB;AAED,MAAM,MAAM,YAAY,GAAG,kBAAkB,GAAG,oBAAoB,CAAC;AAErE,wBAAsB,aAAa,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,YAAY,CAAC,CAezF;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,IAAI,kBAAkB,CAajG;AAED,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,YAAY,EACpB,SAAS,GAAE,UAA2C,GACrD,OAAO,CAAC,IAAI,CAAC,CAgCf;AAWD,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,SAAS,SAAQ,EACjB,UAAU,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAoB,GAChD,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;;;;;;;GAQG;AACH,wBAAsB,4BAA4B,CAChD,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,OAAO,GAAG,SAAS,EAC5B,SAAS,GAAE,UAA2C,GACrD,OAAO,CAAC,IAAI,CAAC,CA8Bf;AAED;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAc7F;AAED,yDAAyD;AACzD,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC,CAiBtG;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EACxB,QAAQ,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,EAC9C,OAAO,GAAE;IACP,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CAC3C,GACL,OAAO,CAAC,cAAc,CAAC,CA4CzB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,gBAAgB,EACzB,SAAS,SAAQ,GAChB,OAAO,CAAC,OAAO,CAAC,CAYlB"}

package/dist/cli/daemon.js

@@ -4,6 +4,11 @@ exports.inspectBridge = inspectBridge;
 exports.assertStandaloneBridge = assertStandaloneBridge;
 exports.requestStandaloneYield = requestStandaloneYield;
 exports.waitForBridgeExit = waitForBridgeExit;
+exports.requestEditorBridgeLifecycle = requestEditorBridgeLifecycle;
+exports.waitForBridgeUnreachable = waitForBridgeUnreachable;
+exports.waitForBridgeReachable = waitForBridgeReachable;
+exports.waitForBridgeRestarted = waitForBridgeRestarted;
+exports.waitForDiscovery = waitForDiscovery;
 const client_js_1 = require("../client.js");
 async function inspectBridge(options = {}) {
     try {
@@ -77,4 +82,162 @@ async function waitForBridgeExit(pid, timeoutMs = 5_000, aliveCheck = isPidAlive
     }
     throw new client_js_1.ScriptSyncClientError(`Standalone bridge PID ${pid} did not stop within ${timeoutMs / 1000}s.`, 'E_STOP_TIMEOUT');
 }
+/**
+ * Send a lifecycle command to an editor-hosted bridge.
+ *
+ * The standalone bridge exposes /api/yield; the editor host routes everything
+ * through POST /api. Recovering an editor-hosted bridge used to be impossible
+ * from here — the CLI refused, and the user had to find and kill an extension
+ * host PID by hand. Asking the owning window to stand down is the safe
+ * equivalent: no signals are ever sent to an editor process.
+ */
+async function requestEditorBridgeLifecycle(status, command, fetchImpl = fetch) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 5_000);
+    try {
+        const response = await fetchImpl(`http://127.0.0.1:${status.discovery.port}/api`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Agent-Token': status.discovery.token,
+            },
+            body: JSON.stringify({ id: `snu_lifecycle_${command}`, command, params: {} }),
+            signal: controller.signal,
+        });
+        const payload = (await response.json().catch(() => ({})));
+        if (!response.ok || payload.status !== 'success') {
+            throw new client_js_1.ScriptSyncClientError(payload.error || `The editor-hosted bridge refused to ${command} (HTTP ${response.status}).`, command === 'yield' ? 'E_STOP_FAILED' : 'E_RESTART_FAILED', response.status);
+        }
+    }
+    catch (err) {
+        if (err instanceof client_js_1.ScriptSyncClientError)
+            throw err;
+        throw new client_js_1.ScriptSyncClientError(`Could not ${command} the editor-hosted bridge: ${err?.message || err}`, command === 'yield' ? 'E_STOP_FAILED' : 'E_RESTART_FAILED');
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Wait for an editor-hosted bridge to go quiet.
+ *
+ * The extension-host process itself stays alive, so PID liveness proves
+ * nothing here — the health endpoint is the only honest signal.
+ */
+async function waitForBridgeUnreachable(port, timeoutMs = 8_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            await (0, client_js_1.checkHealth)(port);
+        }
+        catch {
+            return; // no longer answering: the transports are down
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    throw new client_js_1.ScriptSyncClientError(`The bridge on port ${port} was still answering after ${timeoutMs / 1000}s.`, 'E_STOP_TIMEOUT');
+}
+/** Wait for a bridge to answer again after a restart. */
+async function waitForBridgeReachable(port, timeoutMs = 20_000) {
+    const deadline = Date.now() + timeoutMs;
+    let lastError;
+    while (Date.now() < deadline) {
+        try {
+            return await (0, client_js_1.checkHealth)(port);
+        }
+        catch (err) {
+            lastError = err;
+            await new Promise((resolve) => setTimeout(resolve, 200));
+        }
+    }
+    throw new client_js_1.ScriptSyncClientError(`The bridge did not come back on port ${port} within ${timeoutMs / 1000}s: ${lastError?.message || lastError}`, 'E_RESTART_FAILED');
+}
+/**
+ * Wait for a bridge to come back up after a restart.
+ *
+ * Two assumptions had to go.
+ *
+ * Waiting for it to go *unreachable* first looks natural and is wrong: the
+ * down-state is transient, and a stop/start that completes between two polls is
+ * never observed, so `snu restart --json` reported E_STOP_TIMEOUT for restarts
+ * that had already succeeded.
+ *
+ * Assuming the port is stable is also wrong. The bridge prefers 1977 and falls
+ * back to an ephemeral port when it is taken — which is exactly what happens
+ * right after a force takeover, while the displaced process still holds 1977.
+ * The restart then moves it back, and polling only the pre-restart port waited
+ * out the timeout against an address nothing was serving any more.
+ *
+ * So: poll every plausible port, and re-read discovery each round to pick up a
+ * port that only the descriptor knows about.
+ */
+async function waitForBridgeRestarted(ports, previous, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 25_000;
+    // Only the ports the caller nominated, plus whatever rediscovery turns up.
+    // Adding the fixed port here unconditionally would be wrong: an unrelated
+    // bridge on 1977 would satisfy the "different pid" test and be reported as
+    // this bridge's restart. Which ports are plausible is the caller's knowledge.
+    const candidates = new Set(Array.isArray(ports) ? ports : [ports]);
+    const isRestarted = (health) => (typeof health.startedAt === 'number' &&
+        typeof previous.startedAt === 'number' &&
+        health.startedAt !== previous.startedAt) ||
+        (typeof health.pid === 'number' && typeof previous.pid === 'number' && health.pid !== previous.pid);
+    const deadline = Date.now() + timeoutMs;
+    let lastError;
+    while (Date.now() < deadline) {
+        for (const port of Array.from(candidates)) {
+            try {
+                const health = await (0, client_js_1.checkHealth)(port);
+                if (isRestarted(health))
+                    return health;
+            }
+            catch (err) {
+                lastError = err; // mid-cycle, or nothing on this port
+            }
+        }
+        if (options.rediscover) {
+            try {
+                const moved = await options.rediscover();
+                if (typeof moved === 'number')
+                    candidates.add(moved);
+            }
+            catch {
+                /* the descriptor may be mid-rewrite */
+            }
+        }
+        await new Promise((resolve) => setTimeout(resolve, 150));
+    }
+    throw new client_js_1.ScriptSyncClientError(`The bridge did not report a restart within ${timeoutMs / 1000}s on ports ${Array.from(candidates).join(', ')}${lastError ? `: ${lastError?.message || lastError}` : ''}.`, 'E_RESTART_FAILED');
+}
+/**
+ * Wait, briefly and optimistically, for a restarted bridge to become
+ * discoverable again.
+ *
+ * Serving and discoverable are not the same state. The global descriptor
+ * (~/.sn-scriptsync/agent-port.json) is removed on every start and only
+ * re-written once the browser helper reconnects and reports a Pro licence, so
+ * for roughly a second after a restart the bridge answers health while no
+ * descriptor names it. `snu restart` reported success in that window and an
+ * immediate `snu status` then described a healthy orphan.
+ *
+ * This never fails the restart. A workspace-external caller without a Pro
+ * licence has no global descriptor at all, and blocking on one that is never
+ * coming would turn a working restart into a hang. The caller reports what is
+ * true instead: restarted yes, discoverable not yet.
+ */
+async function waitForDiscovery(options, timeoutMs = 5_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const status = await inspectBridge(options);
+            if (status.running)
+                return true;
+        }
+        catch {
+            /* discovery is allowed to fail while the descriptor is being rewritten */
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    return false;
+}
 //# sourceMappingURL=daemon.js.map

package/dist/cli/daemon.js.map

@@ -1 +1 @@
-{"version":3,"file":"daemon.js","sourceRoot":"","sources":["../../src/cli/daemon.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"daemon.js","sourceRoot":"","sources":["../../src/cli/daemon.ts"],"names":[],"mappings":"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"}

package/dist/cli/doctor.d.ts

@@ -0,0 +1,155 @@
+/**
+ * `snu doctor` — one bundle that explains why the bridge is not behaving,
+ * without leaking anything.
+ *
+ * Two rules shape this file.
+ *
+ * Redaction is an ALLOWLIST. Every field in the report is named here
+ * explicitly; anything not named is dropped. A blocklist would be the obvious
+ * design and the wrong one: the port descriptor carries an auth token, health
+ * responses may grow fields, and instance settings hold session material — with
+ * a blocklist, every future field leaks by default and the mistake is invisible
+ * until someone pastes a diagnostic into an issue. Here the failure mode is a
+ * missing field, which is loud and harmless.
+ *
+ * Collection is INJECTED. The report shape and the redaction are pure, so they
+ * can be tested against token-shaped fixtures without a bridge, processes or
+ * a network.
+ */
+export interface DoctorSources {
+    cliVersion: string;
+    /** Raw descriptor contents, keyed by the path they came from. */
+    descriptors: Array<{
+        path: string;
+        data: any | null;
+        error?: string;
+    }>;
+    /** Raw /api/health response, if any bridge answered. */
+    health?: any;
+    /** Processes listening on the bridge ports. */
+    listeners: Array<{
+        port: number;
+        pid: number;
+        command: string;
+        kind: string;
+    } | null>;
+    /** Owner lease contents, if present. */
+    lease?: any;
+    /** Instance folders discovered in the workspace. */
+    instances: Array<{
+        name: string;
+        url?: string | null;
+        hasSettings: boolean;
+    }>;
+    /** auth_status results per instance, if the bridge could be asked. */
+    auth?: Array<{
+        instance: string;
+        state?: string;
+        ok?: boolean;
+        lastValidatedAt?: number;
+    }>;
+    /** get_capabilities result, if reachable. */
+    capabilities?: any;
+    /** Recent lifecycle/bridge errors, newest last. */
+    recentErrors?: string[];
+    platform: string;
+    nodeVersion: string;
+    cwd: string;
+}
+export interface DoctorReport {
+    generatedAt: number | null;
+    versions: {
+        cli: string;
+        extension: string | null;
+        bridgeApi: number | null;
+        node: string;
+        platform: string;
+    };
+    bridge: {
+        reachable: boolean;
+        hostKind: string | null;
+        pid: number | null;
+        workspaceRoot: string | null;
+        startedAt: number | null;
+        commandCount: number | null;
+    };
+    ownership: {
+        leasePresent: boolean;
+        leasePid: number | null;
+        leaseEditorKind: string | null;
+        leaseWorkspaceRoot: string | null;
+        leaseHeartbeatAt: number | null;
+    };
+    descriptors: Array<{
+        path: string;
+        present: boolean;
+        pid: number | null;
+        port: number | null;
+        hostKind: string | null;
+        workspaceRoot: string | null;
+        /** Whether a credential field was present — never its value. */
+        carriesToken: boolean;
+        error?: string;
+    }>;
+    listeners: Array<{
+        port: number;
+        pid: number;
+        kind: string;
+        command: string;
+    }>;
+    instances: Array<{
+        name: string;
+        origin: string | null;
+        hasSettings: boolean;
+    }>;
+    auth: Array<{
+        instance: string;
+        state: string;
+        ok: boolean;
+        lastValidatedAt: number | null;
+    }>;
+    capabilities: {
+        tier: string | null;
+        proFeatures: boolean | null;
+        commandReview: boolean | null;
+    } | null;
+    findings: string[];
+    recentErrors: string[];
+}
+/**
+ * Scrub free text — command lines and error messages.
+ *
+ * This is the one place an allowlist cannot be used: the content is arbitrary
+ * strings produced elsewhere, so there are no fields to enumerate. Treat it as
+ * defence in depth rather than a guarantee, and keep the surface small by
+ * truncating hard.
+ *
+ * Three shapes are removed: credential-ish key/value pairs with or without
+ * leading dashes, bearer tokens, and any long hex or base64-looking run, which
+ * is what this codebase's 32-character tokens actually look like. The first
+ * version of this only matched dashed flags, and the redaction test caught a
+ * token in `token=<value>` sailing straight through.
+ */
+export declare function scrubFreeText(value: unknown, max?: number): string;
+/** Back-compat alias: command lines are just one kind of free text. */
+export declare const safeCommand: typeof scrubFreeText;
+/**
+ * Build the report. Every output field is constructed explicitly from a named
+ * input; nothing is spread, copied wholesale, or passed through.
+ */
+export declare function buildDoctorReport(sources: DoctorSources, now?: number | null): DoctorReport;
+/**
+ * Turn the collected facts into the sentences a reader actually needs. A dump
+ * that leaves the diagnosis to the reader is not a diagnostic.
+ */
+export declare function deriveFindings(report: DoctorReport): string[];
+/** Human-readable summary. The JSON form carries everything; this carries the point. */
+export declare function formatDoctorReport(report: DoctorReport): string;
+/** Gather everything a diagnosis needs, tolerating every part being absent. */
+export declare function collectDoctorSources(options: {
+    cliVersion: string;
+    cwd: string;
+    httpPort?: number;
+    wsPort?: number;
+}): Promise<DoctorSources>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/cli/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"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"}