agent-tempo 1.7.0-beta.8 → 1.7.0-beta.9

package/CLAUDE.md

@@ -41,7 +41,8 @@ src/
 │   ├── sa-preflight.ts # search-attribute preflight — REQUIRED_SEARCH_ATTRIBUTES list (single source of truth), registerSearchAttribute, verifySearchAttributes, assertSearchAttributesOrExit
 │   ├── scenarios-command.ts # scenarios subcommand (dev mode only) — list/show shipped YAML scenario library (ADR 0014 §4.8)
 │   ├── startup.ts     # auto-provisioning bootstrap state machine (#289) — six-step idempotent sequence used by bare `agent-tempo` invocation
-│   └── upgrade-command.ts # upgrade subcommand — crash-proof; dynamic-imports Temporal only for active-session warning
+│   ├── upgrade-command.ts # upgrade subcommand — crash-proof; dynamic-imports Temporal only for active-session warning
+│   └── upgrade-to-2-command.ts # upgrade-to-2 cutover verb (#785) — crash-proof; dynamic-imports the phase-engine + Temporal inside try/catch; --yes/--dry-run/--force-drain
 ├── adapters/
 │   ├── README.md      # Adapter contract documentation
 │   ├── index.ts       # Adapter registry bootstrap + barrel exports (mock registered iff isDevMode())
@@ -53,7 +54,7 @@ src/
 │   ├── opencode/      # OpenCodeAttachment — headless multi-provider adapter via SST OpenCode subprocess (#449)
 │   ├── pi/            # Headless Pi adapter — descriptor + spawn entry (Phase 3a). No BaseAttachment; the Pi extension singleton owns lifecycle (claim/heartbeat/tools/cue pump). `adapter.ts` is the process entry; `index.ts` is the registry descriptor.
 │   ├── mock/          # MockAttachment — dev-mode-only SDK adapter (ADR 0014 PR-2). prepack strips dist/adapters/mock from npm tarball.
-│   └── sdk/           # SDK-style adapter base (used by Copilot bridge and opencode)
+│   └── sdk/           # SDK-style adapter base (used by Copilot bridge and opencode). Key files: `idle-backoff.ts` (T0.2 IdleBackoff helper — base 2s, cap 30s/60s, reset-on-delivery), `doorbell-client.ts` (T1.1 DoorbellClient + WakeableSleep — reconnecting SSE consumer for `/doorbell`; ding→reset()+wake(); connected ceiling 60s; disconnected falls back to 30s T0.2 floor)
 ├── client/
 │   ├── interface.ts   # TempoClient TypeScript interface and related types
 │   └── index.ts       # TempoClient factory implementation and barrel re-exports
@@ -85,12 +86,17 @@ src/
 │   ├── inner-loop.ts  # InnerLoopRegistry + InnerSubscription — daemon-local fine-tail sink (3c MD-F); drop-oldest bounded queue (256) + `compacted{dropped,sinceTs}` marker; NOT on Temporal/bus, ephemeral no-replay
 │   ├── ingest-registry.ts # IngestTokenRegistry — per-player ingest token (mint-on-pi-spawn / revoke-on-destroy / revokeAll-on-shutdown); timing-safe validation; cross-player-spoof guard
 │   ├── inner-loop-routes.ts # 3 inner-loop HTTP routes: POST /inner/ingest + GET /inner/presence (INGRESS, loopback + X-Ingest-Token, uniform 403); GET /inner (EGRESS operator SSE, requireTier(3))
+│   ├── doorbell.ts    # DoorbellRegistry — in-process Map<"{ensemble}:{playerId}", Set<waiter>>; ring-with-no-listener drops on floor; level-triggered coalescing; never throws (T1.1 PR-1, #776)
+│   ├── doorbell-routes.ts # GET /doorbell/:ensemble/:playerId SSE route — content-free ding events; loopback + X-Ingest-Token auth (same ingress model as inner-loop); NO event IDs / Last-Event-ID / replay by design; :ka keepalive every 15s (T1.1 PR-1, #776)
 │   ├── auth.ts        # 3e MD-E RBAC: two-token model (readToken T1 / adminToken T1+T2+T3 env-var-only); loadRbacTokens; requireTier(tier, input) → TierGuardResult; tierForToken; loadReadToken (env>config>legacy httpToken>auto-gen); loadAdminToken (env-only); TLS/legacy startup warnings in startHttpServer
 │   ├── cors.ts / responses.ts / event-id.ts / port-file.ts / index.ts
 ├── reconcile/
 │   └── orphans.ts     # Shared orphan-query helper (daemon reconcile-on-boot + CLI restore)
+├── upgrade/           # 1.x→2.0 cutover (#785)
+│   ├── snapshot-v1.ts # VERSIONED upgrade-snapshot-v1.json schema + atomic persistence — the cross-release interface #786 imports (Temporal-free)
+│   └── phase-engine.ts # 6-phase resumable cutover engine (preflight→pause→drain→snapshot→destroy→done); snapshot strictly precedes destroy
 ├── ensemble/
-│   ├── schema.ts / loader.ts / saver.ts   # Lineup type definitions, load, save
+│   ├── schema.ts / loader.ts / saver.ts   # Lineup type definitions, load, save (saver exports buildLineupFromCluster — shared by save_lineup + #785 snapshot)
 │   └── agent-types.ts # Agent type discovery, resolution, and lineup resolution
 ├── tools/             # One file per MCP tool — see docs/tools.md for full reference
 │   ├── ensemble.ts / cue.ts / recruit.ts / report.ts / broadcast.ts / recall.ts / listen.ts
@@ -108,7 +114,7 @@ src/
 │   └── descriptor.ts  # Transport-neutral tool descriptor (TempoToolDescriptor) + renderToMcp; per-tool `build*Tool` factories live in each tool file (MD-B, Phase 1)
 ├── pi/                # Pi-native integration — a Pi session as a first-class player over the Temporal core
 │   ├── extension.ts   # `export default function(pi)` — interactive runtime entry. Holds the MODULE-SCOPE singleton `Map<workflowId, PiPlayerRuntime>` that survives Pi's per-switch instance rebuild (rebind, not re-claim); full tool surface via renderToPi; Option-C reason-discriminated teardown
-│   ├── phase-driver.ts / workflow-client.ts / cue-pump.ts   # Pi-event→attachment-phase machine, thin client-side WorkflowClient (lease/heartbeat 90/30, handle getter), cue pump (D10 steer/followUp; one 1s loop with a second pendingReset intake — S3 merge, D14 clean-wipe + /tempo-reset operator notice)
+│   ├── phase-driver.ts / workflow-client.ts / cue-pump.ts   # Pi-event→attachment-phase machine, thin client-side WorkflowClient (lease/heartbeat 90/30, handle getter), cue pump (D10 steer/followUp; IdleBackoff loop 1s base→30s disconnected/60s connected ceiling + ding wake via DoorbellClient; pendingIntake combined query T0.3; S3 merge, D14 clean-wipe + /tempo-reset operator notice)
 │   ├── lazy-proxy.ts  # D11 createLazyProxy — Client/WorkflowHandle proxy resolving the live module-scope target per call (survives instance rebuild)
 │   ├── headless.ts    # Headless Pi runtime (Phase 3a) — boots Pi's createAgentSession with inline extension; `noExtensions: true` closes S2 exec-tool bypass; SIGTERM/SIGINT shutdown → reliable detach + dispose
 │   ├── render-tools.ts # renderToPi — registers the shared tool descriptors on Pi's ExtensionAPI (TypeBox params via the converter)
@@ -208,14 +214,15 @@ daemon worker notes, `npx ts-node` dev runner).
 - **Claude API adapter** (`agent: 'claude-api'`, #131): Headless adapter that drives sessions via the Anthropic Messages API (`@anthropic-ai/sdk`) — no terminal, no Claude Code CLI. Requires `ANTHROPIC_API_KEY` env var and the `@anthropic-ai/sdk` optional dependency. Default model `claude-opus-4-7` (overridable via `model` recruit arg or `CLAUDE_TEMPO_API_MODEL` env). Claude-API players have access to agent-tempo MCP tools (cue, report, recall, ensemble, …) but not file-edit/shell/web tools. See `src/adapters/claude-api/`.
 - **OpenCode adapter** (`agent: 'opencode'`, #449): Headless multi-provider adapter that drives sessions via [SST OpenCode](https://opencode.ai) as a managed subprocess — supports Anthropic, OpenAI, Bedrock, Vertex, Ollama, and ~70 other providers via OpenCode's `provider/model` selector. Requires OpenCode CLI (`npm install -g opencode-ai`) and the `@opencode-ai/sdk` optional dependency. Recruit with `model: 'provider/name'` (e.g. `'anthropic/claude-opus-4-7'`). Tool bridging is MCP-native — OpenCode spawns `dist/server.js` as its own stdio MCP child. Session state is persisted server-side by OpenCode; the adapter stashes the session id on workflow metadata for reconnect across `opencode serve` restarts. See `src/adapters/opencode/`.
 - **Claude Code headless adapter** (`agent: 'claude-code-headless'`, #520): Headless adapter that drives sessions via the official `claude` CLI as a per-turn `claude -p --output-format stream-json` subprocess. The whole point: turns bill against the host's existing Claude Code subscription extra-usage credits (Pro / Max plans) rather than a Console workspace API key — the only ToS-clean way for a third-party tool to tap that pool. Requires the `claude` binary on PATH AND a logged-in Claude Code session (`claude auth login`); recruit pre-flight rejects with an actionable error otherwise. Tool surface is the union of full Claude Code built-ins (Bash / Read / Write / Edit / Glob / Grep / WebSearch / WebFetch) and the agent-tempo MCP surface — registered via inline `--mcp-config` so `claude` spawns `dist/server.js` as its own MCP child (no in-process bridge). Recruit knobs: `permissionMode` (default `'acceptEdits'`) or `dangerouslySkipPermissions: true` (mutually exclusive). Sessions resume across restart via the existing `sessionId` metadata field — the same UUID is shared with the interactive `claude-code` adapter (per-cwd JSONL is per-cwd, not per-adapter). See `src/adapters/claude-code-headless/` and `examples/ensembles/tempo-headless-jam.yaml`.
-- **Pi adapter** (`agent: 'pi'`, #632 / #666): Two modes. **(1) Interactive conductor** (#666): `agent-tempo up --agent pi --ensemble <name>` launches `pi` in a real terminal with the agent-tempo extension auto-loaded (`pi -e dist/pi/extension.js`); the Pi session self-bootstraps its Temporal workflow and attaches as a conductor/player — no separate recruiter step. From the TUI, `/recruit-conductor` relaunches the active ensemble's conductor — set `conductor.agent: pi` in that ensemble's lineup to make it a Pi conductor. Requires `@earendil-works/pi-coding-agent` on Node ≥ 22.19. Recommended: `ANTHROPIC_API_KEY` (without it the session falls back to Pi's own auth/default model). The `AGENT_TEMPO_*` env is auto-wired by `up`; power users can invoke the extension directly with `pi -e dist/pi/extension.js`. `--model provider/model` selector (e.g. `'github-copilot/gpt-4o'`) is a fast-follow. **(2) Headless player** (Phase 3a): `recruit` with `agent: 'pi'` — no terminal, no BaseAttachment; runs `createAgentSession` with an in-memory `SessionManager`; the module-scope singleton owns claim/heartbeat/tools/cue pump (MD-D). Pi players run the full tool surface — incl. shell — with no permission layer, like the other adapters (the former `toolAccess`/`guardrailPolicy` knobs were removed). `noExtensions: true` stays: it blocks third-party disk/package extensions from loading into a recruited player (supply-chain hygiene). See `src/adapters/pi/` and `src/pi/headless.ts`.
+- **Pi adapter** (`agent: 'pi'`, #632 / #666): Two modes. **(1) Interactive conductor** (#666): `agent-tempo up --agent pi --ensemble <name>` launches `pi` in a real terminal with the agent-tempo extension auto-loaded (`pi -e dist/pi/extension.js`); the Pi session self-bootstraps its Temporal workflow and attaches as a conductor/player — no separate recruiter step. From the TUI, `/recruit-conductor` relaunches the active ensemble's conductor — set `conductor.agent: pi` in that ensemble's lineup to make it a Pi conductor. Requires `@earendil-works/pi-coding-agent` on Node ≥ 22.19. Recommended: `ANTHROPIC_API_KEY` (without it the session falls back to Pi's own auth/default model). The `AGENT_TEMPO_*` env is auto-wired by `up`; power users can invoke the extension directly with `pi -e dist/pi/extension.js`. The interactive `--model provider/model` selector (e.g. `'github-copilot/gpt-4o'`) remains a fast-follow. **(2) Headless player** (Phase 3a): `recruit` with `agent: 'pi'` — no terminal, no BaseAttachment; runs `createAgentSession` with an in-memory `SessionManager`; the module-scope singleton owns claim/heartbeat/tools/cue pump (MD-D). Per-player `model: 'provider/model'` on recruit (#734): built-in providers AND custom `~/.pi/agent/models.json` providers (lmstudio, ollama, vllm, …) both resolve, falling back to `AGENT_TEMPO_PI_MODEL` — enables hybrid ensembles (frontier-model conductor, local-model workers). Pi players run the full tool surface — incl. shell — with no permission layer, like the other adapters (the former `toolAccess`/`guardrailPolicy` knobs were removed). `noExtensions: true` stays: it blocks third-party disk/package extensions from loading into a recruited player (supply-chain hygiene). See `src/adapters/pi/` and `src/pi/headless.ts`.
 - **Mission-control / Command-center** (3f, #700 P2): An interactive Pi TUI that is both a live ensemble board + operator controller and an LLM planner. Board side: HTTP-drives the daemon — coarse ensemble view via `/v1/events/:ensemble` SSE + fine per-player tail via `/inner` (T3); operator controls (cue/pause/play/restart/destroy) POST to the daemon write surface using `AGENT_TEMPO_HTTP_ADMIN_TOKEN`. Planner side: registers LLM tools (`ask` / `handoff` / `cue` / `recruit` / `observe_board`) via `MissionControlActions` — HTTP-backed, distinct from the player extension's `renderToPi` MCP surface. **Never claims attachment or registers as a player** — invisible to the ensemble. Launch with **`agent-tempo command-center [ensemble]`** (aliases: `cc`, `board`) — sets `AGENT_TEMPO_MISSION_CONTROL=1`. **Loopback auto-token** (#736): a local (loopback) daemon grants full trust without `AGENT_TEMPO_HTTP_ADMIN_TOKEN`; only a remote daemon requires explicit token configuration. **Role-gated and mutually exclusive** with the player extension (`resolvePiRole` discriminator: explicit `AGENT_TEMPO_PI_ROLE` → `PLAYER_NAME` present → `AGENT_TEMPO_MISSION_CONTROL` → `none`): a bare `pi` keeps both extensions dormant (plain coding session); a player session (`up --agent pi` / `recruit`) keeps the board dormant. Power users invoking `pi -e dist/pi/extension.js` directly without `PLAYER_NAME` also resolve to `none` (dormant) — set `AGENT_TEMPO_PI_ROLE=player` to force player mode. See `src/pi/mission-control/`.
 - **Command-center planner** (#700 P2): An inbox-less interactive Pi session (the operator's planning seat) that routes questions to players via correlated `cue` tags (`[Q <questionId>]`). Players answer with the `respond` MCP tool, which parks the answer on the per-ensemble maestro Q&A mailbox (TTL 1h, 20-slot cap). The planner is woken by an `answer` SSE event when the answer lands (`docs/SSE-PROTOCOL.md` §6). `/handoff` cues hand active work to a conductor (a registered player with a Temporal inbox). See `docs/concepts.md` for the Q&A mechanics.
 - **Mock adapter** (`agent: 'mock'`, dev mode only): Four modes: `echo` (echoes input), `scripted` (replays YAML scenario rules), `silent` (drains messages without replying — heartbeat-stale validation), `chaos` (probabilistic fail/crash injection via seeded PRNG). Only registered when `isDevMode()` is true; stripped from the npm tarball by `prepack`. See `src/adapters/mock/`.
 - **Saveable state** (#334, ADR 0011): Per-player curated state slots — the player itself decides what context survives a restart. Three MCP tools: `save_state` (owner-only write, max 4 slots × 32 KiB), `fetch_state` (read self or peer; audit identity recorded on each entry's `savedBy`), `clear_state` (owner-only). `restart` accepts `loadFromState: true | 'someKey'` to seed the new session from a saved-state slot instead of (or, with `transcript: 'replay'`, alongside) transcript replay. Saved-state delivery uses `from: 'self-restart'` as a stable system identity. Empty-slot fallback: graceful — falls through to transcript replay with a log line. See [docs/design/334-player-saveable-state.md](docs/design/334-player-saveable-state.md).
+- **`upgrade-to-2` cutover** (#785, ratified migration protocol A2 — `docs/design/v2-scoping.md` §A.3): The 1.x → 2.0 migration verb. A 2.0 worker can never replay a 1.x-recorded run, so 2.0 ships behind a clean cutover: `agent-tempo upgrade-to-2` runs a six-phase protocol — **preflight** (enumerate ensembles; refuse if any connected daemon is below the 1.7.x version floor — `hostProfile.version` on the global maestro; covers same-host-stale-daemon, #801) → **pause** (brake the work *sources* — maestro + scheduler — leaving sessions live to drain) → **drain** (poll outboxes ≤60s; `--force-drain` records stragglers instead of stopping) → **snapshot** (freeze session dispatch, then capture continuity to `~/.agent-tempo/upgrade-snapshot-v1.json`) → **destroy** (idempotent teardown: peers → scheduler+maestro → conductor) → **done**. **Load-bearing invariant: SNAPSHOT strictly precedes DESTROY** (`destroyAndFinish` takes a persisted snapshot as a required arg); a crash leaves either everything intact or a durable snapshot + partial teardown, never destruction without capture. Resumable via the snapshot's phase stamp. The snapshot captures schedules (durable intent), #334 state slots (continuity), `sessionId` (resume pointer), the non-default recruit `model` (ad-hoc claude-api/opencode/pi continuity), and undelivered cues (operator review, NOT redelivered); coat-check is dropped (TTL-transient); gates/stages/worktrees are intentionally not captured (transient coordination state; worktree continuity rides `workDir`). **`src/upgrade/snapshot-v1.ts` is the cross-release interface the 2.0-side `up --from-upgrade` (#786) imports** — it is VERSIONED and deliberately Temporal-free; additive optional fields do NOT bump the version, only removed/renamed/retyped required fields do (with a 2.0 reader migration). CLI flags: `--yes` (skip confirm), `--dry-run` (print snapshot + destroy list, exit before pausing), `--force-drain`. The verb is crash-proof (`src/cli/upgrade-to-2-command.ts` dynamic-imports the Temporal-touching engine). See `src/upgrade/` and issue #785.
 - **Coat-check** (#318, ADR 0008): Per-ensemble transient content store on Maestro state. Solves the 100 KB cue body cap — stash a large artifact with `coat_check_put` (returns a ticket id) and attach the ticket to a `cue` via `attachmentTicket`; the recipient calls `coat_check_get` to pull the full body. Four MCP tools: `coat_check_put` (any player; max 32 KiB per entry, 20 slots per ensemble, TTL 7d default), `coat_check_get` (any player; bumps fetch-audit counters), `coat_check_list` (read-only survey; headers only, content omitted), `coat_check_evict` (owner or conductor). Saturation rejects with `CoatCheckSlotsFull` (no LRU eviction). See `src/tools/coat-check-*.ts` and [docs/adr/0008-coat-check-pattern.md](docs/adr/0008-coat-check-pattern.md).
 - **Lineup examples**: Six pre-built ensemble YAML files in `examples/ensembles/` — `tempo-big-band`, `tempo-dev-team`, `tempo-review-squad`, `tempo-jam-session`, `tempo-mock-jam` (dev-mode all-mock ensemble), `tempo-headless-jam` (#520 — all-`claude-code-headless` subscription-billed ensemble). Load with `agent-tempo up --lineup <name>` or the `load_lineup` tool.
-- **GitHub App identity** (`agent-tempo[bot]`): When a player writes to GitHub — issue comments, PR creation/merge, commits, labels, check runs — **use `./scripts/ensemble-gh`** instead of `gh`. The wrapper mints a short-lived installation token so the action is attributed to `agent-tempo[bot]`, not to the human maintainer, making the AI authorship visible. Plain `gh` is still correct for read-only local dev (`gh pr view`, `gh repo clone`, `gh auth status`). Every bot-authored comment/PR body must include the AI attribution footer documented in [docs/github-app.md](docs/github-app.md).
+- **GitHub App identity** (`agent-tempo[bot]`): When a player writes to GitHub — issue comments, PR creation/merge, commits, labels, check runs — **use `./scripts/ensemble-gh`** instead of `gh`. The wrapper mints a short-lived installation token so the action is attributed to `agent-tempo[bot]`, not to the human maintainer, making the AI authorship visible. Plain `gh` is still correct for read-only local dev (`gh pr view`, `gh repo clone`, `gh auth status`). On Windows, invoke via `bash ./scripts/ensemble-gh` — bare PowerShell silently no-ops with no error (see #741). Every bot-authored comment/PR body must include the AI attribution footer documented in [docs/github-app.md](docs/github-app.md).
 
 See [docs/concepts.md](docs/concepts.md) for the full glossary (Adapter, Attachment phases, Restart, Detach/Destroy, Migrate, Broadcast, Recall, Schedule, Lineup, Quality Gate, Worktree, Stage, Hold/Release, Pause/Resume, Maestro, TempoClient, Command-center planner, and more).
 

package/dashboard/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-tempo-dashboard",
   "private": true,
-  "version": "1.7.0-beta.8",
+  "version": "1.7.0-beta.9",
   "type": "module",
   "description": "Web dashboard for agent-tempo. Bundled into the npm package; served by the daemon at /dashboard/*.",
   "scripts": {

package/dist/activities/maestro.d.ts

@@ -55,9 +55,54 @@ export interface FetchEnsembleChatResult {
     hasConductor: boolean;
     error?: string;
 }
+/** T0.1 (#748) — result of the V2 refresh (cloud-profile maestros). */
+export interface RefreshEnsembleStateV2Result {
+    players: MaestroPlayerInfo[];
+    /**
+     * Whether the daemon currently has any live SSE subscriber (TUI, web
+     * dashboard, mission-control board). Read in-process from the
+     * AggregateRunner — zero Temporal cost. The maestro workflow stretches
+     * its next refresh timer when nobody is watching. `true` when no
+     * presence source is wired (fail-open: never stretch by accident).
+     */
+    observersPresent: boolean;
+}
+/**
+ * T0.1 (#748) — daemon-side observer presence source. A mutable holder
+ * because worker/activity construction happens BEFORE the daemon's
+ * AggregateRunner exists; daemon.ts fills `current` in once the HTTP/SSE
+ * plane is up (same late-wiring pattern as IngestTokenRegistry).
+ */
+export interface ObserverPresenceSource {
+    current: (() => number) | null;
+}
+/** Options for {@link createMaestroActivities} (T0.1, #748). */
+export interface MaestroActivityOptions {
+    /** Daemon cost profile — drives the V2 scan strategy. Default 'local'. */
+    costProfile?: 'local' | 'cloud';
+    /** Late-wired SSE subscriber count source (see {@link ObserverPresenceSource}). */
+    observerPresence?: ObserverPresenceSource;
+}
 /** Activity interface — used by proxyActivities in the Maestro workflow. */
 export interface MaestroActivities {
+    /**
+     * Legacy V1 refresh — the `costProfile: 'local'` path AND the replay
+     * path for every maestro started before #748.
+     * TODO(next major, #748): remove once the minimum deployment age
+     * exceeds the longest-lived pre-#748 maestro history (they replay V1);
+     * remove together with the V1 branch in workflows/maestro.ts.
+     */
     refreshEnsembleState(ensemble: string): Promise<MaestroPlayerInfo[]>;
+    /**
+     * T0.1 (#748) — additive V2: called only by maestros started with
+     * `costProfile: 'cloud'` in their input. SA/memo-based ensemble-scoped
+     * scan + in-process observer presence for workflow-side cadence
+     * stretching. V1 stays for in-flight pre-#748 maestros (replay safety)
+     * and the local profile.
+     */
+    refreshEnsembleStateV2(input: {
+        ensemble: string;
+    }): Promise<RefreshEnsembleStateV2Result>;
     fetchConductorHistory(input: FetchConductorHistoryInput): Promise<FetchConductorHistoryResult>;
     relayCommandToConductor(input: RelayCommandInput): Promise<RelayCommandResult>;
     discoverEnsembles(): Promise<string[]>;
@@ -69,4 +114,4 @@ export interface MaestroActivities {
  * Create the Maestro activity implementations bound to a Temporal client.
  * Registered with the shared worker.
  */
-export declare function createMaestroActivities(client: Client): MaestroActivities;
+export declare function createMaestroActivities(client: Client, opts?: MaestroActivityOptions): MaestroActivities;

package/dist/activities/maestro.js

@@ -5,40 +5,89 @@ const activity_1 = require("@temporalio/activity");
 const config_1 = require("../config");
 const types_1 = require("../types");
 const resolve_1 = require("./resolve");
+const action_counters_1 = require("../utils/action-counters");
 const visibility_deadline_1 = require("../utils/visibility-deadline");
 const log = (...args) => console.error('[agent-tempo:maestro]', ...args);
 /**
  * Create the Maestro activity implementations bound to a Temporal client.
  * Registered with the shared worker.
  */
-function createMaestroActivities(client) {
-    return {
+function createMaestroActivities(client, opts = {}) {
+    /** Shared row-mapper for both refresh shapes. */
+    const toPlayerInfo = (ensemble) => (s) => ({
+        playerId: s.playerId,
+        ensemble,
+        part: s.part,
+        hostname: s.hostname,
+        workDir: s.workDir,
+        gitRoot: s.gitRoot,
+        gitBranch: s.gitBranch,
+        isConductor: s.isConductor,
+        agentType: s.agentType,
+        playerType: s.playerType,
+        phase: s.phase,
+        // #399 W1 — forward the activity-counter pair so the maestro's
+        // tempo bucket can diff across refreshes.
+        activityCount: s.activityCount,
+        lastActivityAt: s.lastActivityAt,
+    });
+    // #753 — attribute every Temporal call made by these activities (however
+    // deep, e.g. scanEnsembleSessions → queryHandleWithTimeout) to the maestro.
+    //
+    // T0.6/#774 (architect verification prerequisite) — the tag is SPLIT by
+    // the CALLING workflow, resolved per invocation from the activity
+    // context: the same factory serves the per-ensemble maestro (chat-gated)
+    // and the global maestro (never gated — the prime unwatched-residual
+    // suspect), and the meter must tell them apart. Anything else (incl.
+    // direct test invocation outside an activity context) lands in
+    // 'maestro-session'. NOTE: bySource report keys for the maestro line
+    // changed from 'maestro' to these three.
+    const maestroSource = () => {
+        try {
+            switch ((0, activity_1.activityInfo)().workflowType) {
+                case 'agentMaestroWorkflow': return 'maestro-ensemble';
+                case 'agentGlobalMaestroWorkflow': return 'maestro-global';
+                default: return 'maestro-session';
+            }
+        }
+        catch {
+            return 'maestro-session'; // outside an activity context (tests, direct calls)
+        }
+    };
+    return (0, action_counters_1.tagActionSource)(maestroSource, {
         async refreshEnsembleState(ensemble) {
             try {
                 const sessions = await (0, resolve_1.scanEnsembleSessions)(client, ensemble);
-                return sessions.map((s) => ({
-                    playerId: s.playerId,
-                    ensemble,
-                    part: s.part,
-                    hostname: s.hostname,
-                    workDir: s.workDir,
-                    gitRoot: s.gitRoot,
-                    gitBranch: s.gitBranch,
-                    isConductor: s.isConductor,
-                    agentType: s.agentType,
-                    playerType: s.playerType,
-                    phase: s.phase,
-                    // #399 W1 — forward the activity-counter pair so the maestro's
-                    // tempo bucket can diff across refreshes.
-                    activityCount: s.activityCount,
-                    lastActivityAt: s.lastActivityAt,
-                }));
+                return sessions.map(toPlayerInfo(ensemble));
             }
             catch (err) {
                 log('refreshEnsembleState failed:', err);
                 throw activity_1.ApplicationFailure.nonRetryable(`Failed to scan ensemble: ${err instanceof Error ? err.message : String(err)}`);
             }
         },
+        async refreshEnsembleStateV2(input) {
+            try {
+                // Honor the DAEMON's configured profile for the scan strategy: a
+                // cloud-input maestro on a daemon flipped back to 'local' degrades
+                // gracefully to the legacy scan (still on the stretched cadence
+                // until its next restart).
+                const sessions = opts.costProfile === 'cloud'
+                    ? await (0, resolve_1.scanEnsembleSessionsCloud)(client, input.ensemble, log)
+                    : await (0, resolve_1.scanEnsembleSessions)(client, input.ensemble);
+                const count = opts.observerPresence?.current?.();
+                return {
+                    players: sessions.map(toPlayerInfo(input.ensemble)),
+                    // Fail-open: unknown presence (no aggregate wired yet, e.g. during
+                    // daemon boot) counts as "observers present" — never stretch the
+                    // cadence on missing information.
+                    observersPresent: count === undefined ? true : count > 0,
+                };
+            }
+            catch (err) {
+                log('refreshEnsembleStateV2 failed:', err);
+                throw activity_1.ApplicationFailure.nonRetryable(`Failed to scan ensemble: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        },
         async fetchConductorHistory(input) {
             try {
                 const wfId = (0, config_1.conductorWorkflowId)(input.ensemble);
@@ -250,5 +299,5 @@ function createMaestroActivities(client) {
                 };
             }
         },
-    };
+    });
 }

package/dist/activities/outbox.d.ts

@@ -218,4 +218,17 @@ export interface OutboxActivities {
  * claim — phase is legitimately live) → never skipped. Pure + exported for tests.
  */
 export declare function shouldSkipDuplicateSpawn(attachmentId: string | undefined, phase: AttachmentPhase): boolean;
-export declare function createOutboxActivities(client: Client, config: Config, ingestTokens?: IngestTokenRegistry): OutboxActivities;
+/**
+ * T1.1 PR-1 — late-wired doorbell sink (the ObserverPresenceSource pattern:
+ * activity construction happens before the HTTP plane exists, so the daemon
+ * fills `current` at boot). A worker process that is not the daemon keeps
+ * `current: null` — ring() is a no-op and fallback polling covers it (§2.1).
+ * Defined here (not in src/http) so activities never import the HTTP plane.
+ */
+export interface DoorbellSink {
+    current: {
+        ring(ensemble: string, playerId: string): void;
+        closePlayer(ensemble: string, playerId: string): void;
+    } | null;
+}
+export declare function createOutboxActivities(client: Client, config: Config, ingestTokens?: IngestTokenRegistry, doorbells?: DoorbellSink): OutboxActivities;

package/dist/activities/outbox.js

@@ -46,6 +46,8 @@ const git_info_1 = require("../git-info");
 const spawn_1 = require("../spawn");
 const config_2 = require("../config");
 const resolve_1 = require("./resolve");
+const action_counters_1 = require("../utils/action-counters");
+const search_attributes_1 = require("../utils/search-attributes");
 const agent_types_1 = require("../ensemble/agent-types");
 const default_part_1 = require("../utils/default-part");
 const adapters_1 = require("../adapters");
@@ -156,8 +158,24 @@ function shouldSkipDuplicateSpawn(attachmentId, phase) {
         return false; // restart/migrate handoff — must spawn
     return phase === 'attached' || phase === 'processing' || phase === 'awaiting';
 }
-function createOutboxActivities(client, config, ingestTokens) {
-    return {
+/**
+ * Ring the doorbell sink, swallowing EVERYTHING — a ring must never fail or
+ * retry the delivery activity it follows (t11 §1: doorbell loss must be
+ * indistinguishable from doorbell-never-sent).
+ */
+function ringDoorbell(doorbells, ensemble, playerId) {
+    try {
+        doorbells?.current?.ring(ensemble, playerId);
+    }
+    catch {
+        /* never propagate — §1 */
+    }
+}
+function createOutboxActivities(client, config, ingestTokens, doorbells) {
+    // #753 — attribute every Temporal call made by these activities (however
+    // deep, e.g. deliverCue → resolveSession → queryHandleWithTimeout) to the
+    // outbox dispatch plane.
+    return (0, action_counters_1.tagActionSource)('outbox', {
         async deliverCue(input) {
             const { ensemble, fromPlayerId, targetPlayerId, message, broadcastId, attachmentTicket } = input;
             try {
@@ -174,6 +192,10 @@ function createOutboxActivities(client, config, ingestTokens) {
                     ...(broadcastId !== undefined ? { broadcastId } : {}),
                     ...(attachmentTicket !== undefined ? { attachmentTicket } : {}),
                 });
+                // T1.1 — the signal above has landed durably in history; ring the
+                // doorbell so a connected adapter polls now instead of at its
+                // backoff ceiling. Fire-and-forget: never fails this activity.
+                ringDoorbell(doorbells, ensemble, targetPlayerId);
                 return { success: true };
             }
             catch (err) {
@@ -305,12 +327,19 @@ function createOutboxActivities(client, config, ingestTokens) {
                     taskQueue,
                     args: [sessionInput],
                     workflowIdConflictPolicy: client_1.WorkflowIdConflictPolicy.USE_EXISTING,
+                    // T0.5 (#747) — read-only fields ride the MEMO, not search
+                    // attributes (fresh namespaces register only the 5 filter SAs).
                     searchAttributes: {
-                        ...(gitRoot ? { AgentTempoGitRoot: [gitRoot] } : {}),
                         AgentTempoHostname: [os.hostname()],
                         AgentTempoEnsemble: [ensemble],
                         AgentTempoPlayerId: [targetName],
                     },
+                    memo: {
+                        ...(gitRoot ? { [search_attributes_1.MEMO_KEYS.gitRoot]: gitRoot } : {}),
+                        ...(agentDefinition ? { [search_attributes_1.MEMO_KEYS.playerType]: agentDefinition } : {}),
+                        [search_attributes_1.MEMO_KEYS.isConductor]: isConductor,
+                        [search_attributes_1.MEMO_KEYS.part]: sessionInput.autoSummary,
+                    },
                 });
                 log(`Pre-created workflow ${workflowId} for recruit "${targetName}" (sessionId=${sessionId}, held=${!!held})`);
                 return { success: true, sessionId };
@@ -357,6 +386,20 @@ function createOutboxActivities(client, config, ingestTokens) {
                 }
             }
             try {
+                // T1.1 PR-1 — mint a per-player ingest token for every SDK-family
+                // spawn (was Pi-only since 3c Tier-2). The token authenticates the
+                // adapter's loopback HTTP calls: `POST /inner/ingest` (Pi fine-tail)
+                // and `GET /doorbell/:e/:p` (PR-2's DoorbellClient, all SDK
+                // adapters). Single-token-per-workflowId (mint REPLACES) means a
+                // restart re-mints and naturally revokes the stale token. Injected
+                // into the subprocess env as AGENT_TEMPO_INGEST_TOKEN. Interactive
+                // terminal spawns are deliberately excluded — no doorbell client
+                // exists for them (PR-2's consumers are SdkAttachment + the Pi
+                // runtime); minting extends trivially if that ever changes.
+                const ingestToken = agent === 'mock' || agent === 'copilot' || agent === 'claude-api' ||
+                    agent === 'opencode' || agent === 'claude-code-headless' || agent === 'pi'
+                    ? ingestTokens?.mint((0, config_1.sessionWorkflowId)(ensemble, targetName))
+                    : undefined;
                 if (agent === 'mock') {
                     // ADR 0014 PR-2 — mock adapter spawns headless. No terminal,
                     // no Claude binary, no MCP server child. Talks to Temporal
@@ -377,6 +420,7 @@ function createOutboxActivities(client, config, ingestTokens) {
                         attachmentId,
                         attachmentRunId,
                         adapterId,
+                        ingestToken,
                     });
                     log(`Spawned mock adapter (pid ${pid}) in ${workDir} as "${targetName}" (mode=${mockMode ?? 'echo'}${attachmentId ? `, attachmentId=${attachmentId}` : ''})`);
                 }
@@ -398,6 +442,7 @@ function createOutboxActivities(client, config, ingestTokens) {
                         attachmentId,
                         attachmentRunId,
                         adapterId,
+                        ingestToken,
                     });
                     log(`Spawned copilot-bridge (pid ${pid}) in ${workDir} as "${targetName}"${attachmentId ? ` (attachmentId=${attachmentId})` : ''}`);
                 }
@@ -424,6 +469,7 @@ function createOutboxActivities(client, config, ingestTokens) {
                         attachmentId,
                         attachmentRunId,
                         adapterId,
+                        ingestToken,
                     });
                     log(`Spawned claude-api adapter (pid ${pid}) in ${workDir} as "${targetName}"${model ? ` (model=${model})` : ''}${attachmentId ? ` (attachmentId=${attachmentId})` : ''}`);
                 }
@@ -452,6 +498,7 @@ function createOutboxActivities(client, config, ingestTokens) {
                         attachmentId,
                         attachmentRunId,
                         adapterId,
+                        ingestToken,
                     });
                     log(`Spawned opencode adapter (pid ${pid}) in ${workDir} as "${targetName}"${model ? ` (model=${model})` : ''}${attachmentId ? ` (attachmentId=${attachmentId})` : ''}`);
                 }
@@ -481,6 +528,7 @@ function createOutboxActivities(client, config, ingestTokens) {
                         attachmentId,
                         attachmentRunId,
                         adapterId,
+                        ingestToken,
                     });
                     log(`Spawned claude-code-headless adapter (pid ${pid}) in ${workDir} as "${targetName}"${permissionMode ? ` (permissionMode=${permissionMode})` : ''}${dangerouslySkipPermissions ? ' (dangerouslySkipPermissions=true)' : ''}${attachmentId ? ` (attachmentId=${attachmentId})` : ''}`);
                 }
@@ -492,12 +540,6 @@ function createOutboxActivities(client, config, ingestTokens) {
                     if (allowedTools && allowedTools.length > 0) {
                         log(`Warning: allowedTools [${allowedTools.join(', ')}] specified for pi agent "${targetName}" — Pi players run the full tool surface, skipping allowedTools`);
                     }
-                    // 3c Tier-2 — mint a per-player ingest token scoped to this player's
-                    // session workflowId so the headless Pi subprocess can authenticate its
-                    // `POST /inner/ingest` frames. Single-token-per-workflowId (mint
-                    // REPLACES) means a restart re-mints and naturally revokes the stale
-                    // token. Injected into the subprocess env as AGENT_TEMPO_INGEST_TOKEN.
-                    const ingestToken = ingestTokens?.mint((0, config_1.sessionWorkflowId)(ensemble, targetName));
                     const { pid } = (0, spawn_1.spawnPiHeadless)({
                         name: targetName,
                         ensemble,
@@ -680,6 +722,12 @@ function createOutboxActivities(client, config, ingestTokens) {
                 // revokeIngestToken(workflowId) on detach — deferred; residual surface
                 // negligible (dead holder + loopback-only + single-token replacement).
                 ingestTokens?.revoke((0, config_1.sessionWorkflowId)(ensemble, targetPlayerId));
+                // T1.1 — end the player's doorbell streams too (the registry-side
+                // lifecycle mirror of the token revoke; swallow-everything wrapper).
+                try {
+                    doorbells?.current?.closePlayer(ensemble, targetPlayerId);
+                }
+                catch { /* never propagate */ }
                 if (notifyConductor) {
                     try {
                         const condId = (0, config_1.conductorWorkflowId)(ensemble);
@@ -722,6 +770,9 @@ function createOutboxActivities(client, config, ingestTokens) {
                     ...(reason !== undefined ? { reason } : {}),
                     ...(requestedBy !== undefined ? { requestedBy } : {}),
                 });
+                // T1.1 — ring so a stretched pump's next tickReset looks at
+                // ding-latency, not its ceiling. D14 semantics untouched (§2.1).
+                ringDoorbell(doorbells, ensemble, targetPlayerId);
                 log(`Reset queued for "${targetPlayerId}"${reason ? ` (reason: ${reason})` : ''}`);
                 return { success: true };
             }
@@ -971,5 +1022,5 @@ function createOutboxActivities(client, config, ingestTokens) {
         async hardTerminateAttachment(input) {
             return (0, hard_terminate_1.hardTerminateAttachment)(input);
         },
-    };
+    });
 }

package/dist/activities/resolve.d.ts

@@ -1,5 +1,8 @@
 import { Client, WorkflowHandle } from '@temporalio/client';
 import { AttachmentPhase } from '../types';
+/** 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,6 +11,13 @@ import { AttachmentPhase } from '../types';
  *
  * Shared by activity files (outbox, schedule-fire) and the tools layer.
  *
+ * 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.
+ *
  * **Deadline (#336/#529):** the visibility iterator is bounded by
  * `VISIBILITY_DEADLINES_MS.resolveSession` (default 10s). On timeout,
  * throws `VisibilityIteratorTimeoutError` rather than returning `null`
@@ -49,6 +59,28 @@ export interface EnsembleSessionInfo {
      */
     lastActivityAt?: string;
 }
+/**
+ * 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[]>;
 /**
  * Scan all running session workflows in an ensemble.
  * Returns metadata + part for each session. Shared by the ensemble MCP tool
@@ -60,5 +92,9 @@ export interface EnsembleSessionInfo {
  * 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.
+ *
+ * T0.1 (#748): this legacy shape is the `costProfile: 'local'` path —
+ * byte-identical to pre-#748 behavior. The cloud profile uses
+ * {@link scanEnsembleSessionsCloud}.
  */
 export declare function scanEnsembleSessions(client: Client, ensemble: string, log?: (...args: unknown[]) => void): Promise<EnsembleSessionInfo[]>;