agent-tempo 1.0.1

package/dist/utils/hosts.d.ts

@@ -0,0 +1,113 @@
+/**
+ * `listHosts` — join layer for #274 host discovery.
+ *
+ * Three RPCs per invocation (AC6b):
+ *   1. `DescribeTaskQueue` on the shared queue with `TASK_QUEUE_TYPE_WORKFLOW`
+ *      — populates `hasWorkflowWorker` per identity.
+ *   2. Same queue, `TASK_QUEUE_TYPE_ACTIVITY` — populates `hasActivityWorker`.
+ *   3. `DescribeTaskQueue` on each per-host queue
+ *      (`agent-tempo-<hostname>`), `TASK_QUEUE_TYPE_ACTIVITY` — populates
+ *      `hasHostQueueWorker`. Runs in parallel across discovered hostnames.
+ *
+ * Plus one `hostProfiles` query against the global maestro when it's
+ * running (AC6g). Absent → liveness-only with
+ * `profileStaleness: 'missing'`.
+ *
+ * Identity is parsed with dual-format tolerance (AC6d / M6):
+ *   - `agent-tempo:<hostname>:<pid>:<version>` (set by v1.0+ workers)
+ *   - `<pid>@<hostname>` (legacy SDK default, pre-#274 daemons)
+ *   - Anything else is skipped silently as opaque third-party.
+ *
+ * Results are cached for `CACHE_TTL_MS` (AC6h) to keep rapid-fire CLI/TUI
+ * invocations cheap; pass `force: true` to bypass.
+ */
+import type { Client } from '@temporalio/client';
+import { temporal } from '@temporalio/proto';
+import type { HostInfo, HostProfile } from '../types';
+/**
+ * Freshness threshold — pollers seen in the last minute are `'live'`,
+ * older ones are tagged `'stale'` and hidden by default. Temporal
+ * server-side LRU keeps pollers for ~5 min; 1-min gives a tighter
+ * "currently polling" signal and aligns with the daemon heartbeat
+ * cadence. AC6c.
+ */
+export declare const HOST_FRESHNESS_THRESHOLD_MS = 60000;
+/** Read-through cache TTL for the join result. AC6h. */
+export declare const CACHE_TTL_MS = 3000;
+/**
+ * #281 — concurrency cap for the per-host RPC fan-out.
+ *
+ * `Promise.all(hostnames.map(describe...))` is unbounded; at >20 hosts that
+ * thunder-herds the Temporal frontend's per-namespace RPS budget. 8 keeps
+ * the common case (≤8 hosts) at full parallelism while preventing the worst
+ * case from spiking the backend.
+ */
+export declare const HOST_FANOUT_CONCURRENCY = 8;
+/**
+ * Test hook — never call from production code.
+ *
+ * Convention: `__<verb><Noun>ForTests`, co-located with the module that owns
+ * the state. See `docs/adr/0006-test-hooks-naming.md`.
+ */
+export declare function __resetHostsCacheForTests(): void;
+export interface ParsedIdentity {
+    hostname: string;
+    pid: number;
+    version: string;
+    /** `true` when the identity was in the legacy `<pid>@<hostname>` SDK-default shape. */
+    legacy: boolean;
+}
+/**
+ * Parse a Temporal poller identity back into the daemon that emitted it.
+ *
+ * Returns `null` for opaque / third-party identities (e.g. Temporal's own
+ * system pollers or an unrelated worker sharing the namespace). Callers
+ * skip those silently.
+ *
+ * The v1.0 format (`agent-tempo:<hostname>:<pid>:<version>`) is
+ * guaranteed to have exactly 4 colon-delimited segments because every
+ * component has its own validation: hostname passes `PLAYER_NAME_REGEX`
+ * (no colons possible), pid is numeric, and version is a semver-ish
+ * string (no colons).
+ *
+ * Pre-v1.0 daemons emitted a `claude-tempo:` prefix. Under the v1.0 hard
+ * break those daemons can't reach v1.x task queues anyway, but if one does
+ * surface in a host listing we tag it `legacy: true` so operators can
+ * distinguish a still-running old daemon from a fresh v1.x worker.
+ */
+export declare function parseIdentity(identity: string): ParsedIdentity | null;
+interface RawPoller {
+    identity: string;
+    lastAccessTimeMs: number;
+    lastAccessTimeIso: string;
+}
+/**
+ * Dep-injection seam used by tests. Production callers OMIT this entirely —
+ * grouping it under `deps` (vs. mixing into the top level of `ListHostsOpts`)
+ * keeps the user-facing surface (`force`, `namespace`, `taskQueue`) cleanly
+ * separated from internal test wiring. See #283.
+ */
+export interface ListHostsDeps {
+    /** `Date.now` replacement for deterministic tests. */
+    now?: () => number;
+    /**
+     * Dep-injected poller fetcher — tests stub to return canned rows.
+     * Production callers omit and the helper uses
+     * `client.workflowService.describeTaskQueue` directly.
+     */
+    describePollers?: (client: Client, namespace: string, taskQueueName: string, taskQueueType: temporal.api.enums.v1.TaskQueueType) => Promise<RawPoller[]>;
+    /** Dep-injected profile fetcher. Tests stub to control profile state. */
+    fetchProfiles?: (client: Client) => Promise<Record<string, HostProfile> | null>;
+}
+export interface ListHostsOpts {
+    /** Bypass the 3s TTL cache. CLI/TUI refresh handlers pass `true`. */
+    force?: boolean;
+    /** Default `'default'`. */
+    namespace?: string;
+    /** Default `'agent-tempo'`. */
+    taskQueue?: string;
+    /** Test-only dep-injection seam. Production callers omit. */
+    deps?: ListHostsDeps;
+}
+export declare function listHosts(client: Client, opts?: ListHostsOpts): Promise<HostInfo[]>;
+export {};

package/dist/utils/hosts.js

@@ -0,0 +1,265 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOST_FANOUT_CONCURRENCY = exports.CACHE_TTL_MS = exports.HOST_FRESHNESS_THRESHOLD_MS = void 0;
+exports.__resetHostsCacheForTests = __resetHostsCacheForTests;
+exports.parseIdentity = parseIdentity;
+exports.listHosts = listHosts;
+const proto_1 = require("@temporalio/proto");
+const p_limit_1 = __importDefault(require("p-limit"));
+const config_1 = require("../config");
+/**
+ * Freshness threshold — pollers seen in the last minute are `'live'`,
+ * older ones are tagged `'stale'` and hidden by default. Temporal
+ * server-side LRU keeps pollers for ~5 min; 1-min gives a tighter
+ * "currently polling" signal and aligns with the daemon heartbeat
+ * cadence. AC6c.
+ */
+exports.HOST_FRESHNESS_THRESHOLD_MS = 60_000;
+/** Read-through cache TTL for the join result. AC6h. */
+exports.CACHE_TTL_MS = 3_000;
+/**
+ * #281 — concurrency cap for the per-host RPC fan-out.
+ *
+ * `Promise.all(hostnames.map(describe...))` is unbounded; at >20 hosts that
+ * thunder-herds the Temporal frontend's per-namespace RPS budget. 8 keeps
+ * the common case (≤8 hosts) at full parallelism while preventing the worst
+ * case from spiking the backend.
+ */
+exports.HOST_FANOUT_CONCURRENCY = 8;
+let cache = null;
+/**
+ * Test hook — never call from production code.
+ *
+ * Convention: `__<verb><Noun>ForTests`, co-located with the module that owns
+ * the state. See `docs/adr/0006-test-hooks-naming.md`.
+ */
+function __resetHostsCacheForTests() {
+    cache = null;
+}
+/**
+ * Parse a Temporal poller identity back into the daemon that emitted it.
+ *
+ * Returns `null` for opaque / third-party identities (e.g. Temporal's own
+ * system pollers or an unrelated worker sharing the namespace). Callers
+ * skip those silently.
+ *
+ * The v1.0 format (`agent-tempo:<hostname>:<pid>:<version>`) is
+ * guaranteed to have exactly 4 colon-delimited segments because every
+ * component has its own validation: hostname passes `PLAYER_NAME_REGEX`
+ * (no colons possible), pid is numeric, and version is a semver-ish
+ * string (no colons).
+ *
+ * Pre-v1.0 daemons emitted a `claude-tempo:` prefix. Under the v1.0 hard
+ * break those daemons can't reach v1.x task queues anyway, but if one does
+ * surface in a host listing we tag it `legacy: true` so operators can
+ * distinguish a still-running old daemon from a fresh v1.x worker.
+ */
+function parseIdentity(identity) {
+    if (identity.startsWith('agent-tempo:') || identity.startsWith('claude-tempo:')) {
+        const legacy = identity.startsWith('claude-tempo:');
+        const parts = identity.split(':');
+        if (parts.length === 4) {
+            const [, hostname, pidStr, version] = parts;
+            const pid = Number(pidStr);
+            if (hostname.length > 0 && Number.isFinite(pid) && pid > 0 && version.length > 0) {
+                return { hostname, pid, version, legacy };
+            }
+        }
+        return null;
+    }
+    // Legacy SDK default format: `<pid>@<hostname>`
+    const legacyMatch = identity.match(/^(\d+)@(.+)$/);
+    if (legacyMatch) {
+        const pid = Number(legacyMatch[1]);
+        const hostname = legacyMatch[2];
+        if (Number.isFinite(pid) && pid > 0 && hostname.length > 0) {
+            return { hostname, pid, version: 'unknown', legacy: true };
+        }
+    }
+    return null;
+}
+// ────────────────────────────────────────────────────────────────────────
+// Low-level RPC + timestamp helpers — exposed for dep-injection in tests
+// ────────────────────────────────────────────────────────────────────────
+/** Convert a protobuf Timestamp to ISO 8601. Returns `''` for unset timestamps. */
+function timestampToIso(ts) {
+    // Protobuf Timestamp is `{seconds: Long | number | string, nanos: number}`.
+    // Protobuf.js may deliver `seconds` as a Long object, a raw number, or a
+    // string depending on the runtime — normalise defensively.
+    if (!ts || typeof ts !== 'object')
+        return '';
+    const t = ts;
+    const secondsRaw = t.seconds;
+    if (secondsRaw === undefined || secondsRaw === null)
+        return '';
+    const seconds = typeof secondsRaw === 'number' ? secondsRaw : Number(String(secondsRaw));
+    if (!Number.isFinite(seconds))
+        return '';
+    const ms = seconds * 1000 + Math.floor((t.nanos ?? 0) / 1_000_000);
+    return new Date(ms).toISOString();
+}
+async function describeQueuePollers(client, namespace, taskQueueName, taskQueueType) {
+    const res = await client.workflowService.describeTaskQueue({
+        namespace,
+        taskQueue: { name: taskQueueName },
+        taskQueueType,
+    });
+    const pollers = res.pollers ?? [];
+    const out = [];
+    for (const p of pollers) {
+        const identity = p.identity ?? '';
+        if (!identity)
+            continue;
+        const iso = timestampToIso(p.lastAccessTime);
+        const ms = iso ? Date.parse(iso) : 0;
+        out.push({ identity, lastAccessTimeMs: ms, lastAccessTimeIso: iso });
+    }
+    return out;
+}
+/**
+ * #280 — single combined query against the global maestro.
+ *
+ * Replaces the prior two-RPC dance (`handle.describe()` for liveness
+ * then `handle.query('hostProfiles')` for data) with one round trip.
+ * Reaching the handler proves the workflow is running, so the caller
+ * gets `{ exists: true, profiles }`. Any transport-level failure
+ * (workflow not found, terminated, namespace unreachable, query
+ * handler not registered on an older maestro) is caught and surfaced
+ * as `null`, which the join site treats as `profileStaleness: 'missing'`.
+ *
+ * Note: we deliberately fall back to `null` on ANY error rather than
+ * trying the legacy `hostProfiles` query as a second attempt — the
+ * combined query has been on every maestro since this commit, so a
+ * mismatched daemon/maestro pair is a deployment bug worth surfacing
+ * as missing-profile (which still lets the listing succeed) rather
+ * than masking with extra RPCs.
+ */
+async function fetchHostProfiles(client) {
+    try {
+        const handle = client.workflow.getHandle(config_1.GLOBAL_MAESTRO_WORKFLOW_ID);
+        const result = (await handle.query('hostProfilesWithExistence'));
+        if (!result || !result.exists)
+            return null;
+        return result.profiles;
+    }
+    catch {
+        return null;
+    }
+}
+async function listHosts(client, opts = {}) {
+    const deps = opts.deps ?? {};
+    const now = deps.now ? deps.now() : Date.now();
+    if (!opts.force && cache && now - cache.timestamp < exports.CACHE_TTL_MS) {
+        return cache.hosts;
+    }
+    const namespace = opts.namespace ?? 'default';
+    const taskQueue = opts.taskQueue ?? 'agent-tempo';
+    const describe = deps.describePollers ?? describeQueuePollers;
+    const fetchProfiles = deps.fetchProfiles ?? fetchHostProfiles;
+    const { TASK_QUEUE_TYPE_WORKFLOW, TASK_QUEUE_TYPE_ACTIVITY } = proto_1.temporal.api.enums.v1.TaskQueueType;
+    // RPCs 1 + 2 — shared queue, both worker types. Parallel.
+    const [sharedWorkflow, sharedActivity] = await Promise.all([
+        describe(client, namespace, taskQueue, TASK_QUEUE_TYPE_WORKFLOW),
+        describe(client, namespace, taskQueue, TASK_QUEUE_TYPE_ACTIVITY),
+    ]);
+    // ── Build InstanceInfo per (hostname, pid) as we consume each stream ──
+    // Each daemon sets the same identity on both the shared-workflow and
+    // shared-activity pollers AND on the per-host-activity worker, so the
+    // (hostname, pid) key merges naturally across streams. Opaque identities
+    // drop out of `parseIdentity` and are skipped silently (AC6d).
+    const hostInstances = new Map();
+    const markInstance = (hostname, pid, flag, ident, poller) => {
+        let byPid = hostInstances.get(hostname);
+        if (!byPid) {
+            byPid = new Map();
+            hostInstances.set(hostname, byPid);
+        }
+        let inst = byPid.get(pid);
+        if (!inst) {
+            inst = {
+                pid,
+                version: ident.version,
+                identity: poller.identity,
+                lastAccessTime: poller.lastAccessTimeIso,
+                hasWorkflowWorker: false,
+                hasActivityWorker: false,
+                hasHostQueueWorker: false,
+                ...(ident.legacy ? { legacy: true } : {}),
+            };
+            byPid.set(pid, inst);
+        }
+        inst[flag] = true;
+    };
+    const consume = (pollers, flag) => {
+        for (const p of pollers) {
+            const ident = parseIdentity(p.identity);
+            if (!ident)
+                continue;
+            markInstance(ident.hostname, ident.pid, flag, ident, p);
+        }
+    };
+    consume(sharedWorkflow, 'hasWorkflowWorker');
+    consume(sharedActivity, 'hasActivityWorker');
+    // Hostnames discovered from the shared queues drive the per-host RPC fan-out.
+    const hostnames = Array.from(hostInstances.keys()).sort();
+    // RPC 3 — per-host activity queue. Parallel with the profile fetch,
+    // but capped at HOST_FANOUT_CONCURRENCY so a deployment with many hosts
+    // doesn't thunder-herd the Temporal frontend (#281).
+    const limit = (0, p_limit_1.default)(exports.HOST_FANOUT_CONCURRENCY);
+    const [perHostActivityRows, profiles] = await Promise.all([
+        Promise.all(hostnames.map((hostname) => limit(async () => {
+            try {
+                const rows = await describe(client, namespace, (0, config_1.hostTaskQueue)(taskQueue, hostname), TASK_QUEUE_TYPE_ACTIVITY);
+                return [hostname, rows];
+            }
+            catch {
+                // Per-host-queue not registered yet → empty. Don't fail the whole call.
+                return [hostname, []];
+            }
+        }))),
+        fetchProfiles(client).catch(() => null),
+    ]);
+    for (const [, rows] of perHostActivityRows) {
+        consume(rows, 'hasHostQueueWorker');
+    }
+    // ── Build HostInfo per hostname ──
+    const hosts = [];
+    for (const hostname of hostnames) {
+        const byPid = hostInstances.get(hostname);
+        if (!byPid || byPid.size === 0)
+            continue;
+        const instances = Array.from(byPid.values()).sort((a, b) => a.pid - b.pid);
+        const isFresh = (iso) => {
+            const ts = iso ? Date.parse(iso) : 0;
+            return ts > 0 && now - ts <= exports.HOST_FRESHNESS_THRESHOLD_MS;
+        };
+        const freshness = instances.some((i) => isFresh(i.lastAccessTime)) ? 'live' : 'stale';
+        const recruitReady = instances.some((i) => i.hasActivityWorker && i.hasHostQueueWorker && isFresh(i.lastAccessTime));
+        const profile = profiles?.[hostname];
+        const profileStaleness = determineStaleness(profile, instances, profiles);
+        hosts.push({ hostname, instances, recruitReady, freshness, profile, profileStaleness });
+    }
+    cache = { timestamp: now, hosts };
+    return hosts;
+}
+/**
+ * M13 — identity-vs-profile reconciliation.
+ *
+ *   - `'missing'` — maestro is absent OR this host has no profile entry
+ *   - `'fresh'`   — profile present AND some live instance's version
+ *                   matches `profile.version`
+ *   - `'stale'`   — profile present but no live instance matches its
+ *                   version (rolling upgrade, GC pending, etc.)
+ */
+function determineStaleness(profile, instances, profiles) {
+    if (!profiles)
+        return 'missing'; // maestro unreachable or absent
+    if (!profile)
+        return 'missing';
+    if (!profile.version)
+        return 'fresh'; // legacy profile with no version — trust as-is
+    return instances.some((i) => i.version === profile.version) ? 'fresh' : 'stale';
+}

package/dist/utils/parent-death-watchdog.d.ts

@@ -0,0 +1 @@
+export declare function installParentDeathWatchdog(): void;

package/dist/utils/parent-death-watchdog.js

@@ -0,0 +1,47 @@
+"use strict";
+// Self-exit when the parent process goes away.
+//
+// Stdio-MCP children (and the Copilot bridge subprocess) are spawned by
+// hosts that often die without sending SIGTERM — Claude Code on Windows
+// just closes the pipe, and an abruptly-killed daemon leaves bridge
+// subprocesses orphaned. Without this watchdog, those children stay
+// alive forever holding the Temporal core-bridge `.node` open, which
+// (a) leaks processes across host restarts and (b) blocks
+// `npm install -g` upgrades with EBUSY on Windows.
+//
+// Two complementary signals:
+//   1. stdin 'end'/'close' — fires the instant the parent closes the
+//      stdio pipe. Primary signal; immediate.
+//   2. Parent-PID poll — fallback for when the pipe handle is inherited
+//      by another process (or stdio was 'ignore'). 30s cadence is a
+//      belt-and-braces interval — orphan dies within half a minute,
+//      no measurable syscall cost. `process.kill(pid, 0)` is a
+//      permission check, not a signal.
+//
+// PID reuse caveat: Windows recycles PIDs quickly. If the parent dies
+// and an unrelated process inherits the same PID before our next poll,
+// we falsely conclude the parent is alive. The stdin EOF path catches
+// that case immediately, so this is purely a fallback.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installParentDeathWatchdog = installParentDeathWatchdog;
+const log = (...args) => console.error('[agent-tempo:watchdog]', ...args);
+function installParentDeathWatchdog() {
+    const exit = (reason) => {
+        log('parent gone (', reason, ') — exiting');
+        process.exit(0);
+    };
+    process.stdin.on('end', () => exit('stdin end'));
+    process.stdin.on('close', () => exit('stdin close'));
+    const parentPid = process.ppid;
+    if (parentPid && parentPid > 1) {
+        const timer = setInterval(() => {
+            try {
+                process.kill(parentPid, 0);
+            }
+            catch {
+                exit(`ppid ${parentPid} dead`);
+            }
+        }, 30_000);
+        timer.unref();
+    }
+}

package/dist/utils/query-timeout.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Bounded `WorkflowHandle.query()` wrapper — Issue #433.
+ *
+ * **Problem.** `@temporalio/client@1.15` doesn't expose an `AbortSignal` or a
+ * per-call `deadline` on `WorkflowHandle.query()`. When the workflow is alive
+ * (`Running`) but the worker that polls its task queue is dead (orphaned
+ * adapter, wedged Copilot bridge, sticky-cache lock-up), `query()` never
+ * resolves — it sits on its gRPC stream until the connection is torn down.
+ *
+ * Until v0.26 this only manifested as background reconcile log noise. After
+ * #399 W2 layered `getPlayerWireMeta` (3 session queries × N players) into
+ * the snapshot fan-out, a single hung session also wedged the snapshot
+ * endpoint and the AggregateRunner's 750ms poll loop — the trigger for this
+ * fix.
+ *
+ * **Strategy.** Race `handle.query()` against a `setTimeout`. When the timeout
+ * wins, throw `QueryTimeoutError` so the caller's existing soft-failure path
+ * (`Promise.allSettled` / `try-catch` / `.catch(() => …)`) takes over. The
+ * underlying RPC stays pending in memory until it eventually resolves or the
+ * gRPC connection is closed — see "Leak characteristics" below for why
+ * that's bounded.
+ *
+ * **Leak characteristics.** The pending `handle.query()` Promise can't be
+ * cancelled in this SDK version. Instead we **dedupe in-flight queries** by
+ * `(workflowId, queryName)` so the AggregateRunner firing every 750ms against
+ * the same hung session doesn't accumulate one new dangling promise per tick
+ * — it gets the *same* shared promise back. Total memory cost is bounded by
+ * `unique-hung-workflows × distinct-queries-per-workflow` (typically <50
+ * entries even in degenerate fleets), and every entry is reclaimed when the
+ * RPC settles (workflow closes, namespace evicted, daemon restart). When
+ * `@temporalio/client` adds AbortSignal support, swap the race for a real
+ * cancellation and drop the dedup map.
+ *
+ * **Configurable.** Default timeout is `DEFAULT_QUERY_TIMEOUT_MS` (2000ms) —
+ * Temporal queries against a live worker round-trip in <100ms, so a 2s ceiling
+ * is two orders of magnitude larger than a healthy query. Pass a smaller value
+ * for tests; pass a larger value if you have a slow query handler that does
+ * meaningful work synchronously.
+ */
+import type { WorkflowHandle } from '@temporalio/client';
+import type { QueryDefinition } from '@temporalio/common';
+/**
+ * Default per-query timeout. 2 seconds — Temporal queries against a healthy
+ * worker round-trip in <100ms, so this is two orders of magnitude of
+ * headroom while still being short enough that a hung snapshot fan-out
+ * (~12 players × 3 queries) still completes well under 10s.
+ */
+export declare const DEFAULT_QUERY_TIMEOUT_MS = 2000;
+/**
+ * Thrown by {@link queryHandleWithTimeout} when the per-query timeout fires
+ * before the underlying RPC settles. Subclasses `Error`; `name` is set so
+ * `err.name === 'QueryTimeoutError'` and `err instanceof QueryTimeoutError`
+ * both work for callers that switch on either.
+ */
+export declare class QueryTimeoutError extends Error {
+    readonly workflowId: string;
+    readonly queryName: string;
+    readonly timeoutMs: number;
+    constructor(workflowId: string, queryName: string, timeoutMs: number);
+}
+/**
+ * Test-only — clear the in-flight dedup table so each test case starts with
+ * an empty cache. Follows the `__<verb><Noun>ForTests` convention from
+ * ADR 0006: never call from production code.
+ */
+export declare function __resetInflightQueriesForTests(): void;
+/**
+ * Run `handle.query(queryDef, …(opts.args))` with a
+ * {@link DEFAULT_QUERY_TIMEOUT_MS} (or `opts.timeoutMs`) ceiling. Throws
+ * {@link QueryTimeoutError} if the timeout fires first. Multiple callers
+ * issuing the same `(workflowId, queryName)` while the prior call is
+ * still in flight share one underlying RPC — see the file header for
+ * leak characteristics.
+ *
+ * `queryDef` may be a typed `QueryDefinition` (preferred — caller gets
+ * type inference on `Ret`) or a bare string name (legacy call sites that
+ * predate the signal-defs file: `getMetadata`, `getPart`, `maestroPlayers`,
+ * etc.).
+ *
+ * `opts.args` forwards extra positional args to the SDK `query()` call.
+ * Used by `getEnsembleChat`'s `{ offset, limit }` payload — every other
+ * call site in this codebase issues a zero-arg query.
+ *
+ * **Dedup caveat with args**: the dedup key is `(workflowId, queryName)`
+ * only — args are NOT in the key. If two concurrent callers issue the
+ * same query name with *different* args, the second caller will receive
+ * the first caller's result. Acceptable today because `getEnsembleChat`
+ * is called with `(0, SNAPSHOT_CHAT_LIMIT)` from the snapshot fan-out
+ * and a wider `(0, POLL_CHAT_LIMIT)` from the aggregate poll — both
+ * are zero-offset reads, the wider window is a superset of the
+ * narrower, and the bus's §8 chat cap collapses excess. Revisit if a
+ * future args-passing caller issues a non-superset shape.
+ *
+ * **No retry**: caller decides whether to retry or fall back. Most call
+ * sites fall back (snapshot returns `null` wireMeta;
+ * `queryOrphanedSessions` skips the candidate; `getEnsembleMeta`
+ * substitutes sentinels) so a retry loop here would just delay the
+ * inevitable fallback.
+ */
+export declare function queryHandleWithTimeout<Ret, Args extends unknown[] = []>(handle: WorkflowHandle, queryDef: QueryDefinition<Ret, Args> | string, opts?: {
+    timeoutMs?: number;
+    args?: Args;
+}): Promise<Ret>;

package/dist/utils/query-timeout.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryTimeoutError = exports.DEFAULT_QUERY_TIMEOUT_MS = void 0;
+exports.__resetInflightQueriesForTests = __resetInflightQueriesForTests;
+exports.queryHandleWithTimeout = queryHandleWithTimeout;
+/**
+ * Default per-query timeout. 2 seconds — Temporal queries against a healthy
+ * worker round-trip in <100ms, so this is two orders of magnitude of
+ * headroom while still being short enough that a hung snapshot fan-out
+ * (~12 players × 3 queries) still completes well under 10s.
+ */
+exports.DEFAULT_QUERY_TIMEOUT_MS = 2000;
+/**
+ * Thrown by {@link queryHandleWithTimeout} when the per-query timeout fires
+ * before the underlying RPC settles. Subclasses `Error`; `name` is set so
+ * `err.name === 'QueryTimeoutError'` and `err instanceof QueryTimeoutError`
+ * both work for callers that switch on either.
+ */
+class QueryTimeoutError extends Error {
+    workflowId;
+    queryName;
+    timeoutMs;
+    constructor(workflowId, queryName, timeoutMs) {
+        super(`Temporal query timed out after ${timeoutMs}ms: ` +
+            `workflow="${workflowId}" query="${queryName}" ` +
+            `(worker may be down or wedged — see #433)`);
+        this.workflowId = workflowId;
+        this.queryName = queryName;
+        this.timeoutMs = timeoutMs;
+        this.name = 'QueryTimeoutError';
+    }
+}
+exports.QueryTimeoutError = QueryTimeoutError;
+/** Module-level dedup table keyed by `(workflowId, queryName)`. See JSDoc. */
+const inflightQueries = new Map();
+function inflightKey(workflowId, queryName) {
+    // NUL separator — workflow ids follow the project's `claude-{kind}-…`
+    // convention and query names are JS identifiers, so neither can contain
+    // a literal NUL byte. Guarantees no collision between e.g.
+    // workflow `a` + query `b\0foo` vs. workflow `a\0b` + query `foo`.
+    return `${workflowId}\x00${queryName}`;
+}
+/**
+ * Test-only — clear the in-flight dedup table so each test case starts with
+ * an empty cache. Follows the `__<verb><Noun>ForTests` convention from
+ * ADR 0006: never call from production code.
+ */
+function __resetInflightQueriesForTests() {
+    inflightQueries.clear();
+}
+/**
+ * Run `handle.query(queryDef, …(opts.args))` with a
+ * {@link DEFAULT_QUERY_TIMEOUT_MS} (or `opts.timeoutMs`) ceiling. Throws
+ * {@link QueryTimeoutError} if the timeout fires first. Multiple callers
+ * issuing the same `(workflowId, queryName)` while the prior call is
+ * still in flight share one underlying RPC — see the file header for
+ * leak characteristics.
+ *
+ * `queryDef` may be a typed `QueryDefinition` (preferred — caller gets
+ * type inference on `Ret`) or a bare string name (legacy call sites that
+ * predate the signal-defs file: `getMetadata`, `getPart`, `maestroPlayers`,
+ * etc.).
+ *
+ * `opts.args` forwards extra positional args to the SDK `query()` call.
+ * Used by `getEnsembleChat`'s `{ offset, limit }` payload — every other
+ * call site in this codebase issues a zero-arg query.
+ *
+ * **Dedup caveat with args**: the dedup key is `(workflowId, queryName)`
+ * only — args are NOT in the key. If two concurrent callers issue the
+ * same query name with *different* args, the second caller will receive
+ * the first caller's result. Acceptable today because `getEnsembleChat`
+ * is called with `(0, SNAPSHOT_CHAT_LIMIT)` from the snapshot fan-out
+ * and a wider `(0, POLL_CHAT_LIMIT)` from the aggregate poll — both
+ * are zero-offset reads, the wider window is a superset of the
+ * narrower, and the bus's §8 chat cap collapses excess. Revisit if a
+ * future args-passing caller issues a non-superset shape.
+ *
+ * **No retry**: caller decides whether to retry or fall back. Most call
+ * sites fall back (snapshot returns `null` wireMeta;
+ * `queryOrphanedSessions` skips the candidate; `getEnsembleMeta`
+ * substitutes sentinels) so a retry loop here would just delay the
+ * inevitable fallback.
+ */
+async function queryHandleWithTimeout(handle, queryDef, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? exports.DEFAULT_QUERY_TIMEOUT_MS;
+    const queryName = typeof queryDef === 'string' ? queryDef : queryDef.name;
+    const key = inflightKey(handle.workflowId, queryName);
+    let underlying = inflightQueries.get(key);
+    if (!underlying) {
+        const args = (opts.args ?? []);
+        underlying = handle.query(queryDef, ...args).finally(() => {
+            // Free the slot once the RPC settles — success or failure both clear.
+            // Multiple racing callers all see the same settled value.
+            inflightQueries.delete(key);
+        });
+        inflightQueries.set(key, underlying);
+    }
+    let timer;
+    const timeoutPromise = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            reject(new QueryTimeoutError(handle.workflowId, queryName, timeoutMs));
+        }, timeoutMs);
+        // Don't let the timeout keep the process alive.
+        timer.unref?.();
+    });
+    try {
+        return await Promise.race([underlying, timeoutPromise]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}