visionclaw 0.1.185-beta.7 → 0.1.185-beta.9

package/dist/agent/applied-credential-signature.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Applied-credential signature manifest.
+ *
+ * Persisted alongside materialised tunnel credentials at
+ * `<profileTunnelDir>/.applied-signature.json`. Records the signature
+ * the server handed us with the last bundle we successfully applied.
+ *
+ * The manifest is the *only* piece of state the agent has to remember
+ * across process restarts about credential bundles — everything else
+ * (creds JSON, config.yml) is reconstructable from a fresh server
+ * delivery. The signature is opaque to us; we just echo it back on the
+ * next heartbeat so the server can decide whether to re-ship the body.
+ *
+ * Self-healing properties (intentional):
+ *   - Manifest missing on disk → no signature sent → server sends
+ *     bundle → we re-apply and rewrite the manifest. Recovers any
+ *     install where the manifest was deleted but credentials weren't,
+ *     or vice versa.
+ *   - Manifest present but probe says no live tunnel files → we treat
+ *     the manifest as unusable (return null from `loadIfValid`), the
+ *     next heartbeat goes signature-free, the server re-ships the
+ *     bundle, and we land back in a coherent state.
+ *   - Process restart with everything intact → manifest signature is
+ *     sent on the startup heartbeat, server replies with no
+ *     `credentialBundle`, no disk writes, no tunnel restart.
+ */
+/**
+ * Read the persisted signature, if any. Returns `null` when the file
+ * does not exist, fails to parse, has the wrong shape, or refers to a
+ * tunnel state that no longer matches what's on disk.
+ *
+ * The on-disk-coherence check (`probeLocalTunnelCredential()`) is what
+ * gives us self-healing: a stranded manifest from a wiped tunnel dir
+ * gets ignored, forcing a fresh bundle on the next heartbeat.
+ */
+export declare function loadAppliedSignatureIfValid(): string | null;
+/**
+ * Persist the signature for the most recently applied bundle. Best-
+ * effort: a write failure is logged but does not throw, since the
+ * worst case is just an extra full-bundle delivery on the next
+ * heartbeat.
+ *
+ * The file is written with 0o600 to match the credentials sitting next
+ * to it; the directory itself is already 0o700 from
+ * `runtime-credentials.ts`.
+ */
+export declare function writeAppliedSignature(signature: string): void;
+/**
+ * Forget the persisted signature. Used by tests; production code never
+ * needs to delete it explicitly because writes overwrite in place.
+ */
+export declare function __clearAppliedSignatureForTests(): void;
+//# sourceMappingURL=applied-credential-signature.d.ts.map

package/dist/agent/applied-credential-signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applied-credential-signature.d.ts","sourceRoot":"","sources":["../../src/agent/applied-credential-signature.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAwBH;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,GAAG,IAAI,CA2C3D;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAgC7D;AAED;;;GAGG;AACH,wBAAgB,+BAA+B,IAAI,IAAI,CAMtD"}

package/dist/agent/applied-credential-signature.js

@@ -0,0 +1,137 @@
+/**
+ * Applied-credential signature manifest.
+ *
+ * Persisted alongside materialised tunnel credentials at
+ * `<profileTunnelDir>/.applied-signature.json`. Records the signature
+ * the server handed us with the last bundle we successfully applied.
+ *
+ * The manifest is the *only* piece of state the agent has to remember
+ * across process restarts about credential bundles — everything else
+ * (creds JSON, config.yml) is reconstructable from a fresh server
+ * delivery. The signature is opaque to us; we just echo it back on the
+ * next heartbeat so the server can decide whether to re-ship the body.
+ *
+ * Self-healing properties (intentional):
+ *   - Manifest missing on disk → no signature sent → server sends
+ *     bundle → we re-apply and rewrite the manifest. Recovers any
+ *     install where the manifest was deleted but credentials weren't,
+ *     or vice versa.
+ *   - Manifest present but probe says no live tunnel files → we treat
+ *     the manifest as unusable (return null from `loadIfValid`), the
+ *     next heartbeat goes signature-free, the server re-ships the
+ *     bundle, and we land back in a coherent state.
+ *   - Process restart with everything intact → manifest signature is
+ *     sent on the startup heartbeat, server replies with no
+ *     `credentialBundle`, no disk writes, no tunnel restart.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getProfileTunnelDir } from "../config/index.js";
+import { probeLocalTunnelCredential } from "./runtime-credentials.js";
+import { logger } from "../logger.js";
+const MANIFEST_FILENAME = ".applied-signature.json";
+const MANIFEST_VERSION = 1;
+function getManifestPath() {
+    return path.join(getProfileTunnelDir(), MANIFEST_FILENAME);
+}
+/**
+ * Read the persisted signature, if any. Returns `null` when the file
+ * does not exist, fails to parse, has the wrong shape, or refers to a
+ * tunnel state that no longer matches what's on disk.
+ *
+ * The on-disk-coherence check (`probeLocalTunnelCredential()`) is what
+ * gives us self-healing: a stranded manifest from a wiped tunnel dir
+ * gets ignored, forcing a fresh bundle on the next heartbeat.
+ */
+export function loadAppliedSignatureIfValid() {
+    const manifestPath = getManifestPath();
+    if (!fs.existsSync(manifestPath))
+        return null;
+    let raw;
+    try {
+        raw = fs.readFileSync(manifestPath, "utf-8");
+    }
+    catch (err) {
+        logger.warn(`Applied-signature manifest unreadable: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        logger.warn(`Applied-signature manifest malformed; ignoring`);
+        return null;
+    }
+    if (!parsed ||
+        typeof parsed !== "object" ||
+        !("signature" in parsed) ||
+        typeof parsed.signature !== "string" ||
+        parsed.signature.trim() === "") {
+        return null;
+    }
+    const signature = parsed.signature.trim();
+    // Coherence: a manifest is only meaningful when the credentials it
+    // refers to actually still exist on disk. If the tunnel files were
+    // wiped (e.g. operator deleted `~/.visionclaw/profiles/default/tunnel`)
+    // the stored signature lies about our state, so pretend we have none
+    // and let the server reissue the bundle.
+    if (probeLocalTunnelCredential() === null) {
+        return null;
+    }
+    return signature;
+}
+/**
+ * Persist the signature for the most recently applied bundle. Best-
+ * effort: a write failure is logged but does not throw, since the
+ * worst case is just an extra full-bundle delivery on the next
+ * heartbeat.
+ *
+ * The file is written with 0o600 to match the credentials sitting next
+ * to it; the directory itself is already 0o700 from
+ * `runtime-credentials.ts`.
+ */
+export function writeAppliedSignature(signature) {
+    if (typeof signature !== "string" || signature.trim() === "")
+        return;
+    const manifestPath = getManifestPath();
+    const dir = path.dirname(manifestPath);
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    catch {
+        // best-effort; the credential apply path will have created it
+    }
+    const payload = {
+        version: MANIFEST_VERSION,
+        signature: signature.trim(),
+        appliedAt: new Date().toISOString(),
+    };
+    try {
+        fs.writeFileSync(manifestPath, JSON.stringify(payload, null, 2), "utf-8");
+        if (process.platform !== "win32") {
+            try {
+                fs.chmodSync(manifestPath, 0o600);
+            }
+            catch {
+                // best-effort; directory perms still protect
+            }
+        }
+    }
+    catch (err) {
+        logger.warn(`Failed to persist applied-signature manifest: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Forget the persisted signature. Used by tests; production code never
+ * needs to delete it explicitly because writes overwrite in place.
+ */
+export function __clearAppliedSignatureForTests() {
+    try {
+        fs.rmSync(getManifestPath(), { force: true });
+    }
+    catch {
+        // ignore
+    }
+}
+//# sourceMappingURL=applied-credential-signature.js.map

package/dist/agent/applied-credential-signature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"applied-credential-signature.js","sourceRoot":"","sources":["../../src/agent/applied-credential-signature.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC,MAAM,iBAAiB,GAAG,yBAAyB,CAAC;AACpD,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAW3B,SAAS,eAAe;IACtB,OAAO,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,iBAAiB,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,2BAA2B;IACzC,MAAM,YAAY,GAAG,eAAe,EAAE,CAAC;IACvC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC;QAAE,OAAO,IAAI,CAAC;IAE9C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IAC/C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,IAAI,CACT,0CAA0C,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAC7F,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,CAAC,IAAI,CAAC,gDAAgD,CAAC,CAAC;QAC9D,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IACE,CAAC,MAAM;QACP,OAAO,MAAM,KAAK,QAAQ;QAC1B,CAAC,CAAC,WAAW,IAAI,MAAM,CAAC;QACxB,OAAQ,MAAiC,CAAC,SAAS,KAAK,QAAQ;QAC/D,MAAgC,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,EACzD,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,SAAS,GAAI,MAAgC,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;IAErE,mEAAmE;IACnE,mEAAmE;IACnE,wEAAwE;IACxE,qEAAqE;IACrE,yCAAyC;IACzC,IAAI,0BAA0B,EAAE,KAAK,IAAI,EAAE,CAAC;QAC1C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,SAAiB;IACrD,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO;IAErE,MAAM,YAAY,GAAG,eAAe,EAAE,CAAC;IACvC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IAEvC,IAAI,CAAC;QACH,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,8DAA8D;IAChE,CAAC;IAED,MAAM,OAAO,GAAsB;QACjC,OAAO,EAAE,gBAAgB;QACzB,SAAS,EAAE,SAAS,CAAC,IAAI,EAAE;QAC3B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;IAEF,IAAI,CAAC;QACH,EAAE,CAAC,aAAa,CAAC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;QAC1E,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;YACjC,IAAI,CAAC;gBACH,EAAE,CAAC,SAAS,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;YACpC,CAAC;YAAC,MAAM,CAAC;gBACP,6CAA6C;YAC/C,CAAC;QACH,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,IAAI,CACT,iDAAiD,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CACpG,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,+BAA+B;IAC7C,IAAI,CAAC;QACH,EAAE,CAAC,MAAM,CAAC,eAAe,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,SAAS;IACX,CAAC;AACH,CAAC"}

package/dist/agent/credential-bundle-handler.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Credential bundle coordinator.
+ *
+ * Owns every concern around server-issued `credentialBundle` deliveries
+ * over the heartbeat:
+ *
+ *   - exposing the locally-applied signature so the heartbeat layer can
+ *     send it back to the server (which decides whether to re-ship)
+ *   - materialising delivered bundles to disk (via `runtime-credentials.ts`)
+ *   - bouncing cloudflared when a tunnel rotation lands, with restart
+ *     coalescing so concurrent rotations don't race
+ *
+ * Replaces the old `TunnelCredentialHandler` + `bootstrapCredentials`
+ * flag heuristic. The signature path is server-authoritative and
+ * forward-compatible: when a future credential kind is added to
+ * `CredentialBundleBody`, the same signature mechanism naturally
+ * detects + delivers it without any new wire fields.
+ *
+ * Persistence model — deliberately none. The applied signature lives
+ * only in memory, which means **every fresh process gets a full bundle
+ * delivery on its first heartbeat**. That's the recovery path for any
+ * disk drift we can't enumerate in advance: a corrupted creds JSON, a
+ * stale config.yml, a wiped profile dir, an operator-edited manifest —
+ * doesn't matter. Restart the agent, the server hands us the current
+ * bundle, we re-apply, we're back in sync. The cost is one bundle
+ * download per process lifetime (a few KB), which is negligible.
+ */
+import type { CredentialBundle } from "../onboarding/onboarding-service-client.js";
+export interface CredentialBundleHandlerOptions {
+    /** Canonical agent name used to validate tunnel-name drift. */
+    agentName: string;
+    /**
+     * Callback that bounces cloudflared (typically the `restartTunnel`
+     * returned from `startObsServer`). Invoked when a newly materialised
+     * tunnel credential differs from what's on disk — otherwise
+     * cloudflared keeps running against the UUID it was spawned with
+     * (it does not hot-reload `config.yml`).
+     *
+     * Optional so test harnesses and non-obs builds can skip the restart
+     * side-effect entirely.
+     */
+    restartTunnel?: () => Promise<string | null>;
+}
+export declare class CredentialBundleHandler {
+    private readonly agentName;
+    private readonly restartTunnel?;
+    /**
+     * The signature the agent will send to the server on the next
+     * heartbeat. `undefined` means "I have no opinion, please send me
+     * the bundle" — which is the state every fresh process starts in,
+     * by design. Updated only after a successful apply.
+     */
+    private _appliedSignature;
+    private _restartInFlight;
+    /**
+     * Set whenever a `tunnelChanged` apply lands while a previous restart
+     * is still in flight. The in-flight restart already snapshotted disk
+     * state at its start (`resolveTunnelOpts()` in `obs/server.ts`), so
+     * the second rotation needs its own bounce — we re-kick from the
+     * restart's `finally` block when this flag is set.
+     *
+     * Stored as the latest `ApplyRuntimeCredentialsResult` so the
+     * rotation label in the follow-up log line still reflects the
+     * *latest* tunnel delivery, not the first one already restarted.
+     */
+    private _pendingRestart;
+    constructor(options: CredentialBundleHandlerOptions);
+    /**
+     * The signature to attach to the next heartbeat as
+     * `appliedCredentialSignature`. `undefined` until the first
+     * successful apply in this process — which forces the server to
+     * ship the bundle on the startup heartbeat (the recovery path).
+     */
+    get appliedSignature(): string | undefined;
+    /**
+     * Handle the optional `credentialBundle` from a heartbeat response.
+     *
+     * Defensive by contract: never throws — a failed materialisation must
+     * not block heartbeats. A missing/undefined bundle means "server
+     * agrees with our applied signature": no work to do.
+     */
+    handle(bundle: CredentialBundle | undefined): void;
+    /**
+     * Kick `restartTunnel` in the background, coalescing concurrent
+     * invocations. Logged at `system` level because a restart is a
+     * visible event for operators tailing pm2 logs.
+     *
+     * If a restart is already in flight when we're called, we don't drop
+     * the trigger — the in-flight restart sampled disk before this newer
+     * credential was materialised and would launch cloudflared against
+     * the stale UUID. Instead we record the latest result in
+     * `_pendingRestart` and re-kick from the in-flight restart's
+     * `finally` block, which guarantees one extra restart that picks up
+     * whatever's now on disk.
+     */
+    private triggerRestart;
+}
+//# sourceMappingURL=credential-bundle-handler.d.ts.map

package/dist/agent/credential-bundle-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-bundle-handler.d.ts","sourceRoot":"","sources":["../../src/agent/credential-bundle-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EACV,gBAAgB,EACjB,MAAM,4CAA4C,CAAC;AAOpD,MAAM,WAAW,8BAA8B;IAC7C,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC9C;AAED,qBAAa,uBAAuB;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAA+B;IAE9D;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB,CAAiC;IAE1D,OAAO,CAAC,gBAAgB,CAA8B;IACtD;;;;;;;;;;OAUG;IACH,OAAO,CAAC,eAAe,CAA8C;gBAEzD,OAAO,EAAE,8BAA8B;IAKnD;;;;;OAKG;IACH,IAAI,gBAAgB,IAAI,MAAM,GAAG,SAAS,CAEzC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,GAAG,IAAI;IAuClD;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,cAAc;CA6CvB"}

package/dist/agent/credential-bundle-handler.js

@@ -0,0 +1,161 @@
+/**
+ * Credential bundle coordinator.
+ *
+ * Owns every concern around server-issued `credentialBundle` deliveries
+ * over the heartbeat:
+ *
+ *   - exposing the locally-applied signature so the heartbeat layer can
+ *     send it back to the server (which decides whether to re-ship)
+ *   - materialising delivered bundles to disk (via `runtime-credentials.ts`)
+ *   - bouncing cloudflared when a tunnel rotation lands, with restart
+ *     coalescing so concurrent rotations don't race
+ *
+ * Replaces the old `TunnelCredentialHandler` + `bootstrapCredentials`
+ * flag heuristic. The signature path is server-authoritative and
+ * forward-compatible: when a future credential kind is added to
+ * `CredentialBundleBody`, the same signature mechanism naturally
+ * detects + delivers it without any new wire fields.
+ *
+ * Persistence model — deliberately none. The applied signature lives
+ * only in memory, which means **every fresh process gets a full bundle
+ * delivery on its first heartbeat**. That's the recovery path for any
+ * disk drift we can't enumerate in advance: a corrupted creds JSON, a
+ * stale config.yml, a wiped profile dir, an operator-edited manifest —
+ * doesn't matter. Restart the agent, the server hands us the current
+ * bundle, we re-apply, we're back in sync. The cost is one bundle
+ * download per process lifetime (a few KB), which is negligible.
+ */
+import { applyRuntimeCredentials, } from "./runtime-credentials.js";
+import { logger } from "../logger.js";
+export class CredentialBundleHandler {
+    agentName;
+    restartTunnel;
+    /**
+     * The signature the agent will send to the server on the next
+     * heartbeat. `undefined` means "I have no opinion, please send me
+     * the bundle" — which is the state every fresh process starts in,
+     * by design. Updated only after a successful apply.
+     */
+    _appliedSignature = undefined;
+    _restartInFlight = null;
+    /**
+     * Set whenever a `tunnelChanged` apply lands while a previous restart
+     * is still in flight. The in-flight restart already snapshotted disk
+     * state at its start (`resolveTunnelOpts()` in `obs/server.ts`), so
+     * the second rotation needs its own bounce — we re-kick from the
+     * restart's `finally` block when this flag is set.
+     *
+     * Stored as the latest `ApplyRuntimeCredentialsResult` so the
+     * rotation label in the follow-up log line still reflects the
+     * *latest* tunnel delivery, not the first one already restarted.
+     */
+    _pendingRestart = null;
+    constructor(options) {
+        this.agentName = options.agentName;
+        this.restartTunnel = options.restartTunnel;
+    }
+    /**
+     * The signature to attach to the next heartbeat as
+     * `appliedCredentialSignature`. `undefined` until the first
+     * successful apply in this process — which forces the server to
+     * ship the bundle on the startup heartbeat (the recovery path).
+     */
+    get appliedSignature() {
+        return this._appliedSignature;
+    }
+    /**
+     * Handle the optional `credentialBundle` from a heartbeat response.
+     *
+     * Defensive by contract: never throws — a failed materialisation must
+     * not block heartbeats. A missing/undefined bundle means "server
+     * agrees with our applied signature": no work to do.
+     */
+    handle(bundle) {
+        if (!bundle)
+            return;
+        if (typeof bundle.signature !== "string" || bundle.signature.trim() === "") {
+            logger.warn(`Credential bundle delivery missing signature; ignoring`);
+            return;
+        }
+        let result = null;
+        try {
+            result = applyRuntimeCredentials(bundle.body, { agentName: this.agentName });
+        }
+        catch (err) {
+            logger.warn(`Credential bundle apply failed: ${err instanceof Error ? err.message : String(err)}`);
+            // Deliberately do NOT update `_appliedSignature` on failure: the
+            // server should keep retrying the bundle until we report success.
+            return;
+        }
+        // Remember the new signature even when the bundle body was empty
+        // (e.g. server has no credentials provisioned yet). This is an
+        // intentional policy choice: empty bundle means "no new server-
+        // issued credential to apply", NOT "tear down any local tunnel
+        // currently on disk". The agent therefore keeps its local tunnel
+        // materialization as-is and simply records agreement on the empty
+        // server state for the rest of this process lifetime.
+        this._appliedSignature = bundle.signature.trim();
+        // If the apply rotated cloudflared's UUID, bounce it. Without this
+        // obs/server.ts spawned cloudflared against whatever was on disk at
+        // startup, and a fresh UUID would sit unused until the next
+        // process restart.
+        if (result.tunnelApplied && result.tunnelChanged && result.tunnel) {
+            this.triggerRestart(result);
+        }
+    }
+    /**
+     * Kick `restartTunnel` in the background, coalescing concurrent
+     * invocations. Logged at `system` level because a restart is a
+     * visible event for operators tailing pm2 logs.
+     *
+     * If a restart is already in flight when we're called, we don't drop
+     * the trigger — the in-flight restart sampled disk before this newer
+     * credential was materialised and would launch cloudflared against
+     * the stale UUID. Instead we record the latest result in
+     * `_pendingRestart` and re-kick from the in-flight restart's
+     * `finally` block, which guarantees one extra restart that picks up
+     * whatever's now on disk.
+     */
+    triggerRestart(result) {
+        if (!this.restartTunnel || !result.tunnel)
+            return;
+        if (this._restartInFlight) {
+            // Always overwrite — only the most recent credential matters; any
+            // intermediate bundles will be on disk by the time the follow-up
+            // restart re-probes via `obs/server.ts:resolveTunnelOpts()`.
+            this._pendingRestart = result;
+            return;
+        }
+        const newTunnelId = result.tunnel.tunnelId;
+        const previousTunnelId = result.previousTunnelId;
+        const rotationLabel = previousTunnelId === null
+            ? "initial"
+            : previousTunnelId === newTunnelId
+                ? "refreshed"
+                : `rotated (${previousTunnelId} → ${newTunnelId})`;
+        logger.system(`Runtime credential: tunnel ${rotationLabel}; restarting cloudflared`);
+        const restart = this.restartTunnel;
+        this._restartInFlight = (async () => {
+            try {
+                await restart();
+            }
+            catch (err) {
+                logger.warn(`Failed to restart tunnel after credential update: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            finally {
+                this._restartInFlight = null;
+                // Drain any rotation that landed mid-flight. We re-enter
+                // triggerRestart synchronously (not via setImmediate) so the
+                // follow-up restart starts as soon as the previous Promise
+                // resolves, but `_restartInFlight` is already null above so the
+                // recursive call goes down the spawn path, not the coalesce path.
+                const pending = this._pendingRestart;
+                if (pending) {
+                    this._pendingRestart = null;
+                    this.triggerRestart(pending);
+                }
+            }
+        })();
+    }
+}
+//# sourceMappingURL=credential-bundle-handler.js.map

package/dist/agent/credential-bundle-handler.js.map

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

package/dist/agent/heartbeat-manager.d.ts

@@ -10,6 +10,20 @@ import type { ChannelManager } from "../channels/manager.js";
 import { type HeartbeatBillingPlan, type SubscriptionStatus } from "../onboarding/onboarding-service-client.js";
 import { CommandDispatcher } from "./command-dispatcher.js";
 import { type PendingUpgradeInfo } from "../config/index.js";
+export interface HeartbeatManagerOptions {
+    /**
+     * Callback that bounces the cloudflared tunnel (typically the
+     * `restartTunnel` returned from `startObsServer`). Forwarded verbatim
+     * to the tunnel credential handler — HeartbeatManager itself has no
+     * tunnel knowledge beyond passing this through.
+     *
+     * HeartbeatManager is constructed before `agentState` is initialised
+     * (the heartbeat fires during `init` while the agent state is still
+     * being built), so we take the callback directly rather than reaching
+     * into `getAgentState().restartTunnel`.
+     */
+    restartTunnel?: () => Promise<string | null>;
+}
 export declare class HeartbeatManager {
     private client;
     readonly commandDispatcher: CommandDispatcher;
@@ -20,23 +34,15 @@ export declare class HeartbeatManager {
     private _lastBillingPlans;
     private _lastBillingMessage;
     /**
-     * Arms the next heartbeat to request a full `runtimeCredentials` bundle.
-     * True at startup and whenever the agent detects that local tunnel
-     * credentials are missing (lost files, first-run, post-reset).
+     * Owns all server-issued credential orchestration: signature tracking,
+     * bundle materialisation, restart coalescing. HeartbeatManager hands
+     * it each heartbeat response and reads its `appliedSignature` when
+     * building the next payload.
      */
-    private _needsCredentialBootstrap;
-    constructor(config: VisionClawConfig);
+    private readonly credentialBundle;
+    constructor(config: VisionClawConfig, options?: HeartbeatManagerOptions);
     /** Build a base heartbeat payload including owner info for server-side backfill. */
     private buildPayload;
-    /**
-     * Apply any `runtimeCredentials` delivered by the server.
-     *
-     * Runs inside a try/catch so a failed materialization never breaks the
-     * heartbeat critical path. If the server omitted `runtimeCredentials` but
-     * the agent has no local tunnel credential either, we arm the next
-     * heartbeat to request a bootstrap refresh.
-     */
-    private handleRuntimeCredentialsFromResponse;
     /**
      * Initialize the heartbeat client and validate the API key.
      * Should be called once at startup. If validation fails, heartbeats

package/dist/agent/heartbeat-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"heartbeat-manager.d.ts","sourceRoot":"","sources":["../../src/agent/heartbeat-manager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAEL,KAAK,oBAAoB,EAGzB,KAAK,kBAAkB,EACxB,MAAM,4CAA4C,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,OAAO,EAA4D,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAmDvH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAwC;IACtD,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,CAAC;IAC9C,OAAO,CAAC,YAAY,CAA+C;IACnE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,uBAAuB,CAA8B;IAC7D,OAAO,CAAC,iBAAiB,CAA8B;IACvD,OAAO,CAAC,mBAAmB,CAAqB;IAChD;;;;OAIG;IACH,OAAO,CAAC,yBAAyB,CAAQ;gBAE7B,MAAM,EAAE,gBAAgB;IAQpC,oFAAoF;IACpF,OAAO,CAAC,YAAY;IA0BpB;;;;;;;OAOG;IACH,OAAO,CAAC,oCAAoC;IA0B5C;;;;OAIG;IACG,IAAI,CACR,cAAc,EAAE,cAAc,EAC9B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,YAAY,EAAE,kBAAkB,GAAG,IAAI,GACtC,OAAO,CAAC,IAAI,CAAC;IA+EhB,4CAA4C;IAC5C,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,uEAAuE;IACvE,IAAI,sBAAsB,IAAI,kBAAkB,CAE/C;IAED,sFAAsF;IACtF,IAAI,gBAAgB,IAAI,oBAAoB,EAAE,CAE7C;IAED,wFAAwF;IACxF,IAAI,kBAAkB,IAAI,MAAM,GAAG,SAAS,CAE3C;IAED;;;OAGG;IACG,gBAAgB,IAAI,OAAO,CAAC;QAChC,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,IAAI,CAAC;IAKT;;;OAGG;IACG,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAsC1C;;;OAGG;IACG,4BAA4B,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAoBjE;;;OAGG;IACH,iBAAiB,IAAI,IAAI;IAWzB;;;OAGG;IACH,gBAAgB,IAAI,IAAI;CAYzB"}
+{"version":3,"file":"heartbeat-manager.d.ts","sourceRoot":"","sources":["../../src/agent/heartbeat-manager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAEL,KAAK,oBAAoB,EAEzB,KAAK,kBAAkB,EACxB,MAAM,4CAA4C,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,OAAO,EAA4D,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAYvH,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC9C;AAsCD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAwC;IACtD,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,CAAC;IAC9C,OAAO,CAAC,YAAY,CAA+C;IACnE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,uBAAuB,CAA8B;IAC7D,OAAO,CAAC,iBAAiB,CAA8B;IACvD,OAAO,CAAC,mBAAmB,CAAqB;IAChD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA0B;gBAE/C,MAAM,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,uBAAuB;IAYvE,oFAAoF;IACpF,OAAO,CAAC,YAAY;IA+BpB;;;;OAIG;IACG,IAAI,CACR,cAAc,EAAE,cAAc,EAC9B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,YAAY,EAAE,kBAAkB,GAAG,IAAI,GACtC,OAAO,CAAC,IAAI,CAAC;IAgFhB,4CAA4C;IAC5C,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,uEAAuE;IACvE,IAAI,sBAAsB,IAAI,kBAAkB,CAE/C;IAED,sFAAsF;IACtF,IAAI,gBAAgB,IAAI,oBAAoB,EAAE,CAE7C;IAED,wFAAwF;IACxF,IAAI,kBAAkB,IAAI,MAAM,GAAG,SAAS,CAE3C;IAED;;;OAGG;IACG,gBAAgB,IAAI,OAAO,CAAC;QAChC,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,IAAI,CAAC;IAKT;;;OAGG;IACG,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAgC1C;;;OAGG;IACG,4BAA4B,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAoBjE;;;OAGG;IACH,iBAAiB,IAAI,IAAI;IAWzB;;;OAGG;IACH,gBAAgB,IAAI,IAAI;CAYzB"}