agent-tempo 1.7.0-beta.8 → 1.7.0

package/dist/activities/resolve.d.ts

@@ -1,5 +1,16 @@
 import { Client, WorkflowHandle } from '@temporalio/client';
 import { AttachmentPhase } from '../types';
+/**
+ * Mode-B describe-by-id timeout (#845). The strongly-consistent
+ * `describe()` fallback on `resolveSession`'s not-found branch is a single
+ * O(1) RPC; 2s mirrors {@link DEFAULT_QUERY_TIMEOUT_MS} — two orders of
+ * magnitude over a healthy describe — so a wedged frontend can't re-hang
+ * the outbox loop the visibility deadline (#336/#529) was added to bound.
+ */
+export declare const RESOLVE_DESCRIBE_TIMEOUT_MS = 2000;
+/** Shared query for listing running session workflows. Exported for the
+ *  ensemble-scoped variants in `client/core.ts` (#751). */
+export declare const SESSION_LIST_QUERY = "WorkflowType = \"agentSessionWorkflow\" AND ExecutionStatus = \"Running\"";
 /**
  * Resolve a session by player name.
  * Lists all running session workflows and queries each for metadata.
@@ -8,15 +19,43 @@ import { AttachmentPhase } from '../types';
  *
  * Shared by activity files (outbox, schedule-fire) and the tools layer.
  *
- * **Deadline (#336/#529):** the visibility iterator is bounded by
- * `VISIBILITY_DEADLINES_MS.resolveSession` (default 10s). On timeout,
- * throws `VisibilityIteratorTimeoutError` rather than returning `null`
- * — silent `null` on a partially-scanned set would be indistinguishable
- * from "definitely not found," producing false "Player not found" errors
- * upstream. Every existing caller wraps this in a try/catch (outbox
- * activities, MCP tools' `defineTool` helper, CLI dev-verbs); the throw
- * propagates as a retryable / user-visible "lookup timed out" rather
- * than the misleading "player not found."
+ * DECISION-PATH FENCE (#748): this resolver feeds DECISION paths (outbox
+ * delivery addressing, schedule fires, tool targets). It must keep its
+ * direct per-session `getMetadata` queries — do NOT migrate it to the
+ * eventually-consistent SA/memo read path. Observation-only scans belong
+ * in `scanEnsembleSessionsCloud`. Enforced by
+ * tests/conformance/decision-path-fence.test.ts.
+ *
+ * **Mode A — deadline truncation (#336/#529):** the visibility iterator is
+ * bounded by `VISIBILITY_DEADLINES_MS.resolveSession` (default 10s). On
+ * timeout it throws `VisibilityIteratorTimeoutError` rather than returning
+ * `null` — silent `null` on a partially-scanned set would be
+ * indistinguishable from "definitely not found." The throw is classified
+ * **retryable** by the outbox activity (`isRetryableTemporalError`), so
+ * Temporal's activity retry policy re-runs the lookup with a fresh
+ * deadline rather than collapsing it to a permanent "player not found."
+ * Synchronous tool/CLI callers surface it as a distinct "resolution
+ * incomplete — retry," never "not found."
+ *
+ * **Mode B — visibility-index lag (#845):** `list()` can complete normally
+ * (no throw) yet miss a freshly-started workflow because the visibility
+ * index trails the workflow store (observed live as a 3/8→8/8 roster
+ * during post-restart worker warmup). An early-exhausting scan is NOT
+ * proof of absence. So on the not-found branch we do **exactly one**
+ * strongly-consistent `describe()` against the *derived* workflow id —
+ * an O(1) read by primary key that bypasses the lagging index. This is a
+ * point lookup, NOT a re-scan: it cannot re-introduce the unbounded-scan
+ * hang the deadline guard was added to prevent.
+ *
+ * **Documented Mode-B limitation:** the derived id
+ * `agent-session-{ensemble}-{playerName}` is minted from a player's
+ * INITIAL name at spawn; `set_name` does not change the workflow id. So
+ * describe-by-derived-id false-negatives for a player that was both
+ * RENAMED and is currently index-lagged — it falls back to `null` (looks
+ * absent) for that narrow intersection. Accepted by design: it closes the
+ * gap for the cold-boot/warmup incident class (nobody renames mid-boot),
+ * and a second full re-scan to cover renamed∩lagged would put scan cost on
+ * every genuine typo'd-name lookup. See issue #845.
  */
 export declare function resolveSession(client: Client, ensemble: string, playerName: string): Promise<WorkflowHandle | null>;
 /** Info returned for each session by scanEnsembleSessions. */
@@ -50,15 +89,77 @@ export interface EnsembleSessionInfo {
     lastActivityAt?: string;
 }
 /**
- * Scan all running session workflows in an ensemble.
- * Returns metadata + part for each session. Shared by the ensemble MCP tool
- * and the Maestro refresh activity.
+ * T0.1 (#748) — cloud-profile ensemble scan. Observation path ONLY (see the
+ * DECISION-PATH FENCE on {@link resolveSession}).
+ *
+ * Differences vs the legacy {@link scanEnsembleSessions}:
+ *   - The visibility query is **ensemble-scoped** via the `AgentTempoEnsemble`
+ *     filter SA — no more cluster-wide list + per-session `getMetadata`
+ *     pre-filtering (the unfiltered scan was the dominant idle-burn driver).
+ *   - For v1.8+ runs (memo-complete: `AgentTempoWorkDir` present), the entire
+ *     player row is read from the list result (SAs + memo) — **zero**
+ *     per-player queries except the BPM `getActivityState` query, which is
+ *     intentionally kept per the architect's ruling (deriving BPM from phase
+ *     transitions would change the metric's meaning).
+ *   - Pre-v1.8 runs (no observation memo) fall back to the legacy per-player
+ *     `getMetadata` + `getPart` queries — cost shrinks as old runs cycle out.
+ *
+ * Staleness: SA/memo reads are eventually consistent (tens of seconds worst
+ * case under backlog) — acceptable for the observation path per the design
+ * addendum §B; the aggregate's confirm-on-change hook re-validates phase
+ * transitions with a direct query before emitting SSE events.
+ */
+export declare function scanEnsembleSessionsCloud(client: Client, ensemble: string, log?: (...args: unknown[]) => void): Promise<EnsembleSessionInfo[]>;
+/**
+ * Result of {@link scanEnsembleSessionsWithStatus} — the session rows plus
+ * whether the visibility scan completed or was cut short (#845).
+ *
+ * `truncated` is the Mode-A signal: a `VisibilityIteratorTimeoutError`
+ * fired (the wall-clock deadline tripped mid-scan), so `sessions` is a
+ * partial snapshot, NOT the full roster. Callers that render a roster (the
+ * `ensemble` tool) MUST surface this so a partial set is never mistaken
+ * for a complete one. NOTE: this does NOT cover Mode B (visibility-index
+ * lag) — there the scan completes normally and `truncated` is `false` even
+ * though a freshly-started workflow may be missing; that's best-effort by
+ * design and self-heals on the next tick.
+ *
+ * `scanned` is the number of running workflows the iterator visited before
+ * completing or timing out — useful for warn logs ("partial: 3 of ≥N").
+ */
+export interface EnsembleScanResult {
+    sessions: EnsembleSessionInfo[];
+    truncated: boolean;
+    scanned: number;
+}
+/**
+ * Scan all running session workflows in an ensemble, reporting whether the
+ * scan completed or was truncated by the visibility deadline (#845).
+ *
+ * This is the single source of truth for the local-profile ensemble scan;
+ * {@link scanEnsembleSessions} is a thin array-facade over it that drops
+ * the status fields for the many callers that don't need them.
  *
  * **Deadline (#336/#529):** the iterator is bounded by
- * `VISIBILITY_DEADLINES_MS.scanEnsembleSessions` (default 15s). On
- * timeout, returns the partial result accumulated so far and emits a
- * warn log. This site is **partial-tolerant by design** — the caller
- * (maestro refresh, ensemble MCP tool) treats the result as a
- * best-effort snapshot that the next tick / re-invocation will fill in.
+ * `VISIBILITY_DEADLINES_MS.scanEnsembleSessions` (default 15s). On timeout
+ * the accumulated rows are returned with `truncated: true` and a warn log
+ * — the scan is **partial-tolerant by design**, but the truncation is now
+ * SIGNALLED rather than silent so a roster renderer can flag it.
+ *
+ * T0.1 (#748): this legacy shape is the `costProfile: 'local'` path —
+ * byte-identical row data to pre-#748 behavior. The cloud profile uses
+ * {@link scanEnsembleSessionsCloud}.
+ */
+export declare function scanEnsembleSessionsWithStatus(client: Client, ensemble: string, log?: (...args: unknown[]) => void): Promise<EnsembleScanResult>;
+/**
+ * Scan all running session workflows in an ensemble — array facade over
+ * {@link scanEnsembleSessionsWithStatus}.
+ *
+ * Returns just the session rows; the truncation/scan-status fields are
+ * dropped. This is the byte-identical shape the maestro refresh activity,
+ * the #785 upgrade-snapshot, and the other roster consumers already depend
+ * on — keeping it a thin delegate means the truncation-signalling work
+ * (#845) does NOT ripple through those call sites. Callers that need to
+ * know whether the scan was complete (the `ensemble` tool) call the rich
+ * sibling directly.
  */
 export declare function scanEnsembleSessions(client: Client, ensemble: string, log?: (...args: unknown[]) => void): Promise<EnsembleSessionInfo[]>;

package/dist/activities/resolve.js

@@ -1,13 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SESSION_LIST_QUERY = exports.RESOLVE_DESCRIBE_TIMEOUT_MS = void 0;
 exports.resolveSession = resolveSession;
+exports.scanEnsembleSessionsCloud = scanEnsembleSessionsCloud;
+exports.scanEnsembleSessionsWithStatus = scanEnsembleSessionsWithStatus;
 exports.scanEnsembleSessions = scanEnsembleSessions;
+const config_1 = require("../config");
 const search_attributes_1 = require("../utils/search-attributes");
 const signals_1 = require("../workflows/signals");
 const query_timeout_1 = require("../utils/query-timeout");
 const visibility_deadline_1 = require("../utils/visibility-deadline");
-/** Shared query for listing running session workflows. */
-const SESSION_LIST_QUERY = `WorkflowType = "agentSessionWorkflow" AND ExecutionStatus = "Running"`;
+/**
+ * Mode-B describe-by-id timeout (#845). The strongly-consistent
+ * `describe()` fallback on `resolveSession`'s not-found branch is a single
+ * O(1) RPC; 2s mirrors {@link DEFAULT_QUERY_TIMEOUT_MS} — two orders of
+ * magnitude over a healthy describe — so a wedged frontend can't re-hang
+ * the outbox loop the visibility deadline (#336/#529) was added to bound.
+ */
+exports.RESOLVE_DESCRIBE_TIMEOUT_MS = 2000;
+/** Shared query for listing running session workflows. Exported for the
+ *  ensemble-scoped variants in `client/core.ts` (#751). */
+exports.SESSION_LIST_QUERY = `WorkflowType = "agentSessionWorkflow" AND ExecutionStatus = "Running"`;
 /**
  * Resolve a session by player name.
  * Lists all running session workflows and queries each for metadata.
@@ -16,18 +29,46 @@ const SESSION_LIST_QUERY = `WorkflowType = "agentSessionWorkflow" AND ExecutionS
  *
  * Shared by activity files (outbox, schedule-fire) and the tools layer.
  *
- * **Deadline (#336/#529):** the visibility iterator is bounded by
- * `VISIBILITY_DEADLINES_MS.resolveSession` (default 10s). On timeout,
- * throws `VisibilityIteratorTimeoutError` rather than returning `null`
- * — silent `null` on a partially-scanned set would be indistinguishable
- * from "definitely not found," producing false "Player not found" errors
- * upstream. Every existing caller wraps this in a try/catch (outbox
- * activities, MCP tools' `defineTool` helper, CLI dev-verbs); the throw
- * propagates as a retryable / user-visible "lookup timed out" rather
- * than the misleading "player not found."
+ * DECISION-PATH FENCE (#748): this resolver feeds DECISION paths (outbox
+ * delivery addressing, schedule fires, tool targets). It must keep its
+ * direct per-session `getMetadata` queries — do NOT migrate it to the
+ * eventually-consistent SA/memo read path. Observation-only scans belong
+ * in `scanEnsembleSessionsCloud`. Enforced by
+ * tests/conformance/decision-path-fence.test.ts.
+ *
+ * **Mode A — deadline truncation (#336/#529):** the visibility iterator is
+ * bounded by `VISIBILITY_DEADLINES_MS.resolveSession` (default 10s). On
+ * timeout it throws `VisibilityIteratorTimeoutError` rather than returning
+ * `null` — silent `null` on a partially-scanned set would be
+ * indistinguishable from "definitely not found." The throw is classified
+ * **retryable** by the outbox activity (`isRetryableTemporalError`), so
+ * Temporal's activity retry policy re-runs the lookup with a fresh
+ * deadline rather than collapsing it to a permanent "player not found."
+ * Synchronous tool/CLI callers surface it as a distinct "resolution
+ * incomplete — retry," never "not found."
+ *
+ * **Mode B — visibility-index lag (#845):** `list()` can complete normally
+ * (no throw) yet miss a freshly-started workflow because the visibility
+ * index trails the workflow store (observed live as a 3/8→8/8 roster
+ * during post-restart worker warmup). An early-exhausting scan is NOT
+ * proof of absence. So on the not-found branch we do **exactly one**
+ * strongly-consistent `describe()` against the *derived* workflow id —
+ * an O(1) read by primary key that bypasses the lagging index. This is a
+ * point lookup, NOT a re-scan: it cannot re-introduce the unbounded-scan
+ * hang the deadline guard was added to prevent.
+ *
+ * **Documented Mode-B limitation:** the derived id
+ * `agent-session-{ensemble}-{playerName}` is minted from a player's
+ * INITIAL name at spawn; `set_name` does not change the workflow id. So
+ * describe-by-derived-id false-negatives for a player that was both
+ * RENAMED and is currently index-lagged — it falls back to `null` (looks
+ * absent) for that narrow intersection. Accepted by design: it closes the
+ * gap for the cold-boot/warmup incident class (nobody renames mid-boot),
+ * and a second full re-scan to cover renamed∩lagged would put scan cost on
+ * every genuine typo'd-name lookup. See issue #845.
  */
 async function resolveSession(client, ensemble, playerName) {
-    for await (const wf of (0, visibility_deadline_1.iterateWithDeadline)(client.workflow.list({ query: SESSION_LIST_QUERY }), visibility_deadline_1.VISIBILITY_DEADLINES_MS.resolveSession, 'resolveSession')) {
+    for await (const wf of (0, visibility_deadline_1.iterateWithDeadline)(client.workflow.list({ query: exports.SESSION_LIST_QUERY }), visibility_deadline_1.VISIBILITY_DEADLINES_MS.resolveSession, 'resolveSession')) {
         try {
             const handle = client.workflow.getHandle(wf.workflowId);
             // Issue #433 — bound the per-session metadata query so a wedged
@@ -39,33 +80,204 @@ async function resolveSession(client, ensemble, playerName) {
             }
         }
         catch (err) {
-            // Re-throw deadline timeouts — callers that wrap us in try/catch
-            // already treat unknown throws as a soft "lookup failed" path,
-            // and the typed error name makes the failure mode legible in
-            // outbox logs / user-facing tool errors.
+            // Re-throw deadline timeouts (Mode A) — callers that wrap us in
+            // try/catch treat the typed throw as a soft "lookup timed out" path,
+            // distinct from the not-found `null` below.
             if ((0, visibility_deadline_1.isVisibilityTimeout)(err))
                 throw err;
             // Workflow may have just completed, or worker is wedged (#433) — skip
         }
     }
-    return null;
+    // Mode B (#845): the scan completed without a match, but the visibility
+    // index may simply be lagging a just-started workflow. One strongly-
+    // consistent describe-by-derived-id disambiguates "index lag" from
+    // "genuinely absent" without a second scan.
+    return resolveByDerivedId(client, ensemble, playerName);
+}
+/**
+ * Mode-B (#845) strongly-consistent fallback for {@link resolveSession}.
+ *
+ * Reads the session workflow by its *derived* id
+ * (`agent-session-{ensemble}-{playerName}`) via a single bounded
+ * `describe()` — a primary-key lookup that bypasses the eventually-
+ * consistent visibility index. Returns the handle whenever the execution
+ * is `RUNNING`; otherwise `null` (genuinely absent, terminated/completed,
+ * renamed-false-negative, or describe timed out).
+ *
+ * Deliberately RUNNING-only — NO attachment-phase filter (#845 JC2): a
+ * `gone` player has a LIVE workflow with a terminal adapter, which the
+ * #822/#834 deliverability contract handles as warn-but-queue, not
+ * "not found". Filtering it here would regress #834 for the lagged-gone
+ * window and diverge from the main scan loop (which has no phase filter).
+ */
+async function resolveByDerivedId(client, ensemble, playerName) {
+    let timer;
+    try {
+        // `getHandle` is a lazy, no-RPC handle construction in the real client;
+        // kept inside the try purely so a defensive throw can never escape the
+        // fallback (it must only ever upgrade a null to a handle, never error).
+        const handle = client.workflow.getHandle((0, config_1.sessionWorkflowId)(ensemble, playerName));
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error('describe-by-id timed out')), exports.RESOLVE_DESCRIBE_TIMEOUT_MS);
+            timer.unref?.();
+        });
+        const desc = await Promise.race([handle.describe(), timeout]);
+        // Only a live (RUNNING) execution is a valid resolve target. A
+        // COMPLETED/TERMINATED latest run at this id means the player is gone,
+        // or the id was reused by a since-closed run → null. A RUNNING run
+        // under a reused id is legitimately the current player → return it.
+        //
+        // No attachment-phase filter (#845 JC2, architect ruling): the main
+        // scan loop returns the handle for ANY running session — phase=`gone`
+        // included — and #822/#834 treat `gone` as warn-but-QUEUE (the cue
+        // durably queues and auto-redelivers on re-attach), NOT "not found".
+        // Returning null for a lagged-`gone` player would bypass #822, re-
+        // introduce the false-not-found #834 fixed, and make resolution depend
+        // on visibility-index timing. The "don't deliver to a torn-down
+        // adapter" concern lives at the deliverability layer, not here.
+        if (desc.status.name !== 'RUNNING')
+            return null;
+        return handle;
+    }
+    catch {
+        // NotFound → genuinely absent (or the renamed∩lagged false-negative
+        // documented on resolveSession). Timeout/other → treat as absent; the
+        // caller's not-found path (or the activity retry policy for Mode A)
+        // handles it. We never throw from the fallback — it can only upgrade a
+        // null to a found handle, never turn a clean lookup into an error.
+        return null;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
 }
 /**
- * Scan all running session workflows in an ensemble.
- * Returns metadata + part for each session. Shared by the ensemble MCP tool
- * and the Maestro refresh activity.
+ * T0.1 (#748) — cloud-profile ensemble scan. Observation path ONLY (see the
+ * DECISION-PATH FENCE on {@link resolveSession}).
+ *
+ * Differences vs the legacy {@link scanEnsembleSessions}:
+ *   - The visibility query is **ensemble-scoped** via the `AgentTempoEnsemble`
+ *     filter SA — no more cluster-wide list + per-session `getMetadata`
+ *     pre-filtering (the unfiltered scan was the dominant idle-burn driver).
+ *   - For v1.8+ runs (memo-complete: `AgentTempoWorkDir` present), the entire
+ *     player row is read from the list result (SAs + memo) — **zero**
+ *     per-player queries except the BPM `getActivityState` query, which is
+ *     intentionally kept per the architect's ruling (deriving BPM from phase
+ *     transitions would change the metric's meaning).
+ *   - Pre-v1.8 runs (no observation memo) fall back to the legacy per-player
+ *     `getMetadata` + `getPart` queries — cost shrinks as old runs cycle out.
+ *
+ * Staleness: SA/memo reads are eventually consistent (tens of seconds worst
+ * case under backlog) — acceptable for the observation path per the design
+ * addendum §B; the aggregate's confirm-on-change hook re-validates phase
+ * transitions with a direct query before emitting SSE events.
+ */
+async function scanEnsembleSessionsCloud(client, ensemble, log = () => { }) {
+    const sessions = [];
+    const query = `${exports.SESSION_LIST_QUERY} AND AgentTempoEnsemble = "${(0, search_attributes_1.sanitizeQueryValue)(ensemble)}"`;
+    try {
+        for await (const workflow of (0, visibility_deadline_1.iterateWithDeadline)(client.workflow.list({ query }), visibility_deadline_1.VISIBILITY_DEADLINES_MS.scanEnsembleSessions, 'scanEnsembleSessionsCloud')) {
+            try {
+                const handle = client.workflow.getHandle(workflow.workflowId);
+                const phase = (0, search_attributes_1.getAttachmentPhase)(workflow);
+                const playerId = (0, search_attributes_1.getSearchAttrString)(workflow, 'AgentTempoPlayerId') ?? workflow.workflowId;
+                const hostname = (0, search_attributes_1.getSearchAttrString)(workflow, 'AgentTempoHostname') ?? '';
+                // v1.8-memo-observation-fields runs carry workDir on the memo — use
+                // its presence as the "memo-complete row" discriminator.
+                const workDir = (0, search_attributes_1.getMemoString)(workflow, search_attributes_1.MEMO_KEYS.workDir);
+                let row;
+                if (workDir !== undefined) {
+                    row = {
+                        playerId,
+                        part: (0, search_attributes_1.getPart)(workflow) ?? '',
+                        hostname,
+                        workDir,
+                        gitRoot: (0, search_attributes_1.getWorkflowMetaString)(workflow, search_attributes_1.MEMO_KEYS.gitRoot),
+                        gitBranch: (0, search_attributes_1.getMemoString)(workflow, search_attributes_1.MEMO_KEYS.gitBranch),
+                        isConductor: (0, search_attributes_1.getIsConductor)(workflow)
+                            ?? (workflow.workflowId?.endsWith('-conductor') ?? false),
+                        agentType: (0, search_attributes_1.getMemoString)(workflow, search_attributes_1.MEMO_KEYS.agentType) || 'claude',
+                        playerType: (0, search_attributes_1.getPlayerType)(workflow),
+                    };
+                }
+                else {
+                    // Legacy run (pre-v1.8 memo) — per-player query fallback, bounded
+                    // (#433). Same two queries the legacy scan used.
+                    const metadata = await (0, query_timeout_1.queryHandleWithTimeout)(handle, 'getMetadata');
+                    const part = await (0, query_timeout_1.queryHandleWithTimeout)(handle, 'getPart');
+                    row = {
+                        playerId: metadata.playerId,
+                        part,
+                        hostname: metadata.hostname,
+                        workDir: metadata.workDir,
+                        gitRoot: metadata.gitRoot,
+                        gitBranch: metadata.gitBranch,
+                        isConductor: metadata.isConductor,
+                        agentType: metadata.agentType || 'claude',
+                        playerType: metadata.playerType,
+                    };
+                }
+                // BPM fields filled in below — kept out of the enumeration loop so
+                // per-player query latency can't eat the visibility deadline.
+                sessions.push({ workflowId: workflow.workflowId, ...row, phase });
+            }
+            catch {
+                // Workflow may have just completed, or a legacy-fallback query timed
+                // out (#433) — skip this row; the next tick fills it in.
+            }
+        }
+    }
+    catch (err) {
+        if ((0, visibility_deadline_1.isVisibilityTimeout)(err)) {
+            log(`scanEnsembleSessionsCloud: ${err.message} — returning partial (${sessions.length} sessions)`);
+        }
+        else {
+            throw err;
+        }
+    }
+    // BPM source — kept as a direct per-player query at the stretched cadence
+    // (architect's ruling; see design addendum §C(b)). Fired in PARALLEL after
+    // enumeration: same query count, but N bounded queries (≤2s each) overlap
+    // instead of stacking sequentially against the scan's wall clock.
+    // Best-effort per player — a wedged session contributes zero tempo.
+    await Promise.all(sessions.map(async (s) => {
+        try {
+            const activity = await (0, query_timeout_1.queryHandleWithTimeout)(client.workflow.getHandle(s.workflowId), signals_1.getActivityStateQuery);
+            s.activityCount = activity.activityCount;
+            s.lastActivityAt = activity.lastActivityAt;
+        }
+        catch {
+            // Session predates W2 or worker wedged — contributes zero tempo.
+        }
+    }));
+    return sessions;
+}
+/**
+ * Scan all running session workflows in an ensemble, reporting whether the
+ * scan completed or was truncated by the visibility deadline (#845).
+ *
+ * This is the single source of truth for the local-profile ensemble scan;
+ * {@link scanEnsembleSessions} is a thin array-facade over it that drops
+ * the status fields for the many callers that don't need them.
  *
  * **Deadline (#336/#529):** the iterator is bounded by
- * `VISIBILITY_DEADLINES_MS.scanEnsembleSessions` (default 15s). On
- * timeout, returns the partial result accumulated so far and emits a
- * warn log. This site is **partial-tolerant by design** — the caller
- * (maestro refresh, ensemble MCP tool) treats the result as a
- * best-effort snapshot that the next tick / re-invocation will fill in.
+ * `VISIBILITY_DEADLINES_MS.scanEnsembleSessions` (default 15s). On timeout
+ * the accumulated rows are returned with `truncated: true` and a warn log
+ * — the scan is **partial-tolerant by design**, but the truncation is now
+ * SIGNALLED rather than silent so a roster renderer can flag it.
+ *
+ * T0.1 (#748): this legacy shape is the `costProfile: 'local'` path —
+ * byte-identical row data to pre-#748 behavior. The cloud profile uses
+ * {@link scanEnsembleSessionsCloud}.
  */
-async function scanEnsembleSessions(client, ensemble, log = () => { }) {
+async function scanEnsembleSessionsWithStatus(client, ensemble, log = () => { }) {
     const sessions = [];
+    let truncated = false;
+    let scanned = 0;
     try {
-        for await (const workflow of (0, visibility_deadline_1.iterateWithDeadline)(client.workflow.list({ query: SESSION_LIST_QUERY }), visibility_deadline_1.VISIBILITY_DEADLINES_MS.scanEnsembleSessions, 'scanEnsembleSessions')) {
+        for await (const workflow of (0, visibility_deadline_1.iterateWithDeadline)(client.workflow.list({ query: exports.SESSION_LIST_QUERY }), visibility_deadline_1.VISIBILITY_DEADLINES_MS.scanEnsembleSessions, 'scanEnsembleSessions')) {
+            scanned++;
             try {
                 const handle = client.workflow.getHandle(workflow.workflowId);
                 // Issue #433 — bound the metadata + part queries so a single wedged
@@ -119,11 +331,27 @@ async function scanEnsembleSessions(client, ensemble, log = () => { }) {
     }
     catch (err) {
         if ((0, visibility_deadline_1.isVisibilityTimeout)(err)) {
+            truncated = true;
             log(`scanEnsembleSessions: ${err.message} — returning partial (${sessions.length} sessions)`);
         }
         else {
             throw err;
         }
     }
-    return sessions;
+    return { sessions, truncated, scanned };
+}
+/**
+ * Scan all running session workflows in an ensemble — array facade over
+ * {@link scanEnsembleSessionsWithStatus}.
+ *
+ * Returns just the session rows; the truncation/scan-status fields are
+ * dropped. This is the byte-identical shape the maestro refresh activity,
+ * the #785 upgrade-snapshot, and the other roster consumers already depend
+ * on — keeping it a thin delegate means the truncation-signalling work
+ * (#845) does NOT ripple through those call sites. Callers that need to
+ * know whether the scan was complete (the `ensemble` tool) call the rich
+ * sibling directly.
+ */
+async function scanEnsembleSessions(client, ensemble, log = () => { }) {
+    return (await scanEnsembleSessionsWithStatus(client, ensemble, log)).sessions;
 }

package/dist/activities/schedule-fire.js

@@ -4,13 +4,16 @@ exports.createScheduleActivities = createScheduleActivities;
 const croner_1 = require("croner");
 const config_1 = require("../config");
 const resolve_1 = require("./resolve");
+const action_counters_1 = require("../utils/action-counters");
 const visibility_deadline_1 = require("../utils/visibility-deadline");
 /**
  * Create the schedule-fire activity bound to a Temporal client.
  * The returned object is registered with the worker as activities.
  */
 function createScheduleActivities(client) {
-    return {
+    // #753 — attribute every Temporal call made by these activities (however
+    // deep, e.g. resolveSession → queryHandleWithTimeout) to the scheduler.
+    return (0, action_counters_1.tagActionSource)('schedule', {
         async computeNextCronFire(input) {
             const job = new croner_1.Cron(input.cronExpression, { timezone: input.timezone || 'UTC' });
             const next = job.nextRun();
@@ -104,7 +107,7 @@ function createScheduleActivities(client) {
                 return { success: false, error: errorMsg };
             }
         },
-    };
+    });
 }
 /**
  * Notify the schedule creator (or conductor as fallback) that delivery failed.

package/dist/adapters/base.d.ts

@@ -217,6 +217,7 @@ export declare abstract class BaseAttachment {
      * whatever comes next.
      */
     private tickHeartbeat;
+    private tickHeartbeatInner;
     private schedulePhaseWatcher;
     /**
      * Single tick of the phase-watcher loop. Same orphan-resistance scaffolding as
@@ -227,6 +228,7 @@ export declare abstract class BaseAttachment {
      * restart.
      */
     private tickPhaseWatcher;
+    private tickPhaseWatcherInner;
     /**
      * Shared error-classification path for the heartbeat + phase-watcher ticks (#226).
      *

package/dist/adapters/base.js

@@ -7,6 +7,7 @@ exports._resetProcessLifecycleTelemetryForTest = _resetProcessLifecycleTelemetry
 exports._liveAdaptersForTest = _liveAdaptersForTest;
 const signals_1 = require("../workflows/signals");
 const terminal_error_1 = require("./terminal-error");
+const action_counters_1 = require("../utils/action-counters");
 const log = (...args) => console.error('[agent-tempo:adapter]', ...args);
 // ── Hypothesis A telemetry (#258 follow-up) ─────────────────────────────
 //
@@ -491,6 +492,10 @@ class BaseAttachment {
      * whatever comes next.
      */
     async tickHeartbeat() {
+        // #753 — liveness-lease signals are metered as their own source.
+        return (0, action_counters_1.withActionSource)('heartbeat', () => this.tickHeartbeatInner());
+    }
+    async tickHeartbeatInner() {
         try {
             if (this.stopped || this.terminalFired) {
                 this.logGuardTrip('heartbeat');
@@ -551,6 +556,10 @@ class BaseAttachment {
      * restart.
      */
     async tickPhaseWatcher() {
+        // #753 — relaxed-poll attachmentInfo queries are metered as their own source.
+        return (0, action_counters_1.withActionSource)('phase-watcher', () => this.tickPhaseWatcherInner());
+    }
+    async tickPhaseWatcherInner() {
         try {
             if (this.stopped || this.terminalFired) {
                 this.logGuardTrip('phase-watcher');

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

@@ -75,6 +75,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 mcp_bridge_1 = require("./mcp-bridge");
@@ -135,7 +136,11 @@ function truncateErr(err, max = 240) {
 }
 /** Default model id — verification addendum §1 (no date suffix on direct API). */
 const DEFAULT_MODEL = 'claude-opus-4-7';
-/** Idle poll cadence (ms). Matches Copilot bridge — short enough for snappy cue delivery, loose enough not to hammer Temporal. */
+/**
+ * Busy-wait cadence (ms) while an SDK 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;
 /** Workflow-register poll loop bounds. */
 const WORKFLOW_REGISTER_ATTEMPTS = 30;
@@ -223,6 +228,7 @@ class DirectApiAttachment 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 can
         // issue claimAttachment + heartbeat against it.
@@ -331,6 +337,10 @@ class DirectApiAttachment extends base_1.SdkAttachment {
             await this.mcp?.close().catch(() => { });
             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.
@@ -356,7 +366,9 @@ class DirectApiAttachment 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 the poll loop's Temporal calls under 'sdk-poller'.
+        await (0, action_counters_1.withActionSource)('sdk-poller', () => this.pollLoop(handle));
+        this.stopDoorbell();
         try {
             fs.unlinkSync(pidFile);
         }
@@ -381,6 +393,9 @@ class DirectApiAttachment extends base_1.SdkAttachment {
         // wedge the player indefinitely.
         let consecutiveFailures = 0;
         const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+        // #749: fresh poll loop (initial start OR reconnect) begins 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.
@@ -418,13 +433,20 @@ class DirectApiAttachment extends base_1.SdkAttachment {
             }
             catch (err) {
                 log(`pendingMessages query failed: ${err?.message ?? err}`);
-                await sleep(POLL_INTERVAL_MS);
+                // #749: grow on errors too — mirrors the interactive poller's shape
+                // (a wedged worker shouldn't be hammered 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 {
                 // Representative message for processingStart/End pairing; ack the