agent-tempo 1.7.0-beta.8 → 1.7.0

package/dist/adapters/claude-code/adapter.js

@@ -2,7 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InteractiveAttachment = exports.claudeCodeDescriptor = void 0;
 const base_1 = require("../base");
+const idle_backoff_1 = require("../sdk/idle-backoff");
 const terminal_error_1 = require("../terminal-error");
+const action_counters_1 = require("../../utils/action-counters");
 const config_1 = require("../../config");
 const log = (...args) => console.error('[agent-tempo:poller]', ...args);
 /**
@@ -21,9 +23,11 @@ exports.claudeCodeDescriptor = {
     // heartbeat loop at this interval when the V2 lifecycle path is active.
     heartbeatMs: 60_000,
 };
-const POLL_BASE_MS = 2000;
-const POLL_BACKOFF_FACTOR = 1.5;
-const POLL_MAX_MS = 30000;
+// #749: one family of backoff curves across the codebase — this poller's
+// error backoff shares the SDK idle-backoff constants (values unchanged:
+// 2s base, 1.5× growth, 30s cap; imported at the top of the file). Static
+// defaults only; the AGENT_TEMPO_SDK_POLL_* env overrides apply to SDK
+// adapters, not here.
 /**
  * Poll a session workflow for pending messages and deliver them via `onMessages`.
  *
@@ -48,7 +52,7 @@ const POLL_MAX_MS = 30000;
 function startMessagePoller(handle, onMessages) {
     let stopped = false;
     let timeout = null;
-    let currentInterval = POLL_BASE_MS;
+    let currentInterval = idle_backoff_1.SDK_POLL_BASE_MS;
     let consecutiveErrors = 0;
     const cleanupTimer = () => {
         if (timeout) {
@@ -56,7 +60,9 @@ function startMessagePoller(handle, onMessages) {
             timeout = null;
         }
     };
-    const poll = async () => {
+    // #753 — meter each poll tick's Temporal calls (pendingMessages query +
+    // markDelivered signal) under 'sdk-poller'.
+    const poll = () => (0, action_counters_1.withActionSource)('sdk-poller', async () => {
         if (stopped)
             return;
         try {
@@ -69,7 +75,7 @@ function startMessagePoller(handle, onMessages) {
                 await handle.signal('markDelivered', ids);
             }
             // Reset backoff on successful poll
-            currentInterval = POLL_BASE_MS;
+            currentInterval = idle_backoff_1.SDK_POLL_BASE_MS;
             consecutiveErrors = 0;
         }
         catch (err) {
@@ -88,15 +94,15 @@ function startMessagePoller(handle, onMessages) {
             }
             consecutiveErrors++;
             // Apply exponential backoff on errors
-            currentInterval = Math.min(currentInterval * POLL_BACKOFF_FACTOR, POLL_MAX_MS);
+            currentInterval = Math.min(currentInterval * idle_backoff_1.SDK_POLL_BACKOFF_FACTOR, idle_backoff_1.SDK_POLL_MAX_MS);
             log(`Poll error (attempt ${consecutiveErrors}, next in ${Math.round(currentInterval)}ms):`, err);
         }
         if (!stopped) {
             timeout = setTimeout(poll, currentInterval);
         }
-    };
+    });
     // Start the first poll
-    timeout = setTimeout(poll, POLL_BASE_MS);
+    timeout = setTimeout(poll, idle_backoff_1.SDK_POLL_BASE_MS);
     return () => {
         stopped = true;
         cleanupTimer();

package/dist/adapters/claude-code-headless/adapter.js

@@ -80,6 +80,7 @@ const client_1 = require("@temporalio/client");
 const base_1 = require("../sdk/base");
 const config_1 = require("../../config");
 const connection_1 = require("../../connection");
+const action_counters_1 = require("../../utils/action-counters");
 const signals_1 = require("../../workflows/signals");
 const stream_json_1 = require("./stream-json");
 const error_mapper_1 = require("./error-mapper");
@@ -130,7 +131,8 @@ const log = (...args) => {
     }).join(' ')}\n`;
     fs.writeSync(2, msg);
 };
-/** Idle poll cadence — short enough for snappy cue delivery, loose on Temporal. */
+/** Busy-wait cadence (ms) while a turn is in flight. The IDLE cadence is owned
+ * by the inherited `pollBackoff` (#749): 2s base → 30s cap, reset on delivery. */
 const POLL_INTERVAL_MS = 2000;
 /** Workflow-register poll bounds — same as claude-api/opencode. */
 const WORKFLOW_REGISTER_ATTEMPTS = 30;
@@ -266,6 +268,7 @@ class ClaudeCodeHeadlessAttachment extends base_1.SdkAttachment {
         const client = new client_1.Client({
             connection,
             namespace: config.temporalNamespace,
+            interceptors: (0, action_counters_1.actionCountingInterceptors)(),
         });
         this.configureV2(client, os.hostname());
         // Wait for the session workflow to register in Temporal (the spawn
@@ -352,6 +355,10 @@ class ClaudeCodeHeadlessAttachment extends base_1.SdkAttachment {
             await cleanup();
             process.exit(1);
         }
+        // T1.1 PR-2 — cue doorbell: ding ⇒ immediate poll + backoff reset;
+        // connected ⇒ 60s idle ceiling. No token / daemon down ⇒ silent no-op
+        // (pure #761 polling).
+        this.startDoorbell(config.ensemble, playerIdForWorkflow);
         // PID file so callers can find / kill orphaned adapter processes.
         // #690 — write/unlink the EXACT path the spawner computed (ENV.PID_FILE) so the
         // adapter pid can't diverge from the spawner's; helper fallback for a manual launch.
@@ -377,7 +384,9 @@ class ClaudeCodeHeadlessAttachment extends base_1.SdkAttachment {
         process.on('SIGINT', shutdown);
         process.on('SIGTERM', shutdown);
         // Drive the poll loop until cleanup is requested.
-        await this.pollLoop(handle);
+        // #753 — meter its Temporal calls under 'sdk-poller'.
+        await (0, action_counters_1.withActionSource)('sdk-poller', () => this.pollLoop(handle));
+        this.stopDoorbell();
         try {
             fs.unlinkSync(pidFile);
         }
@@ -397,6 +406,9 @@ class ClaudeCodeHeadlessAttachment extends base_1.SdkAttachment {
         let processing = false;
         let pollCount = 0;
         const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+        // #749: fresh poll loop starts at the fast cadence — never inherit a
+        // stale 30s interval across a restart.
+        this.pollBackoff.reset();
         while (polling && !this.shouldStop()) {
             pollCount++;
             // Periodic workflow-status check — detect external destroy / completion.
@@ -434,13 +446,19 @@ class ClaudeCodeHeadlessAttachment extends base_1.SdkAttachment {
             }
             catch (err) {
                 log(`pendingMessages query failed: ${err?.message ?? err}`);
-                await sleep(POLL_INTERVAL_MS);
+                // #749: grow on errors too — don't hammer a wedged worker at 2s.
+                // T1.1: pollSleep is doorbell-interruptible — a ding ends it early.
+                await this.pollSleep(this.pollBackoff.next(false));
                 continue;
             }
             if (messages.length === 0) {
-                await sleep(POLL_INTERVAL_MS);
+                // #749: idle backoff — 2s → 30s while nothing is pending (60s
+                // ceiling while the T1.1 doorbell is connected; a ding wakes it).
+                await this.pollSleep(this.pollBackoff.next(false));
                 continue;
             }
+            // #749: live conversation — snap back to the fast cadence.
+            this.pollBackoff.reset();
             processing = true;
             try {
                 const ackIds = messages.map((m) => m.id);

package/dist/adapters/copilot/adapter.js

@@ -74,6 +74,7 @@ const path = __importStar(require("path"));
 const client_1 = require("@temporalio/client");
 const config_1 = require("../../config");
 const connection_1 = require("../../connection");
+const action_counters_1 = require("../../utils/action-counters");
 const base_1 = require("../sdk/base");
 // #536 — shared SDK-class system-prompt + MAESTRO_ACK (was inline
 // here pre-#536; moved to the shared module so the post-#536
@@ -128,11 +129,17 @@ const log = (...args) => {
 };
 /** Filter process.env to exclude undefined values (safe to spread as Record<string, string>). */
 const cleanEnv = () => Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined));
+/**
+ * Busy-wait cadence (ms) while a turn is in flight. The IDLE cadence is owned
+ * by the inherited `pollBackoff` (#749, T0.2): 2s base stretching to a 30s
+ * cap on empty polls, snapping back to base on any delivered message.
+ */
 const POLL_INTERVAL_MS = 2000;
 const CREATE_SESSION_TIMEOUT_MS = 45_000;
 const MAX_CONSECUTIVE_FAILURES = 3;
 const MAX_SESSION_RECREATIONS = 2;
-/** Check workflow status every N polls (~30s at 2s interval). */
+/** Check workflow status every N polls (30s–7.5min depending on the #749
+ * idle-backoff cadence; the busier the player, the fresher the check). */
 const WORKFLOW_STATUS_CHECK_INTERVAL = 15;
 /** Proactively recreate the Copilot session after this idle period (ms). Default 60 min. */
 const SESSION_MAX_IDLE_MS = 60 * 60 * 1000;
@@ -233,6 +240,7 @@ class CopilotSdkAttachment extends base_1.SdkAttachment {
         const client = new client_1.Client({
             connection,
             namespace: config.temporalNamespace,
+            interceptors: (0, action_counters_1.actionCountingInterceptors)(),
         });
         // Hand the client + host to BaseAttachment so startV2Lifecycle (below) can
         // issue claimAttachment + heartbeat against it. No-op on legacy path.
@@ -457,6 +465,10 @@ class CopilotSdkAttachment extends base_1.SdkAttachment {
             const expectedAttachmentId = process.env[config_1.ENV.ATTACHMENT_ID] || undefined;
             handle = await this.startV2Lifecycle(expectedWorkflowId, expectedAttachmentId);
             log(`V2 attachment claimed (attachmentId=${this.token?.attachmentId}${expectedAttachmentId ? ', renewed' : ''})`);
+            // T1.1 PR-2 — cue doorbell: ding ⇒ immediate poll tick + backoff
+            // reset; connected ⇒ 60s idle ceiling. No token / daemon down ⇒
+            // silent no-op (pure #761 polling).
+            this.startDoorbell(config.ensemble, playerIdForWorkflow);
         }
         catch (err) {
             log(`ERROR: V2 claimAttachment failed: ${err?.message ?? err}`);
@@ -506,8 +518,6 @@ class CopilotSdkAttachment extends base_1.SdkAttachment {
         let sessionRecreations = 0;
         let proactiveRecreations = 0;
         let lastActivityTime = Date.now();
-        // interval declared here, assigned after poll is defined
-        let interval;
         // Shared cleanup — disconnects session, removes PID file, stops client.
         let shuttingDown = false;
         const cleanup = async () => {
@@ -515,7 +525,10 @@ class CopilotSdkAttachment extends base_1.SdkAttachment {
                 return;
             shuttingDown = true;
             polling = false;
-            clearInterval(interval);
+            // T1.1 — end the doorbell stream and pop any parked inter-tick sleep
+            // so the scheduler chain observes `polling = false` promptly.
+            this.stopDoorbell();
+            this.wakePollSleep();
             // V2 graceful detach — fires `adapterExited` so the workflow collapses
             // draining → detached immediately per §11.1. No-op if V2 was off or if
             // startV2Lifecycle never ran successfully.
@@ -597,12 +610,19 @@ class CopilotSdkAttachment extends base_1.SdkAttachment {
                 return false;
             }
         };
+        /**
+         * One poll tick. Returns the delay (ms) before the next tick; the
+         * scheduler (`runPollTick`) re-checks `polling` before arming the timer,
+         * so shutdown needs no sentinel return (exit paths call `process.exit`).
+         * #749: idle ticks grow the inherited `pollBackoff` toward 30s; delivered
+         * messages snap back to the 2s base.
+         */
         const poll = async () => {
             if (!polling || processing)
-                return;
+                return POLL_INTERVAL_MS; // stopped or busy — scheduler gates on `polling`
             pollCount++;
             // Periodic health check
-            if (pollCount % 30 === 0) { // every ~60 seconds
+            if (pollCount % 30 === 0) { // every 30 polls (~60s busy, up to ~15min idle)
                 const silenceSec = ((Date.now() - lastEventTime) / 1000).toFixed(0);
                 log(`[health] poll #${pollCount}, sessionAlive=${sessionAlive}, lastEvent=${lastEventType} ${silenceSec}s ago`);
             }
@@ -663,8 +683,9 @@ class CopilotSdkAttachment extends base_1.SdkAttachment {
             }
             try {
                 const messages = await handle.query('pendingMessages');
+                // #749: idle backoff — nothing pending, stretch the next poll.
                 if (messages.length === 0)
-                    return;
+                    return this.pollBackoff.next(false);
                 processing = true;
                 const ids = messages.map((m) => m.id);
                 // Format messages into a single prompt, appending ack instruction for Maestro messages
@@ -704,6 +725,9 @@ class CopilotSdkAttachment extends base_1.SdkAttachment {
                 lastActivityTime = Date.now();
                 sessionAlive = true;
                 processing = false;
+                // #749: live conversation — snap back to the fast cadence so
+                // follow-up cues land at 2s responsiveness.
+                return this.pollBackoff.next(true);
             }
             catch (err) {
                 processing = false;
@@ -718,10 +742,36 @@ class CopilotSdkAttachment extends base_1.SdkAttachment {
                         await cleanup();
                         process.exit(2);
                     }
+                    // Recovered — retry promptly so pending messages drain.
+                    return this.pollBackoff.next(true);
                 }
+                // #749: grow on errors too — don't hammer a failing session/worker.
+                return this.pollBackoff.next(false);
             }
         };
-        interval = setInterval(poll, POLL_INTERVAL_MS);
+        // #749: self-scheduling poll chain (replaces the fixed-2s setInterval —
+        // a tick now schedules its successor AFTER it completes, so long ticks
+        // can no longer stack skipped-overlap invocations).
+        // #753 — meter each poll tick's Temporal calls under 'sdk-poller'.
+        const runPollTick = async () => {
+            const delay = await (0, action_counters_1.withActionSource)('sdk-poller', poll).catch((err) => {
+                // poll() has its own catch — this guards the scheduling chain itself.
+                log(`poll tick threw outside its handler: ${err?.message ?? err}`);
+                return POLL_INTERVAL_MS;
+            });
+            if (polling) {
+                // T1.1 — the inter-tick wait is doorbell-interruptible: a ding pops
+                // it (and reset the backoff) so the next tick runs immediately.
+                await this.pollSleep(delay);
+                if (polling)
+                    void runPollTick();
+            }
+        };
+        this.pollBackoff.reset();
+        void this.pollSleep(POLL_INTERVAL_MS).then(() => {
+            if (polling)
+                void runPollTick();
+        });
         log('Message poller started. Bridge is running.');
         // Graceful shutdown on SIGINT/SIGTERM — signal the workflow before exiting
         const shutdown = async () => {

package/dist/adapters/opencode/adapter.js

@@ -71,6 +71,7 @@ const client_1 = require("@temporalio/client");
 const base_1 = require("../sdk/base");
 const config_1 = require("../../config");
 const connection_1 = require("../../connection");
+const action_counters_1 = require("../../utils/action-counters");
 const signals_1 = require("../../workflows/signals");
 const server_tools_1 = require("../../server-tools");
 const config_2 = require("./config");
@@ -130,7 +131,8 @@ const log = (...args) => {
 const DEFAULT_MODEL = 'anthropic/claude-opus-4-7';
 /** Tested-pinned OpenCode SDK version — drift triggers a stderr WARNING. */
 const TESTED_OPENCODE_VERSION = '~1.14.29';
-/** Idle poll cadence — short enough for snappy cue delivery, loose on Temporal. */
+/** Busy-wait cadence (ms) while a turn is in flight. The IDLE cadence is owned
+ * by the inherited `pollBackoff` (#749): 2s base → 30s cap, reset on delivery. */
 const POLL_INTERVAL_MS = 2000;
 /** Workflow-register poll bounds. */
 const WORKFLOW_REGISTER_ATTEMPTS = 30;
@@ -305,7 +307,11 @@ class OpenCodeAttachment extends base_1.SdkAttachment {
         }
         // (5) Connect Temporal, wait for workflow, hand client to BaseAttachment.
         const connection = await (0, connection_1.createTemporalConnection)(config);
-        const client = new client_1.Client({ connection, namespace: config.temporalNamespace });
+        const client = new client_1.Client({
+            connection,
+            namespace: config.temporalNamespace,
+            interceptors: (0, action_counters_1.actionCountingInterceptors)(),
+        });
         this.configureV2(client, os.hostname());
         log(`Waiting for workflow ${expectedWorkflowId} to register...`);
         let handle = client.workflow.getHandle(expectedWorkflowId);
@@ -379,6 +385,10 @@ class OpenCodeAttachment extends base_1.SdkAttachment {
             await cleanup();
             process.exit(1);
         }
+        // T1.1 PR-2 — cue doorbell: ding ⇒ immediate poll + backoff reset;
+        // connected ⇒ 60s idle ceiling. No token / daemon down ⇒ silent no-op
+        // (pure #761 polling).
+        this.startDoorbell(config.ensemble, playerIdForWorkflow);
         // (9) PID file — two lines (adapter PID + opencode-serve PID) per
         // design §6.5. Operators can grep / kill either.
         const pidFile = path.join(logDir, `${playerIdForWorkflow}.pid`);
@@ -401,8 +411,9 @@ class OpenCodeAttachment extends base_1.SdkAttachment {
         };
         process.on('SIGINT', shutdown);
         process.on('SIGTERM', shutdown);
-        // (11) Drive the poll loop.
-        await this.pollLoop(handle);
+        // (11) Drive the poll loop. #753 — meter its Temporal calls under 'sdk-poller'.
+        await (0, action_counters_1.withActionSource)('sdk-poller', () => this.pollLoop(handle));
+        this.stopDoorbell();
         try {
             fs.unlinkSync(pidFile);
         }
@@ -416,6 +427,9 @@ class OpenCodeAttachment extends base_1.SdkAttachment {
         let polling = true;
         let processing = false;
         let pollCount = 0;
+        // #749: fresh poll loop starts at the fast cadence — never inherit a
+        // stale 30s interval across a restart.
+        this.pollBackoff.reset();
         while (polling && !this.shouldStop()) {
             pollCount++;
             // Periodic workflow-status check — detect external destroy / completion.
@@ -453,13 +467,19 @@ class OpenCodeAttachment extends base_1.SdkAttachment {
             }
             catch (err) {
                 log(`pendingMessages query failed: ${err?.message ?? err}`);
-                await sleep(POLL_INTERVAL_MS);
+                // #749: grow on errors too — don't hammer a wedged worker at 2s.
+                // T1.1: pollSleep is doorbell-interruptible — a ding ends it early.
+                await this.pollSleep(this.pollBackoff.next(false));
                 continue;
             }
             if (messages.length === 0) {
-                await sleep(POLL_INTERVAL_MS);
+                // #749: idle backoff — 2s → 30s while nothing is pending (60s
+                // ceiling while the T1.1 doorbell is connected; a ding wakes it).
+                await this.pollSleep(this.pollBackoff.next(false));
                 continue;
             }
+            // #749: live conversation — snap back to the fast cadence.
+            this.pollBackoff.reset();
             processing = true;
             try {
                 const ackIds = messages.map((m) => m.id);

package/dist/adapters/sdk/base.d.ts

@@ -26,6 +26,7 @@
  */
 import type { WorkflowHandle } from '@temporalio/client';
 import { BaseAttachment, type BaseAttachmentOptions } from '../base';
+import { IdleBackoff } from './idle-backoff';
 import type { Message, DetachReason } from '../../types';
 /** Per-message result from `SdkAttachment.deliver()`. */
 export interface SdkDeliverResult {
@@ -57,6 +58,31 @@ export declare abstract class SdkAttachment extends BaseAttachment {
      * implementations to decide whether cancellation actually has an effect.
      */
     protected sdkInFlight: boolean;
+    /**
+     * #749 (T0.2) — shared idle-backoff delay computer for the subclass message
+     * poll loops. Contract: `next(messages.length > 0)` per tick — active
+     * conversations stay at the 2s base; idle stretches to the 30s cap (15×
+     * fewer billable `pendingMessages` queries on an idle player); any
+     * delivered message snaps back to base. Subclasses should `reset()` at
+     * poll-loop (re)start so a reconnect doesn't inherit a stale slow cadence.
+     * Heartbeat/phase-watcher cadences (BaseAttachment) are deliberately NOT
+     * driven by this — lease math depends on them (#249).
+     */
+    protected readonly pollBackoff: IdleBackoff;
+    /**
+     * T1.1 PR-2 — cue doorbell (docs/design/t11-cue-doorbell.md §2.4). Started
+     * by the concrete adapter via {@link startDoorbell} once it knows its
+     * `{ensemble, playerId}`; null until then and after {@link stopDoorbell}.
+     * A ding is a HINT: it wakes the poll sleep + resets the backoff — the
+     * poll itself (and its acks) remain the sole delivery path.
+     */
+    private doorbell;
+    /**
+     * The ding→immediate-poll primitive (level-triggered, identity-guarded —
+     * see {@link WakeableSleep}). Shared shape with the PR-3 Pi pump, which
+     * composes the same class without being an SdkAttachment.
+     */
+    private readonly pollSleeper;
     constructor(options?: BaseAttachmentOptions);
     /**
      * Deliver one message through the SDK turn. Wire-protocol surface:
@@ -86,6 +112,40 @@ export declare abstract class SdkAttachment extends BaseAttachment {
      *                  with one `markDelivered` signal — pass the full batch.
      */
     protected deliver(pinned: WorkflowHandle, msg: Message, prompt: string, timeoutMs: number, invokeSdk: (prompt: string, timeoutMs: number) => Promise<unknown>, ackIds?: string[]): Promise<SdkDeliverResult>;
+    /**
+     * T1.1 PR-2 — start the doorbell once the concrete adapter knows its
+     * identity (typically right after `startV2Lifecycle`). Wires:
+     *
+     *   - `ding` → `pollBackoff.reset()` + wake the parked {@link pollSleep}
+     *     (or set the pending bit if the loop is mid-tick) ⇒ the very next
+     *     poll runs now, at the fast cadence.
+     *   - connection state → idle ceiling: connected ⇒ 60s
+     *     (`SDK_POLL_DOORBELL_MAX_MS`), disconnected ⇒ the T0.2 30s floor.
+     *     Degradation is automatic and silent — daemon down means the player
+     *     behaves exactly like post-#761 (§5 of the design doc).
+     *
+     * No token / no daemon ⇒ the client never subscribes and this is a no-op
+     * beyond one breadcrumb. Idempotent per attachment (restart calls stop
+     * first).
+     */
+    protected startDoorbell(ensemble: string, playerId: string): void;
+    /** Tear down the doorbell stream (graceful detach, adapter exit). Idempotent. */
+    protected stopDoorbell(): void;
+    /**
+     * T1.1 PR-2 — doorbell-interruptible sleep for the subclass poll loops.
+     * Drop-in for the previous `await sleep(pollBackoff.next(...))` sites: a
+     * `ding` (or {@link wakePollSleep}) resolves it early so the next poll
+     * runs immediately; otherwise it behaves exactly like a plain sleep.
+     * A ding that landed while the loop was mid-tick resolves the NEXT call
+     * instantly (level-triggered pending bit — hints are consumed, not lost).
+     */
+    protected pollSleep(ms: number): Promise<void>;
+    /**
+     * Wake a parked {@link pollSleep} now (ding, or a subclass's own stop
+     * path wanting a prompt loop exit). No parked sleep ⇒ sets the pending
+     * bit so the next `pollSleep` returns immediately.
+     */
+    protected wakePollSleep(): void;
     /**
      * Subclass-facing convenience: call this from `startV2Lifecycle` path to
      * fire `adapterExited` on clean shutdown and tear down the V2 machinery.

package/dist/adapters/sdk/base.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SdkAttachment = void 0;
 const base_1 = require("../base");
 const signals_1 = require("../../workflows/signals");
+const idle_backoff_1 = require("./idle-backoff");
+const doorbell_client_1 = require("./doorbell-client");
 const log = (...args) => console.error('[agent-tempo:sdk-adapter]', ...args);
 /**
  * Abstract base for SDK-class adapters.
@@ -25,6 +27,31 @@ class SdkAttachment extends base_1.BaseAttachment {
      * implementations to decide whether cancellation actually has an effect.
      */
     sdkInFlight = false;
+    /**
+     * #749 (T0.2) — shared idle-backoff delay computer for the subclass message
+     * poll loops. Contract: `next(messages.length > 0)` per tick — active
+     * conversations stay at the 2s base; idle stretches to the 30s cap (15×
+     * fewer billable `pendingMessages` queries on an idle player); any
+     * delivered message snaps back to base. Subclasses should `reset()` at
+     * poll-loop (re)start so a reconnect doesn't inherit a stale slow cadence.
+     * Heartbeat/phase-watcher cadences (BaseAttachment) are deliberately NOT
+     * driven by this — lease math depends on them (#249).
+     */
+    pollBackoff = new idle_backoff_1.IdleBackoff();
+    /**
+     * T1.1 PR-2 — cue doorbell (docs/design/t11-cue-doorbell.md §2.4). Started
+     * by the concrete adapter via {@link startDoorbell} once it knows its
+     * `{ensemble, playerId}`; null until then and after {@link stopDoorbell}.
+     * A ding is a HINT: it wakes the poll sleep + resets the backoff — the
+     * poll itself (and its acks) remain the sole delivery path.
+     */
+    doorbell = null;
+    /**
+     * The ding→immediate-poll primitive (level-triggered, identity-guarded —
+     * see {@link WakeableSleep}). Shared shape with the PR-3 Pi pump, which
+     * composes the same class without being an SdkAttachment.
+     */
+    pollSleeper = new doorbell_client_1.WakeableSleep();
     constructor(options = {}) {
         super(options);
         // Wire the V2 lease-revoked signal (fired by BaseAttachment's phase watcher
@@ -122,12 +149,68 @@ class SdkAttachment extends base_1.BaseAttachment {
         }
         return { sdkResult, elapsedMs };
     }
+    /**
+     * T1.1 PR-2 — start the doorbell once the concrete adapter knows its
+     * identity (typically right after `startV2Lifecycle`). Wires:
+     *
+     *   - `ding` → `pollBackoff.reset()` + wake the parked {@link pollSleep}
+     *     (or set the pending bit if the loop is mid-tick) ⇒ the very next
+     *     poll runs now, at the fast cadence.
+     *   - connection state → idle ceiling: connected ⇒ 60s
+     *     (`SDK_POLL_DOORBELL_MAX_MS`), disconnected ⇒ the T0.2 30s floor.
+     *     Degradation is automatic and silent — daemon down means the player
+     *     behaves exactly like post-#761 (§5 of the design doc).
+     *
+     * No token / no daemon ⇒ the client never subscribes and this is a no-op
+     * beyond one breadcrumb. Idempotent per attachment (restart calls stop
+     * first).
+     */
+    startDoorbell(ensemble, playerId) {
+        this.stopDoorbell();
+        this.doorbell = new doorbell_client_1.DoorbellClient({
+            ensemble,
+            playerId,
+            onDing: () => {
+                this.pollBackoff.reset();
+                this.wakePollSleep();
+            },
+            onConnectionChange: (connected) => {
+                this.pollBackoff.setCeiling(connected ? (0, idle_backoff_1.resolveDoorbellCeilingMs)() : (0, idle_backoff_1.resolveIdleBackoffConfig)().maxMs);
+            },
+        });
+        this.doorbell.start();
+    }
+    /** Tear down the doorbell stream (graceful detach, adapter exit). Idempotent. */
+    stopDoorbell() {
+        this.doorbell?.stop();
+        this.doorbell = null;
+    }
+    /**
+     * T1.1 PR-2 — doorbell-interruptible sleep for the subclass poll loops.
+     * Drop-in for the previous `await sleep(pollBackoff.next(...))` sites: a
+     * `ding` (or {@link wakePollSleep}) resolves it early so the next poll
+     * runs immediately; otherwise it behaves exactly like a plain sleep.
+     * A ding that landed while the loop was mid-tick resolves the NEXT call
+     * instantly (level-triggered pending bit — hints are consumed, not lost).
+     */
+    pollSleep(ms) {
+        return this.pollSleeper.sleep(ms);
+    }
+    /**
+     * Wake a parked {@link pollSleep} now (ding, or a subclass's own stop
+     * path wanting a prompt loop exit). No parked sleep ⇒ sets the pending
+     * bit so the next `pollSleep` returns immediately.
+     */
+    wakePollSleep() {
+        this.pollSleeper.wake();
+    }
     /**
      * Subclass-facing convenience: call this from `startV2Lifecycle` path to
      * fire `adapterExited` on clean shutdown and tear down the V2 machinery.
      * Forwards to `BaseAttachment.stopV2Lifecycle` with graceful=true.
      */
     async detachGracefully(reason = 'user-stop') {
+        this.stopDoorbell();
         await this.stopV2Lifecycle(reason, /* graceful */ true);
     }
 }