agent-tempo 1.7.0-beta.8 → 1.7.0

package/dist/adapters/sdk/doorbell-client.d.ts

@@ -0,0 +1,106 @@
+/** Reconnect backoff: 1s doubling to a 30s cap (same family as the daemon's bind retry, #768). */
+export declare function doorbellReconnectDelayMs(retry: number, baseMs?: number, capMs?: number): number;
+/**
+ * Minimal streaming-fetch shape this client needs — injectable for tests.
+ * `body` must be an async-iterable of byte chunks (Node 18+ global `fetch`
+ * response bodies are).
+ */
+export type DoorbellFetch = (url: string, init: {
+    headers: Record<string, string>;
+    signal: AbortSignal;
+}) => Promise<{
+    status: number;
+    body: AsyncIterable<Uint8Array> | null;
+}>;
+export interface DoorbellClientOptions {
+    /** The player's ensemble (URL path segment). */
+    ensemble: string;
+    /** The player's id (URL path segment). */
+    playerId: string;
+    /** Fired once per `ding` event (already coalesced daemon-side). */
+    onDing: () => void;
+    /**
+     * Fired on connected/disconnected transitions. Drives the idle-poll
+     * ceiling (connected ⇒ 60s, disconnected ⇒ the T0.2 30s floor). Never
+     * fired redundantly (true→true / false→false).
+     */
+    onConnectionChange?: (connected: boolean) => void;
+    /** Ingest token. Defaults to `process.env[ENV.INGEST_TOKEN]`. */
+    ingestToken?: string;
+    /** Daemon port discovery. Defaults to {@link readPortFile}. */
+    readPort?: () => number | null;
+    /** HTTP transport. Defaults to global `fetch` (client disabled if absent). */
+    fetchFn?: DoorbellFetch;
+    /** Test seam — defaults to a real setTimeout sleep. */
+    sleep?: (ms: number) => Promise<void>;
+    log?: (...args: unknown[]) => void;
+    /** Reconnect backoff knobs (tests). */
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+}
+/**
+ * Incremental SSE block parser for the doorbell stream. Feed raw text
+ * chunks; returns the number of `ding` events completed by this chunk.
+ * Keepalive comments (`:ka`) and the `:closed` marker carry no event name
+ * and are ignored. Exported @internal for unit tests.
+ */
+export declare class DingParser {
+    private buffer;
+    feed(chunk: string): number;
+}
+/**
+ * Wakeable sleep — the ding→immediate-poll primitive, shared by
+ * `SdkAttachment` (PR-2) and the Pi cue pump (PR-3, which is NOT an
+ * SdkAttachment). Semantics:
+ *
+ *   - `sleep(ms)` parks until the timer fires OR `wake()` pops it early.
+ *   - `wake()` with no parked sleep sets a level-triggered pending bit so
+ *     the NEXT `sleep` returns immediately — a ding that lands while the
+ *     consumer is mid-tick is consumed, not lost (mirrors the daemon
+ *     registry's coalescing; extra wakes coalesce into one).
+ *   - One parked sleep at a time (one poll loop per consumer). A STALE
+ *     timer from an abandoned sleep (e.g. a `Promise.race` loser) is
+ *     identity-guarded so it can never clobber a newer sleep's waker.
+ */
+export declare class WakeableSleep {
+    private wakeFn;
+    private pending;
+    sleep(ms: number): Promise<void>;
+    wake(): void;
+}
+/**
+ * Reconnecting SSE consumer for the daemon doorbell. `start()` launches the
+ * detached connect loop; `stop()` aborts the live stream and ends it. All
+ * callbacks fire on the client's own async path — keep them cheap (the
+ * adapters' `onDing` just wakes a sleeping poll loop).
+ */
+export declare class DoorbellClient {
+    private readonly opts;
+    private readonly token;
+    private readonly readPort;
+    private readonly fetchFn;
+    private readonly sleep;
+    private readonly log;
+    private stopped;
+    private connected;
+    private abort;
+    private loop;
+    constructor(opts: DoorbellClientOptions);
+    /** Whether a doorbell stream is currently live (drives the poll ceiling). */
+    get isConnected(): boolean;
+    /**
+     * Launch the connect loop. No token / no fetch ⇒ logs one breadcrumb and
+     * never subscribes (§5: pure T0.2 behavior). Idempotent.
+     */
+    start(): void;
+    /** End the loop and abort any live stream. Idempotent. */
+    stop(): void;
+    private setConnected;
+    private runLoop;
+    /**
+     * One subscribe attempt. Returns `true` when the stream OPENED (HTTP 200)
+     * regardless of how it ended. Every failure path is silent-by-design
+     * below the transition breadcrumb.
+     */
+    private connectOnce;
+}

package/dist/adapters/sdk/doorbell-client.js

@@ -0,0 +1,261 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DoorbellClient = exports.WakeableSleep = exports.DingParser = void 0;
+exports.doorbellReconnectDelayMs = doorbellReconnectDelayMs;
+/**
+ * DoorbellClient — adapter-side consumer of the daemon's cue doorbell
+ * (T1.1 PR-2, design: docs/design/t11-cue-doorbell.md §2.3/§2.4).
+ *
+ * Subscribes to `GET /doorbell/:ensemble/:playerId` (SSE; loopback +
+ * `X-Ingest-Token`) and fires `onDing` per coalesced ring. The §1 invariant
+ * governs everything here: **doorbell loss must be indistinguishable from
+ * doorbell-never-sent** —
+ *
+ *   - A ding is a HINT, not a guarantee: the daemon's pending bit is
+ *     level-triggered and coalesced, so a ding can arrive for a message the
+ *     poll loop already fetched (one wasted query, §5 row 2) and a ring can
+ *     be lost entirely (fallback poll delivers within the ceiling, §5 row 1).
+ *   - EVERY failure (no token, port file missing, route 404/403/500, daemon
+ *     down, stream drop) degrades to silent disconnected state + reconnect
+ *     with capped backoff. NO error escalation, ever — a player must behave
+ *     identically whether the doorbell never existed or just died (§5).
+ *   - Connection-state transitions emit exactly one `[agent-tempo:doorbell]`
+ *     breadcrumb each (the #249 observability lesson) — that is the only
+ *     above-debug logging in this file.
+ *
+ * Discovery/auth follow the locked inner-loop ingress contract
+ * (`src/pi/inner-loop-client.ts`): port via {@link readPortFile} (`null` ⇒
+ * daemon HTTP not up), loopback base `http://127.0.0.1:{port}`, token from
+ * `AGENT_TEMPO_INGEST_TOKEN` (threaded at spawn; absent ⇒ never subscribes ⇒
+ * pure T0.2 behavior).
+ *
+ * **This file runs in the Node.js adapter process, NOT the Temporal workflow
+ * sandbox.**
+ */
+const config_1 = require("../../config");
+const port_file_1 = require("../../http/port-file");
+const defaultLog = (...args) => console.error('[agent-tempo:doorbell]', ...args);
+/** Reconnect backoff: 1s doubling to a 30s cap (same family as the daemon's bind retry, #768). */
+function doorbellReconnectDelayMs(retry, baseMs = 1_000, capMs = 30_000) {
+    return Math.min(capMs, baseMs * 2 ** Math.min(retry, 31));
+}
+/** Default transport — global `fetch` adapted to {@link DoorbellFetch}, or `null`. */
+function resolveFetch() {
+    const g = globalThis.fetch;
+    if (typeof g !== 'function')
+        return null;
+    return g;
+}
+/**
+ * Cap on the partial-block buffer. Real doorbell blocks are tens of bytes;
+ * the daemon is trusted + loopback, so this is a cheap backstop against a
+ * pathological stream without `\n\n` terminators growing memory unboundedly
+ * — overflow just drops the buffer (a lost ding ≡ never-sent, §1).
+ */
+const MAX_PARSER_BUFFER = 8 * 1024;
+/**
+ * Incremental SSE block parser for the doorbell stream. Feed raw text
+ * chunks; returns the number of `ding` events completed by this chunk.
+ * Keepalive comments (`:ka`) and the `:closed` marker carry no event name
+ * and are ignored. Exported @internal for unit tests.
+ */
+class DingParser {
+    buffer = '';
+    feed(chunk) {
+        this.buffer += chunk;
+        let dings = 0;
+        // SSE events are separated by a blank line. Process every complete
+        // block; keep the trailing partial in the buffer.
+        let sep = this.buffer.indexOf('\n\n');
+        while (sep !== -1) {
+            const block = this.buffer.slice(0, sep);
+            this.buffer = this.buffer.slice(sep + 2);
+            if (/^event:\s*ding\s*$/m.test(block))
+                dings++;
+            sep = this.buffer.indexOf('\n\n');
+        }
+        if (this.buffer.length > MAX_PARSER_BUFFER)
+            this.buffer = '';
+        return dings;
+    }
+}
+exports.DingParser = DingParser;
+/**
+ * Wakeable sleep — the ding→immediate-poll primitive, shared by
+ * `SdkAttachment` (PR-2) and the Pi cue pump (PR-3, which is NOT an
+ * SdkAttachment). Semantics:
+ *
+ *   - `sleep(ms)` parks until the timer fires OR `wake()` pops it early.
+ *   - `wake()` with no parked sleep sets a level-triggered pending bit so
+ *     the NEXT `sleep` returns immediately — a ding that lands while the
+ *     consumer is mid-tick is consumed, not lost (mirrors the daemon
+ *     registry's coalescing; extra wakes coalesce into one).
+ *   - One parked sleep at a time (one poll loop per consumer). A STALE
+ *     timer from an abandoned sleep (e.g. a `Promise.race` loser) is
+ *     identity-guarded so it can never clobber a newer sleep's waker.
+ */
+class WakeableSleep {
+    wakeFn = null;
+    pending = false;
+    sleep(ms) {
+        if (this.pending) {
+            this.pending = false;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            const wake = () => {
+                clearTimeout(timer);
+                if (this.wakeFn === wake)
+                    this.wakeFn = null;
+                resolve();
+            };
+            const timer = setTimeout(() => {
+                if (this.wakeFn === wake)
+                    this.wakeFn = null;
+                resolve();
+            }, ms);
+            timer.unref?.();
+            this.wakeFn = wake;
+        });
+    }
+    wake() {
+        if (this.wakeFn) {
+            this.wakeFn();
+        }
+        else {
+            this.pending = true;
+        }
+    }
+}
+exports.WakeableSleep = WakeableSleep;
+/**
+ * Reconnecting SSE consumer for the daemon doorbell. `start()` launches the
+ * detached connect loop; `stop()` aborts the live stream and ends it. All
+ * callbacks fire on the client's own async path — keep them cheap (the
+ * adapters' `onDing` just wakes a sleeping poll loop).
+ */
+class DoorbellClient {
+    opts;
+    token;
+    readPort;
+    fetchFn;
+    sleep;
+    log;
+    stopped = false;
+    connected = false;
+    abort = null;
+    loop = null;
+    constructor(opts) {
+        this.opts = opts;
+        this.token = opts.ingestToken ?? process.env[config_1.ENV.INGEST_TOKEN];
+        this.readPort = opts.readPort ?? (() => (0, port_file_1.readPortFile)());
+        this.fetchFn = opts.fetchFn ?? resolveFetch();
+        this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms).unref?.()));
+        this.log = opts.log ?? defaultLog;
+    }
+    /** Whether a doorbell stream is currently live (drives the poll ceiling). */
+    get isConnected() {
+        return this.connected;
+    }
+    /**
+     * Launch the connect loop. No token / no fetch ⇒ logs one breadcrumb and
+     * never subscribes (§5: pure T0.2 behavior). Idempotent.
+     */
+    start() {
+        if (this.loop)
+            return;
+        if (!this.token || !this.fetchFn) {
+            this.log(`doorbell disabled for ${this.opts.ensemble}/${this.opts.playerId} ` +
+                `(${!this.token ? 'no ingest token' : 'no fetch transport'}) — polling only`);
+            return;
+        }
+        this.loop = this.runLoop().catch((err) => {
+            // The loop swallows everything itself — this is a last-resort guard so
+            // an unexpected throw can never escalate out of the doorbell (§5).
+            this.log('doorbell loop ended unexpectedly (polling covers):', err?.message ?? err);
+        });
+    }
+    /** End the loop and abort any live stream. Idempotent. */
+    stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        try {
+            this.abort?.abort();
+        }
+        catch { /* already settled */ }
+        this.setConnected(false);
+    }
+    setConnected(connected) {
+        if (this.connected === connected)
+            return;
+        this.connected = connected;
+        this.log(`doorbell ${connected ? 'connected' : 'disconnected'} ` +
+            `(${this.opts.ensemble}/${this.opts.playerId})`);
+        try {
+            this.opts.onConnectionChange?.(connected);
+        }
+        catch (err) {
+            this.log('onConnectionChange threw (ignored):', err?.message ?? err);
+        }
+    }
+    async runLoop() {
+        for (let retry = 0; !this.stopped; retry++) {
+            const streamed = await this.connectOnce();
+            if (this.stopped)
+                return;
+            // A stream that delivered ANY bytes proves the daemon was reachable —
+            // reset the reconnect curve so a healthy-but-bounced daemon comes back
+            // at 1s, not wherever a prior outage left the counter.
+            if (streamed)
+                retry = 0;
+            await this.sleep(doorbellReconnectDelayMs(retry, this.opts.baseDelayMs, this.opts.maxDelayMs));
+        }
+    }
+    /**
+     * One subscribe attempt. Returns `true` when the stream OPENED (HTTP 200)
+     * regardless of how it ended. Every failure path is silent-by-design
+     * below the transition breadcrumb.
+     */
+    async connectOnce() {
+        const port = this.readPort();
+        if (port === null)
+            return false; // daemon HTTP not up — §5 "daemon down" row
+        const url = `http://127.0.0.1:${port}/doorbell/${encodeURIComponent(this.opts.ensemble)}/${encodeURIComponent(this.opts.playerId)}`;
+        this.abort = new AbortController();
+        try {
+            const res = await this.fetchFn(url, {
+                headers: { 'x-ingest-token': this.token },
+                signal: this.abort.signal,
+            });
+            if (res.status !== 200 || !res.body)
+                return false; // 403/404/5xx — §5 "route" rows
+            this.setConnected(true);
+            const parser = new DingParser();
+            const decoder = new TextDecoder();
+            for await (const chunk of res.body) {
+                if (this.stopped)
+                    break;
+                const dings = parser.feed(decoder.decode(chunk, { stream: true }));
+                for (let i = 0; i < dings; i++) {
+                    try {
+                        this.opts.onDing();
+                    }
+                    catch (err) {
+                        this.log('onDing threw (ignored):', err?.message ?? err);
+                    }
+                }
+            }
+            return true;
+        }
+        catch {
+            // Connect refused / aborted / read error — disconnected state covers it.
+            return false;
+        }
+        finally {
+            this.abort = null;
+            this.setConnected(false);
+        }
+    }
+}
+exports.DoorbellClient = DoorbellClient;

package/dist/adapters/sdk/idle-backoff.d.ts

@@ -0,0 +1,71 @@
+/** Fast-poll cadence while a conversation is active (legacy behavior). */
+export declare const SDK_POLL_BASE_MS = 2000;
+/** Growth factor per consecutive empty poll. Matches the interactive
+ * claude-code poller's error-backoff factor (adapter.ts) — one family of
+ * curves across the codebase. */
+export declare const SDK_POLL_BACKOFF_FACTOR = 1.5;
+/** Idle ceiling. 15× the base — the steady-state idle cadence. */
+export declare const SDK_POLL_MAX_MS = 30000;
+/**
+ * T1.1 PR-2 — idle ceiling while the cue doorbell is CONNECTED. Latency is
+ * the doorbell's job; the 60s poll is reconciliation AND the only bound on
+ * worst-case delivery after a lost ding (§2.4 of the design doc — at-most-
+ * once, no replay), so it stays operator-tolerable rather than stretching
+ * to minutes. Disconnected ⇒ the T0.2 30s ceiling above (today's shipped
+ * behavior is the floor).
+ */
+export declare const SDK_POLL_DOORBELL_MAX_MS = 60000;
+export interface IdleBackoffConfig {
+    baseMs: number;
+    factor: number;
+    maxMs: number;
+}
+/**
+ * Resolve the poll-backoff config, honoring the `AGENT_TEMPO_SDK_POLL_BASE_MS`
+ * / `AGENT_TEMPO_SDK_POLL_MAX_MS` env overrides (read at call time, not module
+ * load, so tests and spawners can set them per-process). Setting
+ * `..._MAX_MS` equal to `..._BASE_MS` pins the legacy fixed cadence —
+ * the dev/test escape hatch.
+ */
+export declare function resolveIdleBackoffConfig(): IdleBackoffConfig;
+/**
+ * T1.1 PR-2 — the ceiling to apply while the doorbell is connected
+ * (`AGENT_TEMPO_SDK_POLL_DOORBELL_MAX_MS` override; clamped ≥ the resolved
+ * base so a misconfigured override can never invert base/max).
+ */
+export declare function resolveDoorbellCeilingMs(): number;
+/**
+ * Pure delay computer for an idle-backoff poll loop.
+ *
+ * Usage per tick:
+ *
+ * ```ts
+ * const delay = backoff.next(messages.length > 0);
+ * await sleep(delay);
+ * ```
+ *
+ * - `next(true)`  → conversation is live: reset to `baseMs` and return it.
+ * - `next(false)` → idle tick: grow the delay by `factor` (capped at `maxMs`)
+ *                   and return the grown value. Matches the reference
+ *                   poller's grow-then-sleep shape.
+ * - `reset()`     → external "activity happened" signal (e.g. an SDK turn
+ *                   just finished and follow-ups are likely).
+ */
+export declare class IdleBackoff {
+    private readonly cfg;
+    private currentMs;
+    constructor(cfg?: IdleBackoffConfig);
+    /**
+     * T1.1 PR-2 — swap the idle ceiling (doorbell connected ⇒ 60s,
+     * disconnected ⇒ the 30s T0.2 floor). Base/factor/reset semantics are
+     * untouched; a `currentMs` above a LOWERED ceiling self-heals on the next
+     * `next()` (Math.min clamps it). Clamped ≥ base so the curve can't invert.
+     */
+    setCeiling(maxMs: number): void;
+    /** The delay the next idle sleep would use (read-only; for logs/tests). */
+    get current(): number;
+    /** Compute the next poll delay from this tick's outcome. */
+    next(hadActivity: boolean): number;
+    /** Snap back to the fast cadence. */
+    reset(): void;
+}

package/dist/adapters/sdk/idle-backoff.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdleBackoff = exports.SDK_POLL_DOORBELL_MAX_MS = exports.SDK_POLL_MAX_MS = exports.SDK_POLL_BACKOFF_FACTOR = exports.SDK_POLL_BASE_MS = void 0;
+exports.resolveIdleBackoffConfig = resolveIdleBackoffConfig;
+exports.resolveDoorbellCeilingMs = resolveDoorbellCeilingMs;
+/**
+ * Idle poll backoff (#749, T0.2 of the #747 Tier-0 cost epic).
+ *
+ * Every SDK-class adapter (copilot, claude-api, opencode,
+ * claude-code-headless, mock) drives a `pendingMessages` poll loop against
+ * its session workflow. Pre-#749 all five polled at a fixed 2s cadence —
+ * 43,200 billable queries/day/player even when the player sat idle
+ * overnight. Temporal Cloud bills queries as actions (1 each), so idle
+ * polling was the dominant per-player line item
+ * (docs/design/temporal-cost-rearchitecture.md, driver #3).
+ *
+ * This helper implements true IDLE backoff: each empty poll stretches the
+ * next delay by {@link SDK_POLL_BACKOFF_FACTOR} up to {@link SDK_POLL_MAX_MS};
+ * any delivered message snaps back to {@link SDK_POLL_BASE_MS} so an active
+ * conversation keeps the legacy 2s responsiveness. Steady-state idle lands
+ * at one query per 30s = 2,880/day — a 15× reduction (43,200 ÷ 2,880;
+ * ratio locked by a unit test).
+ *
+ * Trade-off (accepted in #749): the FIRST cue to a long-idle player waits up
+ * to 30s before the adapter notices. Delivery itself is unchanged — the
+ * workflow inbox is durable and the next poll drains the full batch. The
+ * T1.1 doorbell (push delivery) later removes even that latency.
+ *
+ * Pure and timer-free — callers own the `setTimeout`/`sleep`; this class
+ * only computes delays. That keeps it unit-testable without fake timers.
+ *
+ * **This file runs in the Node.js adapter process, NOT the Temporal workflow
+ * sandbox.**
+ */
+const config_1 = require("../../config");
+/** Fast-poll cadence while a conversation is active (legacy behavior). */
+exports.SDK_POLL_BASE_MS = 2_000;
+/** Growth factor per consecutive empty poll. Matches the interactive
+ * claude-code poller's error-backoff factor (adapter.ts) — one family of
+ * curves across the codebase. */
+exports.SDK_POLL_BACKOFF_FACTOR = 1.5;
+/** Idle ceiling. 15× the base — the steady-state idle cadence. */
+exports.SDK_POLL_MAX_MS = 30_000;
+/**
+ * T1.1 PR-2 — idle ceiling while the cue doorbell is CONNECTED. Latency is
+ * the doorbell's job; the 60s poll is reconciliation AND the only bound on
+ * worst-case delivery after a lost ding (§2.4 of the design doc — at-most-
+ * once, no replay), so it stays operator-tolerable rather than stretching
+ * to minutes. Disconnected ⇒ the T0.2 30s ceiling above (today's shipped
+ * behavior is the floor).
+ */
+exports.SDK_POLL_DOORBELL_MAX_MS = 60_000;
+/** Parse a positive-integer env override; fall back on absent/garbage. */
+function envInt(name, fallback) {
+    const raw = process.env[name];
+    if (raw === undefined || raw === '')
+        return fallback;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+/**
+ * Resolve the poll-backoff config, honoring the `AGENT_TEMPO_SDK_POLL_BASE_MS`
+ * / `AGENT_TEMPO_SDK_POLL_MAX_MS` env overrides (read at call time, not module
+ * load, so tests and spawners can set them per-process). Setting
+ * `..._MAX_MS` equal to `..._BASE_MS` pins the legacy fixed cadence —
+ * the dev/test escape hatch.
+ */
+function resolveIdleBackoffConfig() {
+    const baseMs = envInt(config_1.ENV.SDK_POLL_BASE_MS, exports.SDK_POLL_BASE_MS);
+    const maxMs = Math.max(baseMs, envInt(config_1.ENV.SDK_POLL_MAX_MS, exports.SDK_POLL_MAX_MS));
+    return { baseMs, factor: exports.SDK_POLL_BACKOFF_FACTOR, maxMs };
+}
+/**
+ * T1.1 PR-2 — the ceiling to apply while the doorbell is connected
+ * (`AGENT_TEMPO_SDK_POLL_DOORBELL_MAX_MS` override; clamped ≥ the resolved
+ * base so a misconfigured override can never invert base/max).
+ */
+function resolveDoorbellCeilingMs() {
+    const baseMs = envInt(config_1.ENV.SDK_POLL_BASE_MS, exports.SDK_POLL_BASE_MS);
+    return Math.max(baseMs, envInt(config_1.ENV.SDK_POLL_DOORBELL_MAX_MS, exports.SDK_POLL_DOORBELL_MAX_MS));
+}
+/**
+ * Pure delay computer for an idle-backoff poll loop.
+ *
+ * Usage per tick:
+ *
+ * ```ts
+ * const delay = backoff.next(messages.length > 0);
+ * await sleep(delay);
+ * ```
+ *
+ * - `next(true)`  → conversation is live: reset to `baseMs` and return it.
+ * - `next(false)` → idle tick: grow the delay by `factor` (capped at `maxMs`)
+ *                   and return the grown value. Matches the reference
+ *                   poller's grow-then-sleep shape.
+ * - `reset()`     → external "activity happened" signal (e.g. an SDK turn
+ *                   just finished and follow-ups are likely).
+ */
+class IdleBackoff {
+    cfg;
+    currentMs;
+    constructor(cfg = resolveIdleBackoffConfig()) {
+        // Copy — `setCeiling` mutates maxMs and must never write through to a
+        // shared config object a caller handed in.
+        this.cfg = { ...cfg };
+        this.currentMs = cfg.baseMs;
+    }
+    /**
+     * T1.1 PR-2 — swap the idle ceiling (doorbell connected ⇒ 60s,
+     * disconnected ⇒ the 30s T0.2 floor). Base/factor/reset semantics are
+     * untouched; a `currentMs` above a LOWERED ceiling self-heals on the next
+     * `next()` (Math.min clamps it). Clamped ≥ base so the curve can't invert.
+     */
+    setCeiling(maxMs) {
+        this.cfg.maxMs = Math.max(this.cfg.baseMs, maxMs);
+    }
+    /** The delay the next idle sleep would use (read-only; for logs/tests). */
+    get current() {
+        return this.currentMs;
+    }
+    /** Compute the next poll delay from this tick's outcome. */
+    next(hadActivity) {
+        if (hadActivity) {
+            this.currentMs = this.cfg.baseMs;
+        }
+        else {
+            this.currentMs = Math.min(this.currentMs * this.cfg.factor, this.cfg.maxMs);
+        }
+        return this.currentMs;
+    }
+    /** Snap back to the fast cadence. */
+    reset() {
+        this.currentMs = this.cfg.baseMs;
+    }
+}
+exports.IdleBackoff = IdleBackoff;

package/dist/cli/command-center-command.js

@@ -54,6 +54,7 @@ exports.commandCenterCommand = commandCenterCommand;
 const config_1 = require("../config");
 const spawn_1 = require("../spawn");
 const probe_1 = require("../pi/probe");
+const install_1 = require("../pi/install");
 const out = __importStar(require("./output"));
 /**
  * Public entry point — invoked by the CLI dispatcher. Launches the board in a
@@ -62,7 +63,12 @@ const out = __importStar(require("./output"));
  */
 async function commandCenterCommand(args) {
     const config = (0, config_1.getConfig)(args);
-    const ensemble = config.ensemble;
+    // #820 (Bug 3) — honor the positional / `--ensemble` flag. `args.ensemble` is
+    // resolved by the CLI dispatch via the canonical `resolveEnsemble` (flag >
+    // positional > env > 'default'), mirroring `up` post-#685. `config.ensemble`
+    // IGNORES `overrides.ensemble` (config.ts hard-codes it from env/default), so
+    // reading it dropped the positional and the board silently watched 'default'.
+    const ensemble = args.ensemble ?? config.ensemble;
     // Preflight — fail BEFORE launching a terminal that would die. checkPiNodeFloor
     // is a best-effort Node-version proxy; buildPiCommandCenterSpawn's default
     // resolver throws fail-clean when the Pi CLI is missing.
@@ -71,6 +77,24 @@ async function commandCenterCommand(args) {
         out.error(`Cannot start command-center — ${nodeFloor.reason}`);
         process.exit(1);
     }
+    // #820 (Bug 2) — extension-registration guard. command-center relies on the
+    // GLOBAL Pi extension registration (it deliberately passes NO inline `-e`, unlike
+    // `up --agent pi`). On a fresh box that never ran `install-pi`, the extensions are
+    // absent from `~/.pi/agent/settings.json`, so a plain `pi` launches with NO board
+    // and NO error. Auto-install (idempotent — matches `up --agent pi`'s out-of-box
+    // behavior) before spawning; fail loudly with the exact command if the write fails.
+    if (!(0, install_1.arePiExtensionsRegistered)()) {
+        try {
+            const result = (0, install_1.installPiExtensions)();
+            out.log(out.dim(`  Registered the Pi extensions in ${result.settingsPath} (first-run install-pi).`));
+        }
+        catch (err) {
+            out.error('Cannot start command-center — the Pi extensions are not registered and auto-install failed: ' +
+                `${err instanceof Error ? err.message : String(err)}. ` +
+                'Run `agent-tempo install-pi` manually, then retry.');
+            process.exit(1);
+        }
+    }
     // Admin (T3) token — mission-control's operator write/gate surface reads it.
     // #54: a LOCAL (loopback) daemon grants full trust tokenless, so a tokenless
     // board is fully functional locally; only a REMOTE / 0.0.0.0 daemon requires the
@@ -112,5 +136,4 @@ async function commandCenterCommand(args) {
     const { pid } = (0, spawn_1.launchInTerminal)(spawn.cmd, spawn.args, process.cwd(), spawn.env);
     out.success(`Command-center launched for ensemble ${out.cyan(ensemble)} (pid ${pid ?? 'unknown'})`);
     out.log(`  ${out.dim('Observer-only Pi board — the player extension stays dormant in this session.')}`);
-    out.log(`  ${out.dim('Requires `agent-tempo install-pi` to have registered the extensions.')}`);
 }

package/dist/cli/commands.d.ts

@@ -8,8 +8,23 @@ export declare function status(opts: StatusOpts): Promise<void>;
 interface InitOpts {
     dir: string;
     project?: boolean;
+    /**
+     * #818 — suppress the manual-setup "Next steps" block (start Temporal / start
+     * conductor). Set by the automated `up` flow, which has ALREADY started Temporal
+     * and launched the conductor — printing those steps there is stale and misleading.
+     * The manual `agent-tempo init` verb leaves it unset so the guidance still shows.
+     */
+    suppressNextSteps?: boolean;
 }
 export declare function init(opts: InitOpts): Promise<void>;
+/**
+ * Per-project .mcp.json install (legacy, used with --project flag).
+ *
+ * Exported for #818 regression coverage (the `suppressNextSteps` gate) — it only
+ * touches the filesystem + stdout, so it is unit-testable without shelling out to
+ * `claude`. Not part of the public CLI surface.
+ */
+export declare function initProject(dir: string, suppressNextSteps?: boolean): void;
 interface ServerOpts extends CliOverrides {
     background: boolean;
 }
@@ -36,6 +51,19 @@ interface UpOpts extends CliOverrides {
      */
     scenario?: string;
 }
+/**
+ * #832 — the operator-facing "ensemble ready" lines for `up` / `conduct`.
+ *
+ * Keyed on the RESOLVED ensemble name (what `command-center` / `status` take —
+ * `--ensemble` flag > positional > env > `default`), NOT the lineup's `name:`
+ * field. The two diverge whenever any of those overrides the lineup name, so the
+ * old `Ensemble <lineup-name> is ready` line named a thing the operator can't
+ * actually `connect` to. Surfaces the connect command so the next step is one
+ * copy-paste away. Pure + exported for unit testing (the surrounding `up` does
+ * I/O and isn't unit-testable). The shared markdown {@link ensembleReadyBanner}
+ * stays lineup-keyed for the conductor's seeded directive (a different surface).
+ */
+export declare function formatEnsembleReadyLines(ensemble: string, lineupName: string, playerCount: number): [readyLine: string, connectLine: string];
 export declare function up(opts: UpOpts): Promise<void>;
 /**
  * Format a `ScheduleEntry` recurrence for the `status` display.