crewly 1.20.192 → 1.20.194

package/dist/cli/backend/src/services/cloud/cloud-sync.service.d.ts

@@ -16,6 +16,14 @@
  */
 import { EventEmitter } from 'events';
 import type { CloudSyncConfig, CloudSyncHealth, CloudSyncState, SyncDevice, MessageType } from './cloud-sync.types.js';
+/**
+ * Gap before the next queue registration after `failures` consecutive
+ * failures: REGISTER_RETRY_BACKOFF_MS in order, then its last value forever.
+ *
+ * @param failures - Consecutive failures so far (>= 1)
+ * @returns Delay in ms
+ */
+export declare function registerRetryDelay(failures: number): number;
 export declare class CloudSyncService extends EventEmitter {
     private static instance;
     private readonly logger;
@@ -37,8 +45,31 @@ export declare class CloudSyncService extends EventEmitter {
     private messagePollRunning;
     /** When the last message-poll cycle finished (watchdog input). */
     private lastMessagePollAt;
-    /** Queue re-register timer handle (lets relay evict stale Portal pairs). */
+    /**
+     * Next queue registration (self-scheduling): every REGISTER_INTERVAL_MS
+     * while registered (lets the relay evict stale Portal pairs), on the
+     * REGISTER_RETRY_BACKOFF_MS schedule while registration fails.
+     */
     private registerTimer;
+    /** Consecutive failed queue registrations */
+    private queueFailures;
+    /** Epoch ms of the first failure in the current registration failure streak */
+    private queueFailingSince;
+    /** Epoch ms of the next scheduled registration */
+    private nextQueueAttemptAt;
+    /**
+     * Bumped by start() and stop(). An attempt that started under an older
+     * generation must not touch state or files — a stop() (or a test's
+     * cleanup) can land while a registration is still in flight.
+     */
+    private generation;
+    /**
+     * Crewly home, resolved once at start(). Resolving it at write time let a
+     * write that outlived its caller land in a different home (a test that
+     * had already restored CREWLY_HOME wrote a random id into the owner's
+     * real ~/.crewly — 2026-10-02).
+     */
+    private crewlyHome;
     /** Peer reported by the last registration, so a repeat is not logged at info. */
     private lastLoggedPeer;
     /** Consecutive heartbeat failure count */
@@ -173,6 +204,22 @@ export declare class CloudSyncService extends EventEmitter {
      * @throws Error when not started or the HTTP send fails
      */
     sendToPeerQueueId(peerQueueId: string, type: MessageType, payload: unknown): Promise<void>;
+    /**
+     * One registration attempt, then schedule the next: the keep-alive
+     * interval after a success, the backoff after a failure. Never gives up —
+     * a machine without a queue is deaf to Cloud and Slack, and on 2026-10-02
+     * one sat like that for half an hour after a single 429 at boot.
+     *
+     * @param gen - Generation this cycle belongs to (a stale cycle exits)
+     */
+    private runRegisterCycle;
+    /**
+     * Schedule the next registration attempt.
+     *
+     * @param gen - Generation the attempt belongs to
+     * @param delayMs - Gap before it
+     */
+    private scheduleRegister;
     /**
      * Register with the Cloud relay message queue.
      *
@@ -180,16 +227,38 @@ export declare class CloudSyncService extends EventEmitter {
      * derived from the JWT user ID. This allows both devices of the same user
      * to auto-discover each other's queueId for message routing.
      *
-     * The assigned queueId is used for message polling. The peerQueueId
-     * (other device's queue) is used for sending.
+     * Which id to claim, in order:
+     * 1. the queue this process already registered — a running machine never
+     *    switches queues (each switch left the old queue behind and used up
+     *    the relay's per-user quota: f68e1995 → a8eeab1d → d5c4ebc2 in one
+     *    day, all on one MacBook, when something rewrote the id file);
+     * 2. the id remembered in `<crewlyHome>/cloud/relay-queue.json`;
+     * 3. the device id.
+     *
+     * @param gen - Generation of the calling cycle
+     * @throws Error when registration fails (the caller retries)
      */
     private registerQueue;
+    /**
+     * Keep the id file in step with the queue we actually hold, so the next
+     * boot claims the same queue instead of creating another: rewrite it when
+     * it names a different queue, remove it when we hold the device-id queue
+     * (the file is only for the fallback case).
+     *
+     * @param registered - The id just registered
+     * @param remembered - What the file said before this attempt
+     * @param deviceId - This machine's device id
+     * @param gen - Generation of the calling cycle
+     */
+    private syncFallbackFile;
     /**
      * One registration attempt against a specific queue id.
      *
      * @param queueId - The id to claim
      * @param pairingCode - Deterministic code derived from the signed-in user
+     * @param gen - Generation of the calling cycle
      * @throws {QueueForbiddenError} When the relay says the queue is someone else's
+     * @throws Error on any other failure, or when Cloud Sync stopped meanwhile
      */
     private registerQueueAs;
     /**
@@ -206,7 +275,7 @@ export declare class CloudSyncService extends EventEmitter {
      * @returns The polled queue id, else the device id
      */
     private relayDeviceId;
-    /** Where a queue id taken after a 403 is remembered. */
+    /** Where a queue id taken after a 403 is remembered (home resolved at start()). */
     private fallbackQueueFile;
     /**
      * The queue id this machine fell back to previously, if any.
@@ -219,6 +288,7 @@ export declare class CloudSyncService extends EventEmitter {
      * time — the relay caps queues per user.
      *
      * @param queueId - The id that was accepted
+     * @param gen - Generation of the calling cycle (a stale one writes nothing)
      */
     private writeFallbackQueueId;
     /**

package/dist/cli/backend/src/services/cloud/cloud-sync.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloud-sync.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/cloud/cloud-sync.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cloud-sync.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/cloud/cloud-sync.service.ts"],"names":[],"mappings":"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"}

package/dist/cli/backend/src/services/cloud/cloud-sync.service.js

@@ -75,6 +75,17 @@ async function gatherTeamSummaries() {
         return [];
     }
 }
+/**
+ * Gap before the next queue registration after `failures` consecutive
+ * failures: REGISTER_RETRY_BACKOFF_MS in order, then its last value forever.
+ *
+ * @param failures - Consecutive failures so far (>= 1)
+ * @returns Delay in ms
+ */
+export function registerRetryDelay(failures) {
+    const steps = CLOUD_SYNC_CONSTANTS.REGISTER_RETRY_BACKOFF_MS;
+    return steps[Math.min(Math.max(failures, 1), steps.length) - 1];
+}
 // ---------------------------------------------------------------------------
 // Service
 // ---------------------------------------------------------------------------
@@ -123,8 +134,31 @@ export class CloudSyncService extends EventEmitter {
     messagePollRunning = false;
     /** When the last message-poll cycle finished (watchdog input). */
     lastMessagePollAt = 0;
-    /** Queue re-register timer handle (lets relay evict stale Portal pairs). */
+    /**
+     * Next queue registration (self-scheduling): every REGISTER_INTERVAL_MS
+     * while registered (lets the relay evict stale Portal pairs), on the
+     * REGISTER_RETRY_BACKOFF_MS schedule while registration fails.
+     */
     registerTimer = null;
+    /** Consecutive failed queue registrations */
+    queueFailures = 0;
+    /** Epoch ms of the first failure in the current registration failure streak */
+    queueFailingSince = null;
+    /** Epoch ms of the next scheduled registration */
+    nextQueueAttemptAt = null;
+    /**
+     * Bumped by start() and stop(). An attempt that started under an older
+     * generation must not touch state or files — a stop() (or a test's
+     * cleanup) can land while a registration is still in flight.
+     */
+    generation = 0;
+    /**
+     * Crewly home, resolved once at start(). Resolving it at write time let a
+     * write that outlived its caller land in a different home (a test that
+     * had already restored CREWLY_HOME wrote a random id into the owner's
+     * real ~/.crewly — 2026-10-02).
+     */
+    crewlyHome = null;
     /** Peer reported by the last registration, so a repeat is not logged at info. */
     lastLoggedPeer = null;
     /** Consecutive heartbeat failure count */
@@ -203,6 +237,14 @@ export class CloudSyncService extends EventEmitter {
         this.config = config;
         this.state = 'syncing';
         this.startedAt = Date.now();
+        this.generation += 1;
+        this.crewlyHome = process.env['CREWLY_HOME'] ?? join(homedir(), '.crewly');
+        // The queue is re-chosen per start (a re-login may be another account).
+        this.queueId = null;
+        this.queueError = null;
+        this.queueFailures = 0;
+        this.queueFailingSince = null;
+        this.lastLoggedPeer = null;
         this.authRejected = false;
         this.heartbeatFailures = 0;
         this.devicePollFailures = 0;
@@ -216,16 +258,9 @@ export class CloudSyncService extends EventEmitter {
         readVersion().then((v) => { this.version = v; }).catch(() => { });
         // Register with Cloud message queue for inter-device messaging.
         // This gets us a queueId used for message polling and makes us
-        // discoverable by peer devices with the same pairing code.
-        this.registerQueue().catch((err) => {
-            this.queueError = err instanceof Error ? err.message : String(err);
-            // Not "may not work": without a queue id the Slack instance heartbeat
-            // is skipped, so Cloud marks this machine stale and every inbound
-            // Slack event is queued instead of delivered (2026-09-21).
-            this.logger.error('Queue registration failed — this machine will not receive Cloud or Slack messages', {
-                error: this.queueError,
-            });
-        });
+        // discoverable by peer devices with the same pairing code. Retries on
+        // its own schedule until it succeeds (see runRegisterCycle).
+        void this.runRegisterCycle(this.generation);
         // Perform initial sync immediately
         this.sendHeartbeat().catch(() => { });
         this.pollDevices().catch(() => { });
@@ -239,18 +274,12 @@ export class CloudSyncService extends EventEmitter {
         // held long-poll never overlaps the next request. Kicks off immediately;
         // each cycle picks its own next gap (see runMessagePollCycle).
         this.scheduleNextMessagePoll(0);
-        // Periodic re-register lets the relay's stale-pair eviction kick in
-        // when a previously-paired Portal closes uncleanly. Without this,
-        // OSS would stay wedged against a dead Portal session until restart.
-        this.registerTimer = setInterval(() => { this.registerQueue().catch(() => { }); }, CLOUD_SYNC_CONSTANTS.REGISTER_INTERVAL_MS);
-        // Unref timers so they don't keep the process alive (messagePollTimer is
-        // unref'd inside scheduleNextMessagePoll on each cycle).
+        // Unref timers so they don't keep the process alive (messagePollTimer and
+        // registerTimer are unref'd where they are scheduled).
         if (this.heartbeatTimer.unref)
             this.heartbeatTimer.unref();
         if (this.devicePollTimer.unref)
             this.devicePollTimer.unref();
-        if (this.registerTimer.unref)
-            this.registerTimer.unref();
     }
     /**
      * Stop the Cloud Sync service.
@@ -274,9 +303,11 @@ export class CloudSyncService extends EventEmitter {
             this.messagePollTimer = null;
         }
         if (this.registerTimer) {
-            clearInterval(this.registerTimer);
+            clearTimeout(this.registerTimer);
             this.registerTimer = null;
         }
+        this.nextQueueAttemptAt = null;
+        this.generation += 1;
         if (this.errorRecoveryTimer) {
             clearInterval(this.errorRecoveryTimer);
             this.errorRecoveryTimer = null;
@@ -318,6 +349,13 @@ export class CloudSyncService extends EventEmitter {
             lastContactAt: this.lastContactAt || null,
             startedAt: this.startedAt || null,
             authRejected: this.authRejected,
+            relayQueue: {
+                queueId: this.queueId,
+                error: this.queueError,
+                failingSince: this.queueFailingSince,
+                failures: this.queueFailures,
+                nextAttemptAt: this.nextQueueAttemptAt,
+            },
         };
     }
     /** Record a request Cloud answered successfully. */
@@ -455,6 +493,67 @@ export class CloudSyncService extends EventEmitter {
     // -------------------------------------------------------------------------
     // Internal: Queue Registration
     // -------------------------------------------------------------------------
+    /**
+     * One registration attempt, then schedule the next: the keep-alive
+     * interval after a success, the backoff after a failure. Never gives up —
+     * a machine without a queue is deaf to Cloud and Slack, and on 2026-10-02
+     * one sat like that for half an hour after a single 429 at boot.
+     *
+     * @param gen - Generation this cycle belongs to (a stale cycle exits)
+     */
+    async runRegisterCycle(gen) {
+        if (gen !== this.generation || !this.config)
+            return;
+        let delay = CLOUD_SYNC_CONSTANTS.REGISTER_INTERVAL_MS;
+        try {
+            await this.registerQueue(gen);
+            if (gen !== this.generation)
+                return;
+            if (this.queueFailures > 0) {
+                this.logger.info('Queue registration succeeded after failing', {
+                    failures: this.queueFailures,
+                    queueId: this.queueId,
+                });
+            }
+            this.queueFailures = 0;
+            this.queueFailingSince = null;
+        }
+        catch (err) {
+            if (gen !== this.generation)
+                return;
+            this.queueError = err instanceof Error ? err.message : String(err);
+            this.queueFailures += 1;
+            this.queueFailingSince ??= Date.now();
+            delay = registerRetryDelay(this.queueFailures);
+            // Not "may not work": without a queue id the Slack instance heartbeat
+            // is skipped, so Cloud marks this machine stale and every inbound
+            // Slack event is queued instead of delivered (2026-09-21).
+            const level = this.queueId === null ? 'error' : 'warn';
+            this.logger[level](this.queueId === null
+                ? 'Queue registration failed — this machine will not receive Cloud or Slack messages until it succeeds'
+                : 'Queue re-registration failed — still polling the queue registered earlier', { error: this.queueError, attempt: this.queueFailures, retryInMs: delay });
+        }
+        this.scheduleRegister(gen, delay);
+    }
+    /**
+     * Schedule the next registration attempt.
+     *
+     * @param gen - Generation the attempt belongs to
+     * @param delayMs - Gap before it
+     */
+    scheduleRegister(gen, delayMs) {
+        if (gen !== this.generation)
+            return;
+        if (this.registerTimer)
+            clearTimeout(this.registerTimer);
+        this.nextQueueAttemptAt = Date.now() + delayMs;
+        this.registerTimer = setTimeout(() => {
+            this.registerTimer = null;
+            this.nextQueueAttemptAt = null;
+            void this.runRegisterCycle(gen);
+        }, delayMs);
+        this.registerTimer.unref?.();
+    }
     /**
      * Register with the Cloud relay message queue.
      *
@@ -462,52 +561,95 @@ export class CloudSyncService extends EventEmitter {
      * derived from the JWT user ID. This allows both devices of the same user
      * to auto-discover each other's queueId for message routing.
      *
-     * The assigned queueId is used for message polling. The peerQueueId
-     * (other device's queue) is used for sending.
+     * Which id to claim, in order:
+     * 1. the queue this process already registered — a running machine never
+     *    switches queues (each switch left the old queue behind and used up
+     *    the relay's per-user quota: f68e1995 → a8eeab1d → d5c4ebc2 in one
+     *    day, all on one MacBook, when something rewrote the id file);
+     * 2. the id remembered in `<crewlyHome>/cloud/relay-queue.json`;
+     * 3. the device id.
+     *
+     * @param gen - Generation of the calling cycle
+     * @throws Error when registration fails (the caller retries)
      */
-    async registerQueue() {
+    async registerQueue(gen) {
         if (!this.config)
-            return;
+            throw new Error('Cloud Sync is not running');
         // Derive deterministic pairing code from JWT user ID
         const pairingCode = await this.derivePairingCode();
         if (!pairingCode) {
-            this.logger.warn('Cannot register queue: unable to derive pairing code from token');
-            return;
+            throw new Error('Cannot register queue: unable to derive pairing code from token');
         }
         // The relay uses deviceId as the queue id, and refuses to hand a queue to
         // a different account than the one that created it — correct, but it
         // strands a machine whose owner signs in under another account: the
         // queue id is the machine's, and the 403 repeats on every boot. One
-        // MacBook sat deaf to Slack for two hours this way (2026-09-21). Keep
-        // asking for our own id first, and on a 403 take a fresh queue instead
-        // (persisted, so we do not mint one per restart and eat the quota).
-        const own = await this.readFallbackQueueId();
-        const first = own ?? this.config.deviceId;
+        // MacBook sat deaf to Slack for two hours this way (2026-09-21). On a
+        // 403 take a fresh queue (persisted, so we do not mint one per restart
+        // and eat the quota). A 403 means the queue is not ours, so minting a
+        // replacement never orphans a queue of ours.
+        const deviceId = this.config.deviceId;
+        const remembered = await this.readFallbackQueueId();
+        const first = this.queueId ?? remembered ?? deviceId;
         try {
-            await this.registerQueueAs(first, pairingCode);
+            await this.registerQueueAs(first, pairingCode, gen);
+            await this.syncFallbackFile(first, remembered, deviceId, gen);
             return;
         }
         catch (err) {
-            if (!(err instanceof QueueForbiddenError) || own)
+            if (!(err instanceof QueueForbiddenError))
                 throw err;
-            this.logger.warn('Relay refused our device-id queue (it belongs to another account) — taking a fresh one', {
-                deviceId: this.config.deviceId,
+            this.logger.warn('Relay refused our queue (it belongs to another account) — taking a fresh one', {
+                queueId: first,
+                deviceId,
             });
         }
         const fresh = randomUUID();
-        await this.registerQueueAs(fresh, pairingCode);
-        await this.writeFallbackQueueId(fresh);
+        await this.registerQueueAs(fresh, pairingCode, gen);
+        await this.writeFallbackQueueId(fresh, gen);
+    }
+    /**
+     * Keep the id file in step with the queue we actually hold, so the next
+     * boot claims the same queue instead of creating another: rewrite it when
+     * it names a different queue, remove it when we hold the device-id queue
+     * (the file is only for the fallback case).
+     *
+     * @param registered - The id just registered
+     * @param remembered - What the file said before this attempt
+     * @param deviceId - This machine's device id
+     * @param gen - Generation of the calling cycle
+     */
+    async syncFallbackFile(registered, remembered, deviceId, gen) {
+        if (remembered === registered || gen !== this.generation)
+            return;
+        if (registered !== deviceId) {
+            this.logger.warn('Relay queue id file did not match the queue in use — restoring it', {
+                inUse: registered,
+                inFile: remembered,
+            });
+            await this.writeFallbackQueueId(registered, gen);
+            return;
+        }
+        if (remembered !== null) {
+            this.logger.warn('Relay queue id file named a queue this machine does not use — removing it', {
+                inUse: registered,
+                inFile: remembered,
+            });
+            await fsp.rm(this.fallbackQueueFile(), { force: true }).catch(() => { });
+        }
     }
     /**
      * One registration attempt against a specific queue id.
      *
      * @param queueId - The id to claim
      * @param pairingCode - Deterministic code derived from the signed-in user
+     * @param gen - Generation of the calling cycle
      * @throws {QueueForbiddenError} When the relay says the queue is someone else's
+     * @throws Error on any other failure, or when Cloud Sync stopped meanwhile
      */
-    async registerQueueAs(queueId, pairingCode) {
-        if (!this.config)
-            return;
+    async registerQueueAs(queueId, pairingCode, gen) {
+        if (!this.config || gen !== this.generation)
+            throw new Error('Cloud Sync stopped during queue registration');
         const url = `${this.config.cloudUrl}/api/v1/relay/queue/register`;
         const response = await fetch(url, {
             method: 'POST',
@@ -528,19 +670,21 @@ export class CloudSyncService extends EventEmitter {
             throw new Error(message);
         }
         const data = await response.json();
-        if (data.queueId) {
-            // Re-registered every minute to keep the queue alive; only a change is
-            // worth an info line (it was 1,442 identical lines a day).
-            const peer = data.peerQueueId ?? 'none (waiting for peer)';
-            const changed = data.queueId !== this.queueId || peer !== this.lastLoggedPeer || this.queueError !== null;
-            this.queueId = data.queueId;
-            this.queueError = null;
-            this.lastLoggedPeer = peer;
-            this.logger[changed ? 'info' : 'debug']('Registered with Cloud message queue', {
-                queueId: this.queueId,
-                peerQueueId: peer,
-            });
-        }
+        if (gen !== this.generation)
+            throw new Error('Cloud Sync stopped during queue registration');
+        if (!data.queueId)
+            throw new Error('Queue registration failed: the relay returned no queue id');
+        // Re-registered every minute to keep the queue alive; only a change is
+        // worth an info line (it was 1,442 identical lines a day).
+        const peer = data.peerQueueId ?? 'none (waiting for peer)';
+        const changed = data.queueId !== this.queueId || peer !== this.lastLoggedPeer || this.queueError !== null;
+        this.queueId = data.queueId;
+        this.queueError = null;
+        this.lastLoggedPeer = peer;
+        this.logger[changed ? 'info' : 'debug']('Registered with Cloud message queue', {
+            queueId: this.queueId,
+            peerQueueId: peer,
+        });
     }
     /**
      * The id the relay knows this machine by: the queue we actually poll.
@@ -558,9 +702,10 @@ export class CloudSyncService extends EventEmitter {
     relayDeviceId() {
         return this.queueId ?? this.config?.deviceId ?? '';
     }
-    /** Where a queue id taken after a 403 is remembered. */
+    /** Where a queue id taken after a 403 is remembered (home resolved at start()). */
     fallbackQueueFile() {
-        return join(process.env['CREWLY_HOME'] ?? join(homedir(), '.crewly'), 'cloud', 'relay-queue.json');
+        const home = this.crewlyHome ?? process.env['CREWLY_HOME'] ?? join(homedir(), '.crewly');
+        return join(home, 'cloud', 'relay-queue.json');
     }
     /**
      * The queue id this machine fell back to previously, if any.
@@ -582,8 +727,11 @@ export class CloudSyncService extends EventEmitter {
      * time — the relay caps queues per user.
      *
      * @param queueId - The id that was accepted
+     * @param gen - Generation of the calling cycle (a stale one writes nothing)
      */
-    async writeFallbackQueueId(queueId) {
+    async writeFallbackQueueId(queueId, gen) {
+        if (gen !== this.generation)
+            return;
         const file = this.fallbackQueueFile();
         try {
             await fsp.mkdir(dirname(file), { recursive: true });