@masons/agent-network 0.6.24 → 0.6.26

package/dist/channel-setup.d.ts

@@ -4,9 +4,10 @@ interface StartChannelSetupOptions {
     idpBaseUrl: string;
     idpBaseUrlIsDefault?: boolean;
     invitedBy?: string;
+    startOver?: boolean;
 }
 export interface ChannelSetupResult {
-    status: "pending" | "completed" | "expired" | "failed";
+    status: "pending" | "completed" | "linked" | "expired" | "failed";
     handoffUrl?: string;
     expiresAt?: number;
     message?: string;
@@ -14,7 +15,7 @@ export interface ChannelSetupResult {
 export declare function getDefaultChannelSetupOptions(): StartChannelSetupOptions;
 export declare function startOrGetChannelSetup(options: StartChannelSetupOptions): Promise<ChannelSetupResult>;
 export declare function getChannelSetupStatus(): ChannelSetupResult | null;
-export declare function consumeChannelSetupStatus(): ChannelSetupResult | null;
+export declare function getReportableSetupStatus(): ChannelSetupResult | null;
 export declare function _resetChannelSetupForTesting(): void;
 export declare const CHANNEL_SETUP_TTL_MS: number;
 export {};

package/dist/channel-setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channel-setup.d.ts","sourceRoot":"","sources":["../src/channel-setup.ts"],"names":[],"mappings":"AAeA,UAAU,wBAAwB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IAEnB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAM9B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA2BD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAOD,wBAAgB,6BAA6B,IAAI,wBAAwB,CAKxE;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,kBAAkB,CAAC,CAsC7B;AAED,wBAAgB,qBAAqB,IAAI,kBAAkB,GAAG,IAAI,CAcjE;AAED,wBAAgB,yBAAyB,IAAI,kBAAkB,GAAG,IAAI,CAMrE;AAmFD,wBAAgB,4BAA4B,IAAI,IAAI,CAGnD;AAED,eAAO,MAAM,oBAAoB,QAAqB,CAAC"}
+{"version":3,"file":"channel-setup.d.ts","sourceRoot":"","sources":["../src/channel-setup.ts"],"names":[],"mappings":"AA+BA,UAAU,wBAAwB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IAEnB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAM9B,SAAS,CAAC,EAAE,MAAM,CAAC;IAOnB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AA4CD,MAAM,WAAW,kBAAkB;IAKjC,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA4BD,wBAAgB,6BAA6B,IAAI,wBAAwB,CAKxE;AAWD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,kBAAkB,CAAC,CAqB7B;AAyDD,wBAAgB,qBAAqB,IAAI,kBAAkB,GAAG,IAAI,CAQjE;AAaD,wBAAgB,wBAAwB,IAAI,kBAAkB,GAAG,IAAI,CAOpE;AAgOD,wBAAgB,4BAA4B,IAAI,IAAI,CAInD;AAED,eAAO,MAAM,oBAAoB,QAAqB,CAAC"}

package/dist/channel-setup.js

@@ -1,12 +1,22 @@
 import createDebug from "debug";
-import { readExistingConnectorUrl } from "./config.js";
+import { hasApiKey, readExistingConnectorUrl, requireApiKey, requirePlatformConfig, } from "./config.js";
 import { resolveConnectorUrlForSetup } from "./connector-url-boundary.js";
-import { beginBridgeHandoff, completeBridgeHandoff, DEFAULT_IDP_BASE_URL, HANDOFF_TIMEOUT_MS, SetupFlowError, } from "./handoff.js";
+import { beginBridgeHandoff, collectBridgeHandoffOnce, completeBridgeHandoff, DEFAULT_IDP_BASE_URL, HANDOFF_TIMEOUT_MS, SetupFlowError, } from "./handoff.js";
 import { acceptBridgeHandoff } from "./handoff-acceptance.js";
-import { DEFAULT_API_HOST } from "./platform-client.js";
+import { classifyIdentityError, formatCanonicalNode, } from "./identity-format.js";
+import { DEFAULT_API_HOST, getIdentity, } from "./platform-client.js";
 const dbg = createDebug("agent-network:channel-setup");
+const GENERIC_EXPIRY_MESSAGE = "The previous Link URL expired before the browser handoff completed.";
+const GONE_MESSAGE = "That Link session is no longer on the handoff bridge — it expired, or its runtime key was already delivered — so it cannot complete.";
+const SUPERSEDED_MESSAGE = "A newer Link session replaced this one while it was completing, so the runtime key that session delivered was discarded. Nothing changed — this runtime still uses the credential it had before.";
+const DURABLE_BINDING_NOTE = [
+    "This result reflects the current binding — the runtime key this Runtime holds, confirmed with the network just now.",
+    "To re-link or change Node, call masons_link with start_over: true.",
+].join("\n");
 let pendingSetup = null;
 let lastSetupStatus = null;
+let setupSeq = 0;
+let lastRecordedSeq = 0;
 export function getDefaultChannelSetupOptions() {
     return {
         apiHost: DEFAULT_API_HOST,
@@ -14,50 +24,52 @@ export function getDefaultChannelSetupOptions() {
     };
 }
 export async function startOrGetChannelSetup(options) {
+    if (options.startOver)
+        return await startNewSession(options);
     const active = getActivePendingSetup();
     if (active) {
-        return {
-            status: "pending",
-            handoffUrl: active.session.handoffUrl,
-            expiresAt: active.session.expiresAt,
-        };
+        const collected = await collectActiveSetup(active);
+        if (collected)
+            return collected;
     }
-    lastSetupStatus = null;
-    const existingConnectorUrl = await readExistingConnectorUrl();
-    const connectorUrl = resolveConnectorUrlForSetup({
-        apiHost: options.apiHost,
-        existingConnectorUrl,
-        configuredConnectorUrl: options.connectorUrl,
-    });
-    const session = await beginBridgeHandoff({
-        apiHost: options.apiHost,
-        idpBaseUrl: options.idpBaseUrl,
-        idpBaseUrlIsDefault: options.idpBaseUrlIsDefault,
-    });
-    const record = {
-        session,
-        apiHost: options.apiHost,
-        connectorUrl,
-        idpBaseUrl: options.idpBaseUrl,
-        invitedBy: options.invitedBy,
-    };
-    pendingSetup = record;
-    void completePendingSetup(record);
-    return {
-        status: "pending",
-        handoffUrl: session.handoffUrl,
-        expiresAt: session.expiresAt,
-    };
+    const reportable = getReportableSetupStatus();
+    if (reportable)
+        return reportable;
+    const live = getActivePendingSetup();
+    if (live)
+        return pendingResult(live);
+    const durable = await reportDurableBinding(options);
+    if (durable)
+        return durable;
+    return await startNewSession(options);
+}
+async function reportDurableBinding(options) {
+    if (!hasApiKey())
+        return null;
+    let node;
+    try {
+        node = await getIdentity(requirePlatformConfig(), requireApiKey());
+    }
+    catch (err) {
+        if (classifyIdentityError(err) === null)
+            throw err;
+        dbg("the stored runtime key could not be verified before minting: %O", err);
+        return null;
+    }
+    if (node === null)
+        return null;
+    const lines = [formatCanonicalNode("Linked", node), DURABLE_BINDING_NOTE];
+    if (options.invitedBy)
+        lines.push(invitationFollowThrough(options.invitedBy));
+    return { status: "linked", message: lines.join("\n") };
+}
+function invitationFollowThrough(invitedBy) {
+    return `This call carried an invitation from @${invitedBy}. The binding above already stands, so nothing was recorded to act on later — propose the connection now with masons_send_connection_request to @${invitedBy}.`;
 }
 export function getChannelSetupStatus() {
     const active = getActivePendingSetup();
-    if (active) {
-        return {
-            status: "pending",
-            handoffUrl: active.session.handoffUrl,
-            expiresAt: active.session.expiresAt,
-        };
-    }
+    if (active)
+        return pendingResult(active);
     if (!lastSetupStatus)
         return null;
     return {
@@ -65,31 +77,76 @@ export function getChannelSetupStatus() {
         message: lastSetupStatus.message,
     };
 }
-export function consumeChannelSetupStatus() {
-    const status = getChannelSetupStatus();
-    if (status?.status !== "pending") {
-        lastSetupStatus = null;
-    }
-    return status;
+export function getReportableSetupStatus() {
+    const recorded = lastSetupStatus;
+    if (!recorded)
+        return null;
+    if (pendingSetup?.seq === recorded.seq)
+        return null;
+    if (recorded.status === "completed")
+        return reportStatus(recorded);
+    if (!recorded.reported)
+        return reportStatus(recorded);
+    return null;
+}
+function pendingResult(record) {
+    return {
+        status: "pending",
+        handoffUrl: record.session.handoffUrl,
+        expiresAt: record.session.expiresAt,
+    };
+}
+function reportStatus(status) {
+    status.reported = true;
+    return { status: status.status, message: status.message };
+}
+function storedResult(stored) {
+    return stored ? reportStatus(stored) : null;
 }
 function getActivePendingSetup() {
     if (!pendingSetup)
         return null;
     if (Date.now() < pendingSetup.session.expiresAt)
         return pendingSetup;
-    lastSetupStatus = {
-        status: "expired",
-        message: "The previous Link URL expired before the browser handoff completed.",
-        finishedAt: Date.now(),
-    };
+    const lapsed = pendingSetup;
     pendingSetup = null;
+    recordSetupStatus(lapsed, "expired", GENERIC_EXPIRY_MESSAGE, false);
     return null;
 }
-async function completePendingSetup(record) {
+async function collectActiveSetup(record) {
+    let collection;
+    try {
+        collection = await collectBridgeHandoffOnce(record.session);
+    }
+    catch (err) {
+        dbg("owner-invoked collection could not reach the bridge: %O", err);
+        return null;
+    }
+    switch (collection.outcome) {
+        case "delivered":
+            return storedResult(await acceptCollectedHandoff(record, collection.handoff));
+        case "spoiled":
+            return storedResult(settle(record, isExpiryError(collection.error) ? "expired" : "failed", collection.error.message));
+        case "gone":
+            return storedResult(collectGoneSession(record));
+        default:
+            return null;
+    }
+}
+function collectGoneSession(record) {
+    if (!record.collected)
+        return settle(record, "expired", GONE_MESSAGE);
+    const settled = lastSetupStatus;
+    if (settled?.seq === record.seq && settled.settled)
+        return settled;
+    return null;
+}
+async function acceptCollectedHandoff(record, handoff) {
+    record.collected = true;
+    if (pendingSetup !== record) {
+        return recordSetupStatus(record, "failed", SUPERSEDED_MESSAGE, true);
+    }
     try {
-        const handoff = await completeBridgeHandoff(record.session);
-        if (pendingSetup !== record)
-            return;
         const receipt = await acceptBridgeHandoff({
             handoff,
             apiHost: record.apiHost,
@@ -98,31 +155,74 @@ async function completePendingSetup(record) {
             pendingTarget: record.invitedBy,
             expiresAt: record.session.expiresAt,
         });
-        lastSetupStatus = {
-            status: "completed",
-            message: receipt,
-            finishedAt: Date.now(),
-        };
+        return settle(record, "completed", receipt);
     }
     catch (err) {
-        if (pendingSetup !== record && !supersedesGenericExpiry(err))
-            return;
-        lastSetupStatus = {
-            status: isExpiryError(err) ? "expired" : "failed",
-            message: safeSetupErrorMessage(err),
-            finishedAt: Date.now(),
-        };
+        return settle(record, isExpiryError(err) ? "expired" : "failed", safeSetupErrorMessage(err));
     }
-    finally {
-        if (pendingSetup === record) {
-            pendingSetup = null;
-        }
+}
+function settle(record, status, message) {
+    if (pendingSetup === record)
+        pendingSetup = null;
+    return recordSetupStatus(record, status, message, true);
+}
+async function startNewSession(options) {
+    const existingConnectorUrl = await readExistingConnectorUrl();
+    const connectorUrl = resolveConnectorUrlForSetup({
+        apiHost: options.apiHost,
+        existingConnectorUrl,
+        configuredConnectorUrl: options.connectorUrl,
+    });
+    const session = await beginBridgeHandoff({
+        apiHost: options.apiHost,
+        idpBaseUrl: options.idpBaseUrl,
+        idpBaseUrlIsDefault: options.idpBaseUrlIsDefault,
+    });
+    const record = {
+        seq: ++setupSeq,
+        session,
+        apiHost: options.apiHost,
+        connectorUrl,
+        idpBaseUrl: options.idpBaseUrl,
+        invitedBy: options.invitedBy,
+        collected: false,
+    };
+    pendingSetup = record;
+    lastSetupStatus = null;
+    void completePendingSetup(record);
+    return pendingResult(record);
+}
+async function completePendingSetup(record) {
+    let handoff;
+    try {
+        handoff = await completeBridgeHandoff(record.session);
+    }
+    catch (err) {
+        recordSetupStatus(record, isExpiryError(err) ? "expired" : "failed", safeSetupErrorMessage(err), false);
+        return;
     }
+    await acceptCollectedHandoff(record, handoff);
 }
-function supersedesGenericExpiry(err) {
-    return (err instanceof SetupFlowError &&
-        pendingSetup === null &&
-        lastSetupStatus?.status === "expired");
+function recordSetupStatus(record, status, message, settled) {
+    const next = {
+        seq: record.seq,
+        status,
+        message,
+        reported: false,
+        settled,
+    };
+    if (!canRecord(next))
+        return null;
+    lastSetupStatus = next;
+    lastRecordedSeq = next.seq;
+    return next;
+}
+function canRecord(next) {
+    if (next.seq !== lastRecordedSeq)
+        return next.seq > lastRecordedSeq;
+    if (!lastSetupStatus)
+        return false;
+    return next.settled && !lastSetupStatus.settled;
 }
 function isExpiryError(err) {
     if (!(err instanceof SetupFlowError))
@@ -138,5 +238,6 @@ function safeSetupErrorMessage(err) {
 export function _resetChannelSetupForTesting() {
     pendingSetup = null;
     lastSetupStatus = null;
+    lastRecordedSeq = 0;
 }
 export const CHANNEL_SETUP_TTL_MS = HANDOFF_TIMEOUT_MS;

package/dist/connector-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connector-client.d.ts","sourceRoot":"","sources":["../src/connector-client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAI3C,OAAO,EAEL,KAAK,qBAAqB,EAI1B,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EAEzB,KAAK,mBAAmB,EAUxB,KAAK,oBAAoB,EAMzB,KAAK,oBAAoB,EAC1B,MAAM,YAAY,CAAC;AAEpB,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AA0B3B,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;gBACT,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM;CAMvD;AAED,MAAM,MAAM,wBAAwB,GAAG,aAAa,GAAG,mBAAmB,CAAC;AAM3E,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,IAAI,EAAG,sBAAsB,CAAU;IAChD,QAAQ,CAAC,SAAS,EAAG,KAAK,CAAU;IACpC,QAAQ,CAAC,QAAQ,EAAG,CAAC,CAAU;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;gBAE9B,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,wBAAwB;CAahE;AAID,KAAK,qBAAqB,GAAG;IAC3B,gBAAgB,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;IACzD,eAAe,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;IACtD,QAAQ,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAC;IAChD,gBAAgB,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAC;IACxD,eAAe,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;IACtD,gBAAgB,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAC;IACxD,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAC9B,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,YAAY,EAAE,MAAM,IAAI,CAAC;CAC1B,CAAC;AAEF,MAAM,WAAW,sBAAsB;IAErC,SAAS,CAAC,EAAE,IAAI,CACd,kBAAkB,EAClB,YAAY,GAAG,gBAAgB,GAAG,wBAAwB,CAC3D,CAAC;CACH;AAiBD,MAAM,MAAM,YAAY,GACpB,YAAY,GACZ,WAAW,GACX,cAAc,GACd,cAAc,CAAC;AAanB,MAAM,MAAM,mBAAmB,GAC3B;IAAE,KAAK,EAAE,UAAU,CAAA;CAAE,GACrB;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,KAAK,EAAE,UAAU,CAAA;CAAE,GACrB;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAItB,qBAAa,eAAgB,SAAQ,YAAY;IAC/C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,uBAAuB,CAAK;IACpC,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,SAAS,CAAkC;IACnD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAsC;IAEvE,OAAO,CAAC,eAAe,CAA6B;IACpD,OAAO,CAAC,cAAc,CAAuC;IAC7D,OAAO,CAAC,aAAa,CAA8C;IAGnE,OAAO,CAAC,YAAY,CAA0C;IAG9D,OAAO,CAAC,WAAW,CAAS;IAG5B,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAG/B;IACJ,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAgB;IAGnD,OAAO,CAAC,YAAY,CAOhB;gBAGF,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,sBAA2B;IAUtC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAWxB,UAAU,IAAI,IAAI;IAwBlB,eAAe,IAAI,YAAY;IAe/B,eAAe,IAAI,mBAAmB;IActC,IAAI,CACF,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,WAAW,SAAS,EACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,oBAAoB,CAAC;IA+ChC,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO;IAUlD,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAOrC,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IASzC,EAAE,CAAC,CAAC,SAAS,MAAM,qBAAqB,EACtC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,qBAAqB,CAAC,CAAC,CAAC,GACjC,IAAI;IACP,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI;IAKxE,IAAI,CAAC,CAAC,SAAS,MAAM,qBAAqB,EACxC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,qBAAqB,CAAC,CAAC,CAAC,GACjC,IAAI;IACP,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI;IAK1E,GAAG,CAAC,CAAC,SAAS,MAAM,qBAAqB,EACvC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,qBAAqB,CAAC,CAAC,CAAC,GACjC,IAAI;IACP,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI;IAKzE,IAAI,CAAC,CAAC,SAAS,MAAM,qBAAqB,EACxC,KAAK,EAAE,CAAC,EACR,GAAG,IAAI,EAAE,UAAU,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,GAC5C,OAAO;IACV,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO;IAOzD,OAAO,CAAC,SAAS;IAyCjB,OAAO,CAAC,YAAY;IAcpB,OAAO,CAAC,oBAAoB;IAO5B,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,cAAc;IActB,OAAO,CAAC,aAAa,CAgBnB;IAGF,OAAO,CAAC,iBAAiB;IAuFzB,OAAO,CAAC,sBAAsB;IA0B9B,OAAO,CAAC,kBAAkB;IAc1B,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,2BAA2B;IAYnC,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,iBAAiB;IAkFzB,OAAO,CAAC,aAAa;IAwBrB,OAAO,CAAC,qBAAqB;IAkC7B,OAAO,CAAC,WAAW;IAiEnB,OAAO,CAAC,WAAW,CAIjB;IAIF,OAAO,CAAC,iBAAiB;IAezB,OAAO,CAAC,gBAAgB;IAcxB,OAAO,CAAC,sBAAsB;IAO9B,OAAO,CAAC,mBAAmB;IAS3B,OAAO,CAAC,iBAAiB;IA0BzB,OAAO,CAAC,SAAS;IAWjB,OAAO,CAAC,mBAAmB;CAW5B"}
+{"version":3,"file":"connector-client.d.ts","sourceRoot":"","sources":["../src/connector-client.ts"],"names":[],"mappings":"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"}

package/dist/connector-client.js

@@ -476,8 +476,10 @@ export class ConnectorClient extends EventEmitter {
             this.registration = { state: "replaced" };
             const msg = "This agent was claimed by another Runtime " +
                 "(this Runtime disconnected). " +
-                "Re-run `openclaw channels login --channel agent-network` " +
-                "to drive this agent from here again.";
+                "To drive this agent from here again, ask the owner to call " +
+                "masons_link with start_over: true in this conversation; as a last " +
+                "resort, `openclaw channels login --channel agent-network` in a " +
+                "terminal does the same.";
             this.emit("error", new Error(msg));
             if (wasRegistering) {
                 this.rejectRegister(new Error(msg));

package/dist/handoff.d.ts

@@ -1,4 +1,5 @@
 import { type KeyObject } from "node:crypto";
+import { SetupFlowError } from "./handoff-deadline.js";
 export { SetupFlowError } from "./handoff-deadline.js";
 export declare const DEFAULT_IDP_BASE_URL = "https://preview.masons.ai";
 export declare const HANDOFF_TIMEOUT_MS: number;
@@ -24,4 +25,16 @@ export interface BeginBridgeHandoffOptions {
 }
 export declare function beginBridgeHandoff(options: BeginBridgeHandoffOptions): Promise<BridgeHandoffSession>;
 export declare function completeBridgeHandoff(session: BridgeHandoffSession): Promise<BridgeHandoffResult>;
+export type BridgeCollection = {
+    outcome: "pending";
+} | {
+    outcome: "gone";
+} | {
+    outcome: "delivered";
+    handoff: BridgeHandoffResult;
+} | {
+    outcome: "spoiled";
+    error: SetupFlowError;
+};
+export declare function collectBridgeHandoffOnce(session: BridgeHandoffSession): Promise<BridgeCollection>;
 //# sourceMappingURL=handoff.d.ts.map

package/dist/handoff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handoff.d.ts","sourceRoot":"","sources":["../src/handoff.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,SAAS,EAEf,MAAM,aAAa,CAAC;AAQrB,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAavD,eAAO,MAAM,oBAAoB,8BAA8B,CAAC;AAWhE,eAAO,MAAM,kBAAkB,QAAiB,CAAC;AA0BjD,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1D;AAQD,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAElB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAOhB,UAAU,EAAE,SAAS,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IAMnB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAMD,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,oBAAoB,CAAC,CAiE/B;AAKD,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CA0C9B"}
+{"version":3,"file":"handoff.d.ts","sourceRoot":"","sources":["../src/handoff.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,SAAS,EAEf,MAAM,aAAa,CAAC;AAErB,OAAO,EAEL,cAAc,EACf,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAavD,eAAO,MAAM,oBAAoB,8BAA8B,CAAC;AAWhE,eAAO,MAAM,kBAAkB,QAAiB,CAAC;AA0BjD,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1D;AAQD,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAElB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAUhB,UAAU,EAAE,SAAS,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IAMnB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAMD,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,oBAAoB,CAAC,CAiE/B;AAKD,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAO9B;AAUD,MAAM,MAAM,gBAAgB,GACxB;IAAE,OAAO,EAAE,SAAS,CAAA;CAAE,GACtB;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GACnB;IAAE,OAAO,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,mBAAmB,CAAA;CAAE,GACtD;IAAE,OAAO,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,CAAC;AASlD,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,gBAAgB,CAAC,CA8B3B"}

package/dist/handoff.js

@@ -55,6 +55,44 @@ export async function beginBridgeHandoff(options) {
 }
 export async function completeBridgeHandoff(session) {
     const envelope = await pollForCompletion(session.apiBase, session.sessionId, session.expiresAt);
+    return readBridgeEnvelope(session, envelope);
+}
+export async function collectBridgeHandoffOnce(session) {
+    assertHandoffDeadlineActive(session.expiresAt);
+    const res = await apiFetch(pollUrl(session.apiBase, session.sessionId), {
+        method: "GET",
+    });
+    if (res.status === 404)
+        return { outcome: "gone" };
+    if (!res.ok)
+        return { outcome: "pending" };
+    let body;
+    try {
+        body = (await res.json());
+    }
+    catch (err) {
+        return { outcome: "spoiled", error: unreadableDelivery(err) };
+    }
+    if (body.status !== "completed" || !body.payload)
+        return { outcome: "pending" };
+    try {
+        return {
+            outcome: "delivered",
+            handoff: readBridgeEnvelope(session, body.payload),
+        };
+    }
+    catch (err) {
+        return {
+            outcome: "spoiled",
+            error: err instanceof SetupFlowError ? err : unreadableDelivery(err),
+        };
+    }
+}
+function unreadableDelivery(err) {
+    const detail = err instanceof Error ? err.message : "unknown error";
+    return new SetupFlowError(`The handoff bridge released this Link's runtime key but the response could not be read (${detail}), so the key was lost with it.`);
+}
+function readBridgeEnvelope(session, envelope) {
     let payload;
     try {
         payload = decryptBridgeEnvelope(session.privateKey, envelope);
@@ -81,12 +119,15 @@ export async function completeBridgeHandoff(session) {
         },
     };
 }
+function pollUrl(apiBase, sessionId) {
+    return `${apiBase}/v1/cli-handoff/${encodeURIComponent(sessionId)}/poll`;
+}
 async function pollForCompletion(apiBase, sessionId, expiresAt) {
     let lastNetworkError;
     while (Date.now() < expiresAt) {
         let res;
         try {
-            res = await apiFetch(`${apiBase}/v1/cli-handoff/${encodeURIComponent(sessionId)}/poll`, { method: "GET" });
+            res = await apiFetch(pollUrl(apiBase, sessionId), { method: "GET" });
         }
         catch (err) {
             if (err instanceof PlatformNetworkError) {

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAUrE,OAAO,EACL,kCAAkC,EAEnC,MAAM,oCAAoC,CAAC;AA8D5C,wBAAgB,uBAAuB,CACrC,eAAe,EAAE,MAAM,GAAG,SAAS,EACnC,iBAAiB,EAAE,MAAM,GAAG,IAAI,EAChC,mBAAmB,GAAE,mBAAmB,GAAG,IAA+B,GACzE,MAAM,GAAG,SAAS,CA6EpB;AAKD,UAAU,iBAAiB;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACjD,YAAY,CACV,IAAI,EAAE,OAAO,EACb,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3C,IAAI,CAAC;IACR,yBAAyB,CAAC,MAAM,EAAE;QAChC,EAAE,EAAE,MAAM,CAAC;QACX,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,OAAO,kCAAkC,CAAC;KACrD,GAAG,IAAI,CAAC;IACT,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GAAG,IAAI,CAAC;CACnE;AAqCD,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAaI,iBAAiB;CAoahC,CAAC;AAEF,eAAe,MAAM,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAUrE,OAAO,EACL,kCAAkC,EAEnC,MAAM,oCAAoC,CAAC;AA8D5C,wBAAgB,uBAAuB,CACrC,eAAe,EAAE,MAAM,GAAG,SAAS,EACnC,iBAAiB,EAAE,MAAM,GAAG,IAAI,EAChC,mBAAmB,GAAE,mBAAmB,GAAG,IAA+B,GACzE,MAAM,GAAG,SAAS,CA6EpB;AAKD,UAAU,iBAAiB;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACjD,YAAY,CACV,IAAI,EAAE,OAAO,EACb,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3C,IAAI,CAAC;IACR,yBAAyB,CAAC,MAAM,EAAE;QAChC,EAAE,EAAE,MAAM,CAAC;QACX,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,OAAO,kCAAkC,CAAC;KACrD,GAAG,IAAI,CAAC;IACT,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GAAG,IAAI,CAAC;CACnE;AAqCD,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAaI,iBAAiB;CAsahC,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/plugin.js

@@ -194,10 +194,12 @@ const plugin = {
             if (!state.hasCredentials) {
                 dynamicContext =
                     "[Context: Agent Network] You recently installed the agent network plugin " +
-                        "but it is not yet authorized. If your current channel sender is the verified " +
-                        "OpenClaw owner, call masons_link to generate a MASONS handoff URL here. " +
-                        "If owner authority is unavailable, tell your user to run this terminal fallback: " +
-                        "`openclaw channels login --channel agent-network`. Browser sign-in handles " +
+                        "but it is not yet authorized. Link finishes in this conversation: if your " +
+                        "current channel sender is the verified OpenClaw owner, call masons_link to " +
+                        "generate a MASONS handoff URL here. If owner authority is unavailable here, " +
+                        "ask the owner to start Link from a channel their OpenClaw is configured for; " +
+                        "only as a last resort, `openclaw channels login --channel agent-network` in a " +
+                        "terminal. Browser sign-in handles " +
                         "agent selection or creation. After the Link completes, OpenClaw will reload and " +
                         "the agent network tools will become available.";
                 if (state.pendingTarget) {

package/dist/tools.d.ts

@@ -26,7 +26,6 @@ interface ToolApi {
     }): void;
 }
 export declare function _resetToolsForTesting(): void;
-export declare function terminalSetupInstructions(): string;
 export declare function ownerRefusalText(reason: "known-non-owner" | "ambiguous"): string;
 export declare function formatChannelSetupResult(result: ChannelSetupResult): string;
 export declare function registerTools(api: ToolApi): void;

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAuBA,OAAO,EAEL,KAAK,kBAAkB,EAIxB,MAAM,oBAAoB,CAAC;AAuD5B,UAAU,WAAW;IACnB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,CACP,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,OAAO,CAAC,WAAW,CAAC,CAAC;CAC3B;AAED,UAAU,WAAW;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,KAAK,WAAW,GAAG,CAAC,GAAG,EAAE,WAAW,KAAK,cAAc,GAAG,IAAI,GAAG,SAAS,CAAC;AAE3E,UAAU,OAAO;IACf,YAAY,CACV,IAAI,EAAE,cAAc,GAAG,WAAW,EAWlC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAC7D,IAAI,CAAC;CACT;AAkED,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AA6WD,wBAAgB,yBAAyB,IAAI,MAAM,CAiBlD;AAmBD,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,iBAAiB,GAAG,WAAW,GACtC,MAAM,CAqBR;AAGD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAoC3E;AAcD,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAmnChD"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAuBA,OAAO,EAEL,KAAK,kBAAkB,EAGxB,MAAM,oBAAoB,CAAC;AA0D5B,UAAU,WAAW;IACnB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,CACP,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,OAAO,CAAC,WAAW,CAAC,CAAC;CAC3B;AAED,UAAU,WAAW;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,KAAK,WAAW,GAAG,CAAC,GAAG,EAAE,WAAW,KAAK,cAAc,GAAG,IAAI,GAAG,SAAS,CAAC;AAE3E,UAAU,OAAO;IACf,YAAY,CACV,IAAI,EAAE,cAAc,GAAG,WAAW,EAWlC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAC7D,IAAI,CAAC;CACT;AAkED,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAkYD,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,iBAAiB,GAAG,WAAW,GACtC,MAAM,CAqBR;AAGD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAyC3E;AA+CD,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAqoChD"}

package/dist/tools.js

@@ -1,7 +1,7 @@
 import { Type } from "@sinclair/typebox";
 import pluginManifest from "../openclaw.plugin.json" with { type: "json" };
 import { getOwnerPassportAddress } from "./channel.js";
-import { _resetChannelSetupForTesting, consumeChannelSetupStatus, getDefaultChannelSetupOptions, startOrGetChannelSetup, } from "./channel-setup.js";
+import { _resetChannelSetupForTesting, getDefaultChannelSetupOptions, startOrGetChannelSetup, } from "./channel-setup.js";
 import { clearTargetHandle, extractNetworkConfig, getConnectorClient, getDmScope, getPendingTarget, hasApiKey, isProfileNeeded, markProfileComplete, removeIdentityLinks, requireApiKey, requireConversationManager, requirePlatformConfig, writeIdentityLinks, } from "./config.js";
 import { getOwnerHandle } from "./environment-context.js";
 import { classifyIdentityError, formatCanonicalNode, formatKindLabel, } from "./identity-format.js";
@@ -142,17 +142,19 @@ function formatRegistration(outcome) {
             return "none";
     }
 }
+function formatChannelStateLines(client) {
+    return [
+        `Gateway channel: ${client ? client.getChannelState() : "not established"}`,
+        `Registration (this connection): ${formatRegistration(client ? client.getRegistration() : { state: "none" })}`,
+    ];
+}
 function formatReadinessSection() {
     const credentialsLine = hasApiKey()
         ? "Credentials: configured"
         : "Credentials: not configured";
-    const client = getConnectorClient();
-    const channel = client ? client.getChannelState() : "not established";
-    const registration = formatRegistration(client ? client.getRegistration() : { state: "none" });
     return [
         credentialsLine,
-        `Gateway channel: ${channel}`,
-        `Registration (this connection): ${registration}`,
+        ...formatChannelStateLines(getConnectorClient()),
     ].join("\n");
 }
 async function resolveIdentitySection() {
@@ -222,24 +224,6 @@ function toRecord(value) {
 function stringValue(value) {
     return typeof value === "string" && value.length > 0 ? value : undefined;
 }
-export function terminalSetupInstructions() {
-    return [
-        "Run this in the terminal where OpenClaw is installed:",
-        "",
-        "  openclaw channels login --channel agent-network",
-        "",
-        "It will:",
-        "  1. Display a MASONS handoff URL.",
-        "  2. Open it in your browser and sign in.",
-        "  3. Pick an existing agent or create a new one.",
-        "  4. Return to the terminal after the encrypted handoff completes.",
-        "  5. Persist credentials to openclaw.json. OpenClaw reloads the channel.",
-        "",
-        "Note: on an already-linked install this is a Relink — choosing another Node here changes",
-        "which Node this OpenClaw install drives. Each install holds its own runtime key, so",
-        "relinking updates this OpenClaw install's credentials.",
-    ].join("\n");
-}
 export function ownerRefusalText(reason) {
     if (reason === "known-non-owner") {
         return [
@@ -269,6 +253,7 @@ export function formatChannelSetupResult(result) {
             result.handoffUrl,
             "",
             "Open this link in your browser, sign in, choose an agent, then come back here.",
+            "This Link is still open, so asking me again returns this same URL, not a new one — open the one above.",
             "After browser sign-in and agent selection, OpenClaw will receive the encrypted handoff, persist the runtime key locally, and reload the channel.",
             "This URL is sensitive Link material; only the OpenClaw owner should open it.",
         ].join("\n");
@@ -278,24 +263,40 @@ export function formatChannelSetupResult(result) {
             result.message ?? "Agent Network Link completed.",
             "",
             "HTTP tools may work before the Gateway WebSocket is connected.",
-            'If the gateway tool is available, call it with action "restart" and reason "Activate Agent Network after Link". If not, ask the user to run `openclaw gateway restart`.',
+            GATEWAY_RESTART_ACTION,
+            "This result stands until the owner asks to start over: to re-link or change Node, call masons_link with start_over: true.",
         ].join("\n");
     }
+    if (result.status === "linked") {
+        const receipt = result.message ?? "This Runtime is linked to an Agent Node.";
+        return [receipt, ...formatRealtimeGap()].join("\n");
+    }
     if (result.status === "expired") {
         return [
             result.message ?? "The previous Link URL expired.",
-            "Ask again to generate a fresh owner-only Link URL, or use the terminal fallback:",
             "",
-            terminalSetupInstructions(),
+            LINK_RETRY_GUIDANCE,
         ].join("\n");
     }
     return [
         result.message ?? "Agent Network Link failed.",
-        "Ask again to retry, or use the terminal fallback:",
         "",
-        terminalSetupInstructions(),
+        LINK_RETRY_GUIDANCE,
     ].join("\n");
 }
+const GATEWAY_RESTART_ACTION = 'If the gateway tool is available, call it with action "restart" and reason "Activate Agent Network after Link". If not, ask the user to run `openclaw gateway restart`.';
+function formatRealtimeGap() {
+    const client = getConnectorClient();
+    if (client?.getChannelState() === "connected" &&
+        client.getRegistration().state === "accepted") {
+        return [];
+    }
+    return ["", ...formatChannelStateLines(client), GATEWAY_RESTART_ACTION];
+}
+const LINK_RETRY_GUIDANCE = [
+    "Call masons_link again in this conversation — the whole flow finishes here.",
+    "Last resort, only if that keeps failing: the owner can run `openclaw channels login --channel agent-network` in a terminal.",
+].join("\n");
 export function registerTools(api) {
     api.registerTool((ctx = {}) => ({
         name: "masons_link",
@@ -306,7 +307,12 @@ export function registerTools(api) {
             "Agent Network tools fail with a 'no credentials' error, or when the",
             "runtime owner wants a different MASONS agent driven by OpenClaw.",
             "On a Runtime that is already linked, present this to the user as",
-            "Relink / Change Node — the same capability, not a second one.",
+            "Relink / Change Node — the same capability, not a second one. After a",
+            "Link has completed in this process, pass start_over: true to re-link",
+            "or link a different Node; a plain call re-reports the completed one.",
+            "To check on a Link in progress (after the owner opens the URL), call",
+            "with NO arguments — start_over would discard the pending Link and",
+            "issue a fresh URL instead of confirming the one the owner completed.",
             "",
             "Not to be confused with masons_link_identity: this tool binds a",
             "Runtime to a Node. masons_link_identity aliases your owner's identity",
@@ -319,7 +325,9 @@ export function registerTools(api) {
             "This tool returns a browser handoff URL on the channel where you are",
             "running. The user opens it, signs in, picks an agent, and the encrypted",
             "handoff completes in the background. After completion, restart the",
-            "gateway to activate realtime messaging.",
+            "gateway to activate realtime messaging. When this Runtime already",
+            "holds a verified binding and no Link is pending, it reports that",
+            "standing binding instead of issuing a URL.",
             "",
             "If the user is reaching this agent through the MASONS network as a",
             "visitor (not the agent's owner), this tool refuses with an explanation",
@@ -333,6 +341,13 @@ export function registerTools(api) {
                     "the plugin records this as a pending connection target so the " +
                     "agent can propose a connection request automatically.",
             })),
+            start_over: Type.Optional(Type.Boolean({
+                description: "Discard whatever this Runtime is holding — a Link still in " +
+                    "progress, a Link that already completed, or a binding already " +
+                    "on disk — and issue a fresh Link URL. Without it a repeat call " +
+                    "re-reports what stands, which after a Gateway restart is the " +
+                    "standing binding rather than the completed result.",
+            })),
         }),
         execute: async (_id, params) => {
             const authority = resolveSetupAuthority();
@@ -342,15 +357,13 @@ export function registerTools(api) {
             const invitedBy = typeof params.invitedBy === "string" && params.invitedBy.length > 0
                 ? params.invitedBy
                 : undefined;
-            const existing = consumeChannelSetupStatus();
             let result;
             try {
-                result = existing
-                    ? existing
-                    : await startOrGetChannelSetup({
-                        ...getSetupOptionsFromToolContext(ctx),
-                        invitedBy,
-                    });
+                result = await startOrGetChannelSetup({
+                    ...getSetupOptionsFromToolContext(ctx),
+                    invitedBy,
+                    startOver: params.start_over === true,
+                });
             }
             catch (err) {
                 result = {
@@ -416,7 +429,7 @@ export function registerTools(api) {
             catch (err) {
                 if (err instanceof PlatformApiError) {
                     if (err.status === 401) {
-                        return textResult("Authentication failed. The runtime key may be invalid. Ask the user to run `openclaw channels login --channel agent-network`.");
+                        return textResult("Authentication failed. The runtime key may be invalid. Ask the owner to re-link here: call masons_link with start_over: true.");
                     }
                     if (err.status === 422) {
                         return textResult(`Validation error: ${err.message}`);
@@ -497,7 +510,7 @@ export function registerTools(api) {
                             : "This Services deployment does not serve the connection-request endpoint. Nothing was sent.");
                     }
                     if (err.status === 401) {
-                        return textResult("Authentication failed. The runtime key may be invalid. Ask the user to run `openclaw channels login --channel agent-network`.");
+                        return textResult("Authentication failed. The runtime key may be invalid. Ask the owner to re-link here: call masons_link with start_over: true.");
                     }
                     return textResult(`Connection request failed: ${err.message}`);
                 }
@@ -581,7 +594,7 @@ export function registerTools(api) {
             catch (err) {
                 if (err instanceof PlatformApiError) {
                     if (err.status === 401) {
-                        return textResult("Authentication failed. The runtime key may be invalid. Ask the user to run `openclaw channels login --channel agent-network`.");
+                        return textResult("Authentication failed. The runtime key may be invalid. Ask the owner to re-link here: call masons_link with start_over: true.");
                     }
                     if (err.status === 404) {
                         return textResult("This Services deployment does not serve the packaged connection-request endpoint. Nothing was read.");
@@ -769,7 +782,7 @@ export function registerTools(api) {
             catch (err) {
                 if (err instanceof PlatformApiError) {
                     if (err.status === 401) {
-                        return textResult("Authentication failed. The runtime key may be invalid. Ask the user to run `openclaw channels login --channel agent-network`.");
+                        return textResult("Authentication failed. The runtime key may be invalid. Ask the owner to re-link here: call masons_link with start_over: true.");
                     }
                     return textResult(`Failed to list connections: ${err.message}`);
                 }

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const PLUGIN_VERSION = "0.6.24";
+export declare const PLUGIN_VERSION = "0.6.26";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1 +1 @@
-export const PLUGIN_VERSION = "0.6.24";
+export const PLUGIN_VERSION = "0.6.26";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masons/agent-network",
-  "version": "0.6.24",
+  "version": "0.6.26",
   "description": "MASONS Agent Network — OpenClaw channel plugin for connecting agent runtimes to the Agent Network over MSTP.",
   "license": "MIT",
   "author": "MASONS.ai <hello@masons.ai> (https://masons.ai)",

package/skills/agent-network/SKILL.md

@@ -71,7 +71,7 @@ Check your current state and go to the right section:
 
 ## Link
 
-Binding this runtime to an agent Node takes about a minute. Link can run from an owner-verified channel through an encrypted browser handoff. Terminal login remains the fallback when owner authority is unavailable.
+Binding this runtime to an agent Node takes about a minute. Link runs from an owner-verified channel through an encrypted browser handoff, and it finishes **in this conversation** — never send the owner to a terminal as your first move. Terminal login is the last resort, for when owner authority is unavailable here or Link keeps failing here.
 
 On a runtime that is already linked, this same flow is a **Relink / Change Node** — tell the user that, and use the same tool. There is no second capability.
 
@@ -83,11 +83,7 @@ On a runtime that is already linked, this same flow is a **Relink / Change Node*
 
 If the current sender is verified as the OpenClaw owner, the tool returns a MASONS handoff URL. Share the URL as ordinary chat text, on its own line, without wrapping it in backticks or a code block. Never ask for or display runtime keys, ciphertext payloads, decrypted token metadata, private key material, or debug output that looks credential-like.
 
-If owner authority is missing, false, or ambiguous, the tool returns the terminal fallback. Tell the user to run:
-
-```sh
-openclaw channels login --channel agent-network
-```
+If owner authority is missing, false, or ambiguous, the tool refuses and explains why — relay that text. Where it names `openclaw channels login --channel agent-network`, that is the last resort for an owner with no channel their OpenClaw is configured for; try such a channel first.
 
 ### Step 2: User Completes Browser Handoff
 
@@ -97,7 +93,9 @@ The browser handoff page lets the owner sign in, select or create an agent, and
 
 After completion:
 
-1. Call `masons_link` again to check whether the encrypted handoff completed.
+1. Call `masons_link` again to check whether the encrypted handoff completed. This call collects the owner's browser selection itself, so a step they already finished is confirmed here rather than costing a second browser walk. While the Link is still open the same call returns the SAME URL — pass it on, do not describe it as a new one.
+   - Some Hosts restart the Gateway the moment the runtime key is written, so a restart right after the owner says they finished is EXPECTED here — it is the success signal, not a fault.
+   - The restarted process confirms the Link as a **Linked** receipt (the present binding) instead of an **Accepted** one (the acceptance moment). Both mean the Link succeeded: relay it and move on, never re-issue a URL.
 2. If `masons_link` reports the Link completed, restart the Gateway to activate realtime messaging:
    - Prefer the host `gateway` tool with `action`: `"restart"` and `reason`: `"Activate Agent Network after Link"`.
    - If the `gateway` tool is unavailable, tell the user to run `openclaw gateway restart`.
@@ -110,10 +108,13 @@ After completion:
 
 ### Errors
 
-- If any tool returns an error, explain it simply and suggest next steps.
-- If the CLI says a handle is rejected or taken, ask the user to retry the login command and choose a different handle.
+- If `masons_link` reports the Link expired or failed, that session is over: call `masons_link` again in this conversation. On a Runtime that still holds a working binding that call reports the standing binding, so add `start_over: true` to get a fresh URL. Do not offer the terminal on a first failure.
+- If `masons_link` reports the Link completed or Linked and the user wants to re-link or change Node, call it with `start_over: true` — a plain call re-reports the current binding.
+- Only after Link has failed here repeatedly, name `openclaw channels login --channel agent-network` as the last resort, and say so.
+- If any other tool returns an error, explain it simply and suggest next steps.
+- If the CLI says a handle is rejected or taken, ask the user to retry and choose a different handle.
 - If network errors, suggest checking internet connection.
-- If the tools still report no runtime key after login, read `references/troubleshooting.md`.
+- If the tools still report no runtime key after a completed Link, read `references/troubleshooting.md`.
 
 ## Profile