agent-tempo 1.0.1

package/dist/utils/validation.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Shared input validation constants for player names, ensemble names, messages, etc.
+ * Used by MCP tool Zod schemas and config validation.
+ */
+/** Player names: alphanumeric, hyphens, underscores. */
+export declare const PLAYER_NAME_REGEX: RegExp;
+export declare const PLAYER_NAME_MAX = 64;
+/**
+ * Ensemble names: must start and end with alphanumeric, may contain dots, hyphens, underscores.
+ * Minimum 1 char (single alphanumeric), maximum 64 chars.
+ */
+export declare const ENSEMBLE_NAME_REGEX: RegExp;
+/** Stage name max length. */
+export declare const STAGE_NAME_MAX = 64;
+/** Maximum players per stage. */
+export declare const STAGE_PLAYERS_MAX = 20;
+/** Maximum message size for cue/report (100KB). */
+export declare const MESSAGE_MAX = 102400;
+/** Maximum part (status) length. */
+export declare const PART_MAX = 500;
+/** Default slot key when callers omit `key`. */
+export declare const PLAYER_STATE_DEFAULT_KEY = "main";
+/** Slot keys: alphanumeric + underscore + hyphen. Mirrors PLAYER_NAME_REGEX shape. */
+export declare const PLAYER_STATE_KEY_REGEX: RegExp;
+/** Maximum slot key length. */
+export declare const PLAYER_STATE_KEY_MAX = 32;
+/** Maximum content size per slot — 32 KiB. Mirrors coat-check's per-entry cap. */
+export declare const PLAYER_STATE_CONTENT_MAX: number;
+/** Maximum number of populated slots per player. Saturation rejects with `PlayerStateSlotsFull`. */
+export declare const PLAYER_STATE_SLOTS_MAX = 4;
+/** Coat-check ticket id pattern. Alphanumeric + underscore + hyphen, generated server-side via `uuid4()`. */
+export declare const COAT_CHECK_TICKET_REGEX: RegExp;
+/** Maximum coat-check ticket id length. Generous to accommodate uuid4 + future versioning prefixes. */
+export declare const COAT_CHECK_TICKET_MAX = 64;
+/** Maximum content size per coat-check entry — 32 KiB. Mirrors `PLAYER_STATE_CONTENT_MAX`. */
+export declare const COAT_CHECK_CONTENT_MAX: number;
+/** Maximum summary length per coat-check entry — short, listing-friendly preamble. */
+export declare const COAT_CHECK_SUMMARY_MAX = 500;
+/** Maximum free-form contentType string (e.g. `'text/markdown'`). */
+export declare const COAT_CHECK_CONTENT_TYPE_MAX = 64;
+/** Maximum populated coat-check slots per ensemble. Saturation rejects with `CoatCheckSlotsFull`. */
+export declare const COAT_CHECK_SLOTS_MAX = 20;
+/** Minimum allowed `ttlMs` argument on `coat_check_put` — 1 hour. */
+export declare const COAT_CHECK_TTL_MIN_MS: number;
+/** Maximum allowed `ttlMs` argument on `coat_check_put` — 30 days. */
+export declare const COAT_CHECK_TTL_MAX_MS: number;
+/** Default `ttlMs` when caller omits the argument — 7 days. */
+export declare const COAT_CHECK_TTL_DEFAULT_MS: number;
+/**
+ * Maximum length of the ensemble description set via
+ * `set_ensemble_description` (#399 W1, Q5.1). Soft cap — the MCP tool
+ * boundary rejects oversized inputs; the maestro workflow clamps as a
+ * defence-in-depth measure.
+ */
+export declare const ENSEMBLE_DESCRIPTION_MAX = 100;
+/** Maximum file path length. */
+export declare const PATH_MAX = 1024;
+/** Maximum schedule name length. */
+export declare const SCHEDULE_NAME_MAX = 64;
+/** Maximum schedule message size (10KB). */
+export declare const SCHEDULE_MESSAGE_MAX = 10240;
+/** Maximum cron expression length. */
+export declare const CRON_EXPRESSION_MAX = 128;
+/** Maximum quality gate task name length. */
+export declare const GATE_TASK_MAX = 64;
+/** Maximum number of criteria per quality gate. */
+export declare const GATE_CRITERIA_MAX = 20;
+/** Maximum length for individual criterion text. */
+export declare const GATE_CRITERION_TEXT_MAX = 512;
+/** Maximum length for gate criterion notes. */
+export declare const GATE_NOTES_MAX = 1024;
+/** Timeout for npm install in worktrees (60s). */
+export declare const WORKTREE_INSTALL_TIMEOUT = 60000;
+/** Maximum length for message preview truncation. */
+export declare const PREVIEW_MAX_LENGTH = 200;
+/** Maximum `contextMessages` arg for restart / migrate tools (QA B4). */
+export declare const RESTART_CONTEXT_MESSAGES_MAX = 50;
+/** Maximum `deadlineMs` arg for detach tool. */
+export declare const MAX_DETACH_DEADLINE_MS = 120000;
+/**
+ * Default graceful-detach deadline used by `deliverRestart`'s Step 2
+ * (`requestDetach` before a forced attachment handover). Internal, not
+ * user-controllable — well below `MAX_DETACH_DEADLINE_MS`. Extracted from
+ * a raw `5_000` literal in PR #136 F5 follow-up (#139).
+ */
+export declare const DEFAULT_RESTART_DETACH_DEADLINE_MS = 5000;
+/**
+ * Default attachment lease (ms) used by `deliverRestart`'s Step 4
+ * (`claimAttachment`). Ninety seconds gives the freshly-spawned adapter
+ * enough runway to boot, renew, and begin heartbeating. Extracted from a
+ * raw `90_000` literal in PR #136 F5 follow-up (#139).
+ */
+export declare const DEFAULT_RESTART_LEASE_MS = 90000;
+/**
+ * Whether a session should be included in a broadcast based on its attachment phase.
+ *
+ * Option-B mapping (see #176 PR description):
+ *   - `attached` / `processing` / `awaiting` → include (talkable)
+ *   - `booting`                              → exclude (not ready — legacy "pending")
+ *   - `draining` / `detached`                → include only if includeDisconnected
+ *   - `gone`                                 → exclude (terminal — legacy "terminated")
+ *
+ * Undefined phase (older workflows pre-attachment-lifecycle, or transient
+ * search-attribute propagation) is treated as `booting` — safe default.
+ *
+ * The `includeDisconnected` parameter is surfaced to callers via the `includeStale`
+ * MCP tool argument (kept for wire compat; description updated).
+ */
+export declare function shouldIncludeInBroadcast(phase: string | undefined, includeDisconnected: boolean): boolean;
+/** Validate a player name string. Returns an error message or null if valid. */
+export declare function validatePlayerName(name: string): string | null;
+/** Validate an ensemble name string. Returns an error message or null if valid. */
+export declare function validateEnsembleName(name: string): string | null;

package/dist/utils/validation.js

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * Shared input validation constants for player names, ensemble names, messages, etc.
+ * Used by MCP tool Zod schemas and config validation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RESTART_LEASE_MS = exports.DEFAULT_RESTART_DETACH_DEADLINE_MS = exports.MAX_DETACH_DEADLINE_MS = exports.RESTART_CONTEXT_MESSAGES_MAX = exports.PREVIEW_MAX_LENGTH = exports.WORKTREE_INSTALL_TIMEOUT = exports.GATE_NOTES_MAX = exports.GATE_CRITERION_TEXT_MAX = exports.GATE_CRITERIA_MAX = exports.GATE_TASK_MAX = exports.CRON_EXPRESSION_MAX = exports.SCHEDULE_MESSAGE_MAX = exports.SCHEDULE_NAME_MAX = exports.PATH_MAX = exports.ENSEMBLE_DESCRIPTION_MAX = exports.COAT_CHECK_TTL_DEFAULT_MS = exports.COAT_CHECK_TTL_MAX_MS = exports.COAT_CHECK_TTL_MIN_MS = exports.COAT_CHECK_SLOTS_MAX = exports.COAT_CHECK_CONTENT_TYPE_MAX = exports.COAT_CHECK_SUMMARY_MAX = exports.COAT_CHECK_CONTENT_MAX = exports.COAT_CHECK_TICKET_MAX = exports.COAT_CHECK_TICKET_REGEX = exports.PLAYER_STATE_SLOTS_MAX = exports.PLAYER_STATE_CONTENT_MAX = exports.PLAYER_STATE_KEY_MAX = exports.PLAYER_STATE_KEY_REGEX = exports.PLAYER_STATE_DEFAULT_KEY = exports.PART_MAX = exports.MESSAGE_MAX = exports.STAGE_PLAYERS_MAX = exports.STAGE_NAME_MAX = exports.ENSEMBLE_NAME_REGEX = exports.PLAYER_NAME_MAX = exports.PLAYER_NAME_REGEX = void 0;
+exports.shouldIncludeInBroadcast = shouldIncludeInBroadcast;
+exports.validatePlayerName = validatePlayerName;
+exports.validateEnsembleName = validateEnsembleName;
+/** Player names: alphanumeric, hyphens, underscores. */
+exports.PLAYER_NAME_REGEX = /^[a-zA-Z0-9_-]+$/;
+exports.PLAYER_NAME_MAX = 64;
+/**
+ * Ensemble names: must start and end with alphanumeric, may contain dots, hyphens, underscores.
+ * Minimum 1 char (single alphanumeric), maximum 64 chars.
+ */
+exports.ENSEMBLE_NAME_REGEX = /^[a-zA-Z0-9]([a-zA-Z0-9._-]{0,62}[a-zA-Z0-9])?$/;
+/** Stage name max length. */
+exports.STAGE_NAME_MAX = 64;
+/** Maximum players per stage. */
+exports.STAGE_PLAYERS_MAX = 20;
+/** Maximum message size for cue/report (100KB). */
+exports.MESSAGE_MAX = 102400;
+/** Maximum part (status) length. */
+exports.PART_MAX = 500;
+// ── Player saveable state (#334 PR-1) ──────────────────────────────────────
+//
+// Per-session, player-curated state slots. Sized per design §3.3:
+//   per-key 32 KiB × max 4 slots → 128 KiB structural max per session.
+// At a 1.2 MiB p99 session footprint, that lands at ~33 % of Temporal's
+// 4 MiB CAN-payload ceiling — comfortable. Saturation refuses with a
+// `PlayerStateSlotsFull` ApplicationFailure rather than evicting LRU
+// (Anthropic harness-design blog: explicit eviction reinforces authorial
+// discipline). See docs/adr/0011-player-saveable-state.md.
+/** Default slot key when callers omit `key`. */
+exports.PLAYER_STATE_DEFAULT_KEY = 'main';
+/** Slot keys: alphanumeric + underscore + hyphen. Mirrors PLAYER_NAME_REGEX shape. */
+exports.PLAYER_STATE_KEY_REGEX = /^[a-zA-Z0-9_-]+$/;
+/** Maximum slot key length. */
+exports.PLAYER_STATE_KEY_MAX = 32;
+/** Maximum content size per slot — 32 KiB. Mirrors coat-check's per-entry cap. */
+exports.PLAYER_STATE_CONTENT_MAX = 32 * 1024;
+/** Maximum number of populated slots per player. Saturation rejects with `PlayerStateSlotsFull`. */
+exports.PLAYER_STATE_SLOTS_MAX = 4;
+// ── Coat-check (#318, ADR 0008) ────────────────────────────────────────────
+//
+// Ensemble-shared, ticket-keyed stash for content too large to inline in a
+// `cue` message body. Lives on per-ensemble Maestro workflow state.
+//
+// Sizing per the #318 architect verdict (which adjusts ADR 0008's 50-slot
+// proposal):
+//   per-entry 32 KiB × max 20 slots → 640 KiB structural max per ensemble.
+//   That lands at ~16 % of Temporal's 4 MiB CAN-payload ceiling — comfortable
+//   headroom on top of existing maestro state (~316 KiB). Saturation refuses
+//   with a `CoatCheckSlotsFull` ApplicationFailure rather than evicting LRU
+//   — cross-host scope makes silent peer eviction a sharper footgun than
+//   the rejection's diagnostic UX.
+/** Coat-check ticket id pattern. Alphanumeric + underscore + hyphen, generated server-side via `uuid4()`. */
+exports.COAT_CHECK_TICKET_REGEX = /^[a-zA-Z0-9_-]+$/;
+/** Maximum coat-check ticket id length. Generous to accommodate uuid4 + future versioning prefixes. */
+exports.COAT_CHECK_TICKET_MAX = 64;
+/** Maximum content size per coat-check entry — 32 KiB. Mirrors `PLAYER_STATE_CONTENT_MAX`. */
+exports.COAT_CHECK_CONTENT_MAX = 32 * 1024;
+/** Maximum summary length per coat-check entry — short, listing-friendly preamble. */
+exports.COAT_CHECK_SUMMARY_MAX = 500;
+/** Maximum free-form contentType string (e.g. `'text/markdown'`). */
+exports.COAT_CHECK_CONTENT_TYPE_MAX = 64;
+/** Maximum populated coat-check slots per ensemble. Saturation rejects with `CoatCheckSlotsFull`. */
+exports.COAT_CHECK_SLOTS_MAX = 20;
+/** Minimum allowed `ttlMs` argument on `coat_check_put` — 1 hour. */
+exports.COAT_CHECK_TTL_MIN_MS = 60 * 60 * 1000;
+/** Maximum allowed `ttlMs` argument on `coat_check_put` — 30 days. */
+exports.COAT_CHECK_TTL_MAX_MS = 30 * 24 * 60 * 60 * 1000;
+/** Default `ttlMs` when caller omits the argument — 7 days. */
+exports.COAT_CHECK_TTL_DEFAULT_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Maximum length of the ensemble description set via
+ * `set_ensemble_description` (#399 W1, Q5.1). Soft cap — the MCP tool
+ * boundary rejects oversized inputs; the maestro workflow clamps as a
+ * defence-in-depth measure.
+ */
+exports.ENSEMBLE_DESCRIPTION_MAX = 100;
+/** Maximum file path length. */
+exports.PATH_MAX = 1024;
+/** Maximum schedule name length. */
+exports.SCHEDULE_NAME_MAX = 64;
+/** Maximum schedule message size (10KB). */
+exports.SCHEDULE_MESSAGE_MAX = 10240;
+/** Maximum cron expression length. */
+exports.CRON_EXPRESSION_MAX = 128;
+/** Maximum quality gate task name length. */
+exports.GATE_TASK_MAX = 64;
+/** Maximum number of criteria per quality gate. */
+exports.GATE_CRITERIA_MAX = 20;
+/** Maximum length for individual criterion text. */
+exports.GATE_CRITERION_TEXT_MAX = 512;
+/** Maximum length for gate criterion notes. */
+exports.GATE_NOTES_MAX = 1024;
+/** Timeout for npm install in worktrees (60s). */
+exports.WORKTREE_INSTALL_TIMEOUT = 60000;
+// `BLOCKED_WINDOW_MS` constant removed in v0.26 (#175 / #178) — the blocked
+// session heuristic it gated was replaced by the attachment-phase lifecycle.
+/** Maximum length for message preview truncation. */
+exports.PREVIEW_MAX_LENGTH = 200;
+/** Maximum `contextMessages` arg for restart / migrate tools (QA B4). */
+exports.RESTART_CONTEXT_MESSAGES_MAX = 50;
+/** Maximum `deadlineMs` arg for detach tool. */
+exports.MAX_DETACH_DEADLINE_MS = 120_000;
+/**
+ * Default graceful-detach deadline used by `deliverRestart`'s Step 2
+ * (`requestDetach` before a forced attachment handover). Internal, not
+ * user-controllable — well below `MAX_DETACH_DEADLINE_MS`. Extracted from
+ * a raw `5_000` literal in PR #136 F5 follow-up (#139).
+ */
+exports.DEFAULT_RESTART_DETACH_DEADLINE_MS = 5_000;
+/**
+ * Default attachment lease (ms) used by `deliverRestart`'s Step 4
+ * (`claimAttachment`). Ninety seconds gives the freshly-spawned adapter
+ * enough runway to boot, renew, and begin heartbeating. Extracted from a
+ * raw `90_000` literal in PR #136 F5 follow-up (#139).
+ */
+exports.DEFAULT_RESTART_LEASE_MS = 90_000;
+/**
+ * Whether a session should be included in a broadcast based on its attachment phase.
+ *
+ * Option-B mapping (see #176 PR description):
+ *   - `attached` / `processing` / `awaiting` → include (talkable)
+ *   - `booting`                              → exclude (not ready — legacy "pending")
+ *   - `draining` / `detached`                → include only if includeDisconnected
+ *   - `gone`                                 → exclude (terminal — legacy "terminated")
+ *
+ * Undefined phase (older workflows pre-attachment-lifecycle, or transient
+ * search-attribute propagation) is treated as `booting` — safe default.
+ *
+ * The `includeDisconnected` parameter is surfaced to callers via the `includeStale`
+ * MCP tool argument (kept for wire compat; description updated).
+ */
+function shouldIncludeInBroadcast(phase, includeDisconnected) {
+    const p = phase || 'booting';
+    if (p === 'gone' || p === 'booting')
+        return false;
+    if ((p === 'draining' || p === 'detached') && !includeDisconnected)
+        return false;
+    return true;
+}
+/** Validate a player name string. Returns an error message or null if valid. */
+function validatePlayerName(name) {
+    if (name.length > exports.PLAYER_NAME_MAX) {
+        return `Name too long (${name.length} chars, max ${exports.PLAYER_NAME_MAX}).`;
+    }
+    if (!exports.PLAYER_NAME_REGEX.test(name)) {
+        return `Invalid name "${name}". Names must contain only letters, numbers, hyphens, and underscores.`;
+    }
+    return null;
+}
+/** Validate an ensemble name string. Returns an error message or null if valid. */
+function validateEnsembleName(name) {
+    if (!exports.ENSEMBLE_NAME_REGEX.test(name)) {
+        return `Invalid ensemble name "${name}". Must start/end with alphanumeric, may contain letters, numbers, dots, hyphens, underscores (max 64 chars).`;
+    }
+    return null;
+}

package/dist/utils/visibility-deadline.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Iterator-level deadlines for unbounded Temporal visibility queries
+ * (`client.workflow.list({ query })`). Closes #336 + #529.
+ *
+ * ## Background
+ *
+ * Six daemon hot-path sites consume `for await (const wf of
+ * client.workflow.list({ query }))` without any iterator-level deadline.
+ * Temporal's visibility API is page-based: each `next()` may fetch
+ * additional pages over gRPC. A wedged worker, a slow page on a deep
+ * scan, or a backend hiccup can stall the iterator indefinitely while
+ * the gRPC stream retains buffer state. Researcher's spike on #336
+ * traced 17h-runtime memory growth to retained `WorkflowExecutionInfo`
+ * protobufs hanging off un-completed iterator streams.
+ *
+ * The fix per site is small (≤ 12 LoC), but the **caller's correctness
+ * model around partial enumeration is what varies** — three patterns:
+ *
+ * - **Partial-tolerant + warn-log**: silently breaking out is safe;
+ *   the caller treats the truncated result as a best-effort snapshot
+ *   that the next tick / retry will fill in. (Sites 2, 3, 5)
+ * - **Structured outcome**: the caller branches on whether enumeration
+ *   completed. Sites 4 (`fireSchedule target='all'`) extends its
+ *   existing `{delivered, failures}` result. Site 1 (`resolveSession`)
+ *   throws {@link VisibilityIteratorTimeoutError} so callers can
+ *   distinguish "definitely absent" from "scan didn't finish."
+ * - **Skip the entire tick / preserve prior state**: AggregateRunner's
+ *   ensemble-set diff (site 6) — partial results would emit phantom
+ *   `ensemble.destroyed` SSE events. Handled separately via the
+ *   architect-approved invariant in `src/http/aggregate.ts`.
+ *
+ * ## Deadline tuning rationale
+ *
+ * Per-site defaults live in {@link VISIBILITY_DEADLINES_MS}. Numbers
+ * chosen to balance:
+ *
+ * - The caller's tick cadence (a 5s deadline is "instant" if the
+ *   caller polls every 750ms but "an eternity" if they boot once and
+ *   never retry).
+ * - The expected scan depth (orphan boot scan walks every running
+ *   session workflow across every host; aggregate poll walks the same
+ *   set but happens 80× per minute).
+ * - Headroom against the activity-level StartToClose timeout
+ *   (typically 60s) — the iterator deadline should fire well before
+ *   StartToClose so the activity returns a structured "timed out"
+ *   outcome rather than getting force-cancelled by Temporal.
+ *
+ * Tune per site rather than chasing a single magic number; reviewer
+ * sanity-checks the values in this map during PR review.
+ */
+import type { WorkflowExecutionInfo } from '@temporalio/client';
+/**
+ * Per-site deadline budgets for visibility iterators (#336/#529).
+ *
+ * Adding a new site? Pick a deadline that:
+ * 1. Comfortably fits within the caller's StartToClose if it runs as an activity.
+ * 2. Is short enough that a wedged iterator can't dominate the caller's tick budget.
+ * 3. Documents the rationale below.
+ */
+export declare const VISIBILITY_DEADLINES_MS: {
+    /**
+     * `resolveSession` — finds a single `(ensemble, playerId)` in the
+     * running-session set. Called from outbox / CLI / tools on every
+     * cue/signal/restart. 10s gives plenty of headroom for a healthy
+     * lookup while preventing a wedged session worker from holding the
+     * outbox loop indefinitely (per-workflow `getMetadata` already
+     * bounded at #433's `queryHandleWithTimeout`).
+     */
+    readonly resolveSession: 10000;
+    /**
+     * `scanEnsembleSessions` — full ensemble enumeration with metadata
+     * + part + activity-state per session. Called from the `ensemble`
+     * MCP tool and the maestro refresh activity. 15s allows scanning
+     * hundreds of workflows with the per-query bounds at #433.
+     */
+    readonly scanEnsembleSessions: 15000;
+    /**
+     * `discoverEnsembles` (maestro activity) — aggregates unique ensemble
+     * names. 10s; the maestro retries on its own schedule, so a partial
+     * result self-heals on the next tick.
+     */
+    readonly discoverEnsembles: 10000;
+    /**
+     * `fireSchedule target='all'` — broadcast loop. 20s; broadcasts can
+     * fan out to many players, and the caller's existing `failures: []`
+     * surface already records partial delivery — extending it with a
+     * `timedOut` flag preserves the "scheduler promised 'all'" semantic.
+     */
+    readonly fireScheduleAll: 20000;
+    /**
+     * `queryOrphanedSessions` boot scan — runs once at daemon startup.
+     * 60s budget because losing an orphan means a session goes
+     * un-reconciled, but the function's existing comment explicitly
+     * marks partial results as acceptable ("next tick will retry").
+     */
+    readonly orphanQueryBoot: 60000;
+    /**
+     * `queryOrphanedSessions` cleanup loop — 6h-cadence sweep. 30s;
+     * shorter than boot because the cleanup loop runs frequently
+     * enough to amortize partial scans across many sweeps.
+     */
+    readonly orphanQueryCleanup: 30000;
+};
+export type VisibilitySite = keyof typeof VISIBILITY_DEADLINES_MS;
+/**
+ * Thrown by {@link iterateWithDeadline} when the per-iterator deadline
+ * fires. Callers that want to distinguish "scan didn't finish" from
+ * "scan completed with N results" should catch this error specifically.
+ *
+ * Carries `site` (which deadline tripped) and `partialCount` (how many
+ * entries were yielded before the timeout) so warn-log surfaces are
+ * actionable — `"orphanQueryBoot timed out after 60000ms, partial=423"`
+ * tells the operator both which budget is too tight AND how close to
+ * complete the scan got.
+ */
+export declare class VisibilityIteratorTimeoutError extends Error {
+    readonly site: string;
+    readonly deadlineMs: number;
+    readonly partialCount: number;
+    readonly name = "VisibilityIteratorTimeoutError";
+    constructor(site: string, deadlineMs: number, partialCount: number);
+}
+/**
+ * Wrap an async iterable of `WorkflowExecutionInfo` (the type yielded
+ * by `client.workflow.list({ query })`) with a wall-clock deadline.
+ *
+ * Yields entries until either the upstream iterator exhausts (normal
+ * end) or `Date.now() > deadline` (timeout). On timeout, throws
+ * {@link VisibilityIteratorTimeoutError} after the in-progress
+ * iteration completes — so the caller can choose whether to swallow
+ * the throw (partial-tolerant pattern) or propagate it.
+ *
+ * The deadline check fires **before** each yield, not after — so the
+ * iterator never spends time fetching a page it won't consume. The
+ * `partialCount` reported in the error reflects entries yielded, not
+ * pages fetched, which matches what operators care about.
+ *
+ * ## Usage pattern (partial-tolerant)
+ *
+ * ```ts
+ * try {
+ *   for await (const wf of iterateWithDeadline(
+ *     client.workflow.list({ query }),
+ *     VISIBILITY_DEADLINES_MS.scanEnsembleSessions,
+ *     'scanEnsembleSessions',
+ *   )) {
+ *     // existing loop body
+ *   }
+ * } catch (err) {
+ *   if (err instanceof VisibilityIteratorTimeoutError) {
+ *     log('warn: ' + err.message + ' — returning partial results');
+ *     // fall through to return whatever we accumulated
+ *   } else {
+ *     throw err;
+ *   }
+ * }
+ * ```
+ *
+ * ## Usage pattern (structured outcome)
+ *
+ * ```ts
+ * let timedOut = false;
+ * try {
+ *   for await (const wf of iterateWithDeadline(...)) { ... }
+ * } catch (err) {
+ *   if (err instanceof VisibilityIteratorTimeoutError) {
+ *     timedOut = true;
+ *     // fall through — caller surfaces `timedOut` in the result
+ *   } else {
+ *     throw err;
+ *   }
+ * }
+ * return { success: !timedOut, ..., timedOut };
+ * ```
+ */
+export declare function iterateWithDeadline(source: AsyncIterable<WorkflowExecutionInfo>, deadlineMs: number, site: string, 
+/** Test-only — defaults to `Date.now`; injectable so unit tests can advance the clock. */
+now?: () => number): AsyncGenerator<WorkflowExecutionInfo>;
+/**
+ * Compose `iterateWithDeadline` with the partial-tolerant catch pattern
+ * for sites that just want "log a warn, return what we got."
+ *
+ * Sites 2, 3, 5 use this; sites 1 + 4 use the raw iterator so they can
+ * carry the timeout signal into their return shape.
+ */
+export declare function isVisibilityTimeout(err: unknown): err is VisibilityIteratorTimeoutError;

package/dist/utils/visibility-deadline.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VisibilityIteratorTimeoutError = exports.VISIBILITY_DEADLINES_MS = void 0;
+exports.iterateWithDeadline = iterateWithDeadline;
+exports.isVisibilityTimeout = isVisibilityTimeout;
+/**
+ * Per-site deadline budgets for visibility iterators (#336/#529).
+ *
+ * Adding a new site? Pick a deadline that:
+ * 1. Comfortably fits within the caller's StartToClose if it runs as an activity.
+ * 2. Is short enough that a wedged iterator can't dominate the caller's tick budget.
+ * 3. Documents the rationale below.
+ */
+exports.VISIBILITY_DEADLINES_MS = {
+    /**
+     * `resolveSession` — finds a single `(ensemble, playerId)` in the
+     * running-session set. Called from outbox / CLI / tools on every
+     * cue/signal/restart. 10s gives plenty of headroom for a healthy
+     * lookup while preventing a wedged session worker from holding the
+     * outbox loop indefinitely (per-workflow `getMetadata` already
+     * bounded at #433's `queryHandleWithTimeout`).
+     */
+    resolveSession: 10_000,
+    /**
+     * `scanEnsembleSessions` — full ensemble enumeration with metadata
+     * + part + activity-state per session. Called from the `ensemble`
+     * MCP tool and the maestro refresh activity. 15s allows scanning
+     * hundreds of workflows with the per-query bounds at #433.
+     */
+    scanEnsembleSessions: 15_000,
+    /**
+     * `discoverEnsembles` (maestro activity) — aggregates unique ensemble
+     * names. 10s; the maestro retries on its own schedule, so a partial
+     * result self-heals on the next tick.
+     */
+    discoverEnsembles: 10_000,
+    /**
+     * `fireSchedule target='all'` — broadcast loop. 20s; broadcasts can
+     * fan out to many players, and the caller's existing `failures: []`
+     * surface already records partial delivery — extending it with a
+     * `timedOut` flag preserves the "scheduler promised 'all'" semantic.
+     */
+    fireScheduleAll: 20_000,
+    /**
+     * `queryOrphanedSessions` boot scan — runs once at daemon startup.
+     * 60s budget because losing an orphan means a session goes
+     * un-reconciled, but the function's existing comment explicitly
+     * marks partial results as acceptable ("next tick will retry").
+     */
+    orphanQueryBoot: 60_000,
+    /**
+     * `queryOrphanedSessions` cleanup loop — 6h-cadence sweep. 30s;
+     * shorter than boot because the cleanup loop runs frequently
+     * enough to amortize partial scans across many sweeps.
+     */
+    orphanQueryCleanup: 30_000,
+};
+/**
+ * Thrown by {@link iterateWithDeadline} when the per-iterator deadline
+ * fires. Callers that want to distinguish "scan didn't finish" from
+ * "scan completed with N results" should catch this error specifically.
+ *
+ * Carries `site` (which deadline tripped) and `partialCount` (how many
+ * entries were yielded before the timeout) so warn-log surfaces are
+ * actionable — `"orphanQueryBoot timed out after 60000ms, partial=423"`
+ * tells the operator both which budget is too tight AND how close to
+ * complete the scan got.
+ */
+class VisibilityIteratorTimeoutError extends Error {
+    site;
+    deadlineMs;
+    partialCount;
+    name = 'VisibilityIteratorTimeoutError';
+    constructor(site, deadlineMs, partialCount) {
+        super(`Visibility iterator "${site}" exceeded ${deadlineMs}ms deadline ` +
+            `after ${partialCount} entries`);
+        this.site = site;
+        this.deadlineMs = deadlineMs;
+        this.partialCount = partialCount;
+    }
+}
+exports.VisibilityIteratorTimeoutError = VisibilityIteratorTimeoutError;
+/**
+ * Wrap an async iterable of `WorkflowExecutionInfo` (the type yielded
+ * by `client.workflow.list({ query })`) with a wall-clock deadline.
+ *
+ * Yields entries until either the upstream iterator exhausts (normal
+ * end) or `Date.now() > deadline` (timeout). On timeout, throws
+ * {@link VisibilityIteratorTimeoutError} after the in-progress
+ * iteration completes — so the caller can choose whether to swallow
+ * the throw (partial-tolerant pattern) or propagate it.
+ *
+ * The deadline check fires **before** each yield, not after — so the
+ * iterator never spends time fetching a page it won't consume. The
+ * `partialCount` reported in the error reflects entries yielded, not
+ * pages fetched, which matches what operators care about.
+ *
+ * ## Usage pattern (partial-tolerant)
+ *
+ * ```ts
+ * try {
+ *   for await (const wf of iterateWithDeadline(
+ *     client.workflow.list({ query }),
+ *     VISIBILITY_DEADLINES_MS.scanEnsembleSessions,
+ *     'scanEnsembleSessions',
+ *   )) {
+ *     // existing loop body
+ *   }
+ * } catch (err) {
+ *   if (err instanceof VisibilityIteratorTimeoutError) {
+ *     log('warn: ' + err.message + ' — returning partial results');
+ *     // fall through to return whatever we accumulated
+ *   } else {
+ *     throw err;
+ *   }
+ * }
+ * ```
+ *
+ * ## Usage pattern (structured outcome)
+ *
+ * ```ts
+ * let timedOut = false;
+ * try {
+ *   for await (const wf of iterateWithDeadline(...)) { ... }
+ * } catch (err) {
+ *   if (err instanceof VisibilityIteratorTimeoutError) {
+ *     timedOut = true;
+ *     // fall through — caller surfaces `timedOut` in the result
+ *   } else {
+ *     throw err;
+ *   }
+ * }
+ * return { success: !timedOut, ..., timedOut };
+ * ```
+ */
+async function* iterateWithDeadline(source, deadlineMs, site, 
+/** Test-only — defaults to `Date.now`; injectable so unit tests can advance the clock. */
+now = Date.now) {
+    const deadline = now() + deadlineMs;
+    let count = 0;
+    for await (const entry of source) {
+        if (now() > deadline) {
+            throw new VisibilityIteratorTimeoutError(site, deadlineMs, count);
+        }
+        yield entry;
+        count++;
+    }
+}
+/**
+ * Compose `iterateWithDeadline` with the partial-tolerant catch pattern
+ * for sites that just want "log a warn, return what we got."
+ *
+ * Sites 2, 3, 5 use this; sites 1 + 4 use the raw iterator so they can
+ * carry the timeout signal into their return shape.
+ */
+function isVisibilityTimeout(err) {
+    return err instanceof VisibilityIteratorTimeoutError;
+}