agent-tempo 1.0.1

package/dist/workflows/signals.d.ts

@@ -0,0 +1,297 @@
+import type { SessionMetadata, Message, SentMessage, HistoryEntry, OutboxEntry, OutboxEntryInput, QualityGate, WorktreeEntry, StageEntry, AttachmentToken, AttachmentInfo, AdapterClass, DetachReason, OrphanSummary, PlayerStateEntry } from '../types';
+export type { SessionMetadata, SessionInput, Message, Command, PlayerReport, SentMessage, HistoryEntry, OutboxEntry, OutboxEntryInput, OutboxEntryStatus, CueOutboxEntry, RecruitOutboxEntry, ReportOutboxEntry, StopOutboxEntry, ReleaseOutboxEntry, SpawnOutboxEntry, AgentType, QualityGate, QualityGateCriterion, WorktreeEntry, StageEntry, StagePlayerStatus, AttachmentToken, AttachmentInfo, AttachmentPhase, Attachment, AdapterClass, AdapterDescriptor, DetachReason, AdapterDirective, OrphanSummary, PlayerStateEntry, } from '../types';
+export declare const receiveMessageSignal: import("@temporalio/workflow").SignalDefinition<[{
+    from: string;
+    text: string;
+    isMaestro?: boolean;
+    isScheduled?: boolean;
+    scheduleName?: string;
+    responseRequested?: boolean;
+    broadcastId?: string;
+    attachmentTicket?: string;
+}], string>;
+export declare const recordSentMessageSignal: import("@temporalio/workflow").SignalDefinition<[{
+    to: string;
+    text: string;
+    broadcastId?: string;
+}], string>;
+export declare const setPartSignal: import("@temporalio/workflow").SignalDefinition<[string], string>;
+export declare const markDeliveredSignal: import("@temporalio/workflow").SignalDefinition<[string[]], string>;
+export declare const setNameSignal: import("@temporalio/workflow").SignalDefinition<[string], string>;
+export declare const updateMetadataSignal: import("@temporalio/workflow").SignalDefinition<[{
+    hostname?: string;
+    gitBranch?: string;
+    gitRoot?: string;
+    terminatedBy?: string;
+    enableStaleDetection?: boolean;
+    playerType?: string;
+    playerTypeDescription?: string;
+    worktreePath?: string;
+    sessionId?: string;
+}], string>;
+export declare const getPartQuery: import("@temporalio/workflow").QueryDefinition<string, [], string>;
+export declare const getMetadataQuery: import("@temporalio/workflow").QueryDefinition<SessionMetadata, [], string>;
+export declare const pendingMessagesQuery: import("@temporalio/workflow").QueryDefinition<Message[], [], string>;
+export declare const allMessagesQuery: import("@temporalio/workflow").QueryDefinition<Message[], [], string>;
+export declare const allSentMessagesQuery: import("@temporalio/workflow").QueryDefinition<SentMessage[], [], string>;
+/** Release a held session — unlocks the outbox and delivers the stored initial message. */
+export declare const releaseHeldSignal: import("@temporalio/workflow").SignalDefinition<[], "releaseHeld">;
+/** Query whether the session's outbox is locked (warm hold). */
+export declare const outboxLockedQuery: import("@temporalio/workflow").QueryDefinition<boolean, [], string>;
+/** Set the paused state for the session (ensemble-wide pause/resume). */
+export declare const setPausedSignal: import("@temporalio/workflow").SignalDefinition<[boolean], string>;
+/** Query whether the session is paused. */
+export declare const pausedQuery: import("@temporalio/workflow").QueryDefinition<boolean, [], string>;
+export declare const commandSignal: import("@temporalio/workflow").SignalDefinition<[{
+    text: string;
+    source: string;
+    replyTo?: string;
+}], string>;
+export declare const playerReportSignal: import("@temporalio/workflow").SignalDefinition<[{
+    playerId: string;
+    text: string;
+    type: "result" | "blocker" | "question";
+}], string>;
+export declare const historyQuery: import("@temporalio/workflow").QueryDefinition<HistoryEntry[], [], string>;
+/** Signal that the adapter has started processing an inbound message (blocking LLM/tool call). */
+export declare const processingStartUpdate: import("@temporalio/common").UpdateDefinition<{
+    inFlightCount: number;
+}, [{
+    messageId: string;
+    expectedAttachmentId?: string;
+}], string>;
+/** Signal that the adapter has finished processing an inbound message. */
+export declare const processingEndUpdate: import("@temporalio/common").UpdateDefinition<{
+    inFlightCount: number;
+}, [{
+    messageId: string;
+    expectedAttachmentId?: string;
+}], string>;
+/** Query currently in-flight message IDs. */
+export declare const inFlightMessagesQuery: import("@temporalio/workflow").QueryDefinition<string[], [], string>;
+/** Destroy the session: abandon in-flight outbox per §2.5, emit audit event, COMPLETE. */
+export declare const destroyUpdate: import("@temporalio/common").UpdateDefinition<void, [{
+    reason?: string;
+    terminatedBy?: string;
+}], string>;
+/** Query whether the session has been destroyed. */
+export declare const isDestroyedQuery: import("@temporalio/workflow").QueryDefinition<boolean, [], string>;
+/**
+ * Transactionally claim or renew the attachment lease on this workflow.
+ *
+ * - **First claim**: `expectedAttachmentId` absent, no live attachment → fresh `Attachment`
+ *   created, phase `booting → attached` (or `detached → attached`).
+ * - **Renewal**: `expectedAttachmentId` matches current attachment AND lease not expired
+ *   → extend `expiresAt` and `lastHeartbeatAt`. Returns same token.
+ * - **Conflict**: live attachment held by a different claimant → rejects with
+ *   `AttachmentConflict` ApplicationFailure.
+ * - **WorkflowGone**: phase is `gone` → rejects with `WorkflowGone`.
+ */
+export declare const claimAttachmentUpdate: import("@temporalio/common").UpdateDefinition<AttachmentToken, [{
+    host: string;
+    adapterId: string;
+    adapterClass: AdapterClass;
+    leaseMs: number;
+    /** Present on renewal; absent on fresh claim. */
+    expectedAttachmentId?: string;
+}], string>;
+/**
+ * Revoke the current attachment. Options for drain-grace behavior during `draining` phase.
+ * Returns `{ reaped: true }` when a live attachment was revoked, `{ reaped: false }` when
+ * already detached (idempotent).
+ */
+export declare const forceDetachUpdate: import("@temporalio/common").UpdateDefinition<{
+    reaped: boolean;
+    previousAttachmentId?: string;
+}, [{
+    reason: DetachReason;
+    /** If provided, only act if the current attachmentId matches. Prevents TOCTOU. */
+    expectedAttachmentId?: string;
+    /** 0 = immediate; >0 = wait up to this long for `drainingDeadline` first. */
+    gracePeriodMs: number;
+}], string>;
+/**
+ * Queue a spawn-outbox entry carrying the claim token. Called by `restart` after a successful
+ * `claimAttachment`. Workflow-side spawn-failure rollback lives in §8.4.
+ */
+export declare const enqueueSpawnUpdate: import("@temporalio/common").UpdateDefinition<{
+    spawnEntryId: string;
+}, [{
+    host: string;
+    attachmentId: string;
+    runId: string;
+    resume: boolean;
+    sessionId?: string;
+    adapterId: string;
+    /** Resolved agent definition so restart spawns `--agent`/`--system-prompt`
+     *  the same way recruit does. See #184. */
+    agentDefinition?: string;
+    agentDefinitionPath?: string;
+    nativeResolvable?: boolean;
+    /** #131 Phase C — claude-api model id carried across restart. */
+    model?: string;
+}], string>;
+/** Record a preferred host for daemon reconcile-on-boot targeting. */
+export declare const setPreferredHostUpdate: import("@temporalio/common").UpdateDefinition<void, [{
+    host: string;
+}], string>;
+/**
+ * Liveness heartbeat from the adapter. Resets `lastHeartbeatAt` and extends `expiresAt` to
+ * `workflow.now() + leaseMs` iff `attachmentId` matches the current attachment; otherwise ignored.
+ */
+export declare const heartbeatSignal: import("@temporalio/workflow").SignalDefinition<[{
+    attachmentId: string;
+    at: string;
+}], string>;
+/**
+ * Adapter-, conductor-, or operator-initiated request to detach gracefully.
+ * Phase transitions to `draining`; outbox continues to drain up to `deadlineMs` then
+ * the main loop reaps.
+ */
+export declare const requestDetachSignal: import("@temporalio/workflow").SignalDefinition<[{
+    reason: DetachReason;
+    deadlineMs: number;
+}], string>;
+/**
+ * Final acknowledgement from a detaching adapter. Collapses `draining → detached` immediately
+ * if `attachmentId` matches the current attachment; ignored on `detached` (no-op).
+ */
+export declare const adapterExitedSignal: import("@temporalio/workflow").SignalDefinition<[{
+    attachmentId: string;
+    reason: DetachReason;
+}], string>;
+/** Current attachment state + phase + in-flight count. Read by adapters, tools, and the TUI. */
+export declare const attachmentInfoQuery: import("@temporalio/workflow").QueryDefinition<AttachmentInfo, [], string>;
+/**
+ * Daemon and CLI `restore` summary — metadata to render a detached-orphan card and decide
+ * whether auto-restore applies.
+ */
+export declare const orphanSummaryQuery: import("@temporalio/workflow").QueryDefinition<OrphanSummary, [], string>;
+/**
+ * Save curated state for the calling player into a named slot.
+ *
+ * Validation (pre-handler):
+ *  - `key` matches `PLAYER_STATE_KEY_REGEX` (alphanumeric + underscore + hyphen,
+ *    1–32 chars). `PlayerStateInvalidKey` on mismatch.
+ *  - `content` byte length ≤ `PLAYER_STATE_CONTENT_MAX` (32 KiB).
+ *    `PlayerStateContentTooLarge` on overflow.
+ *  - When the key is new and slots already at `PLAYER_STATE_SLOTS_MAX` (4),
+ *    rejects with `PlayerStateSlotsFull` and lists existing keys so the LLM
+ *    can pick which slot to clear.
+ *
+ * On success, writes `{ content, savedAt: workflowNow().toISOString(), savedBy }`
+ * to `playerState[key]`. Carried via `continueAsNew`.
+ */
+export declare const savePlayerStateUpdate: import("@temporalio/common").UpdateDefinition<{
+    saved: true;
+    savedAt: string;
+}, [{
+    key: string;
+    content: string;
+    savedBy: string;
+}], string>;
+/**
+ * Clear the named slot. Returns `{ cleared: true }` if the slot existed,
+ * `{ cleared: false }` if it was already empty (idempotent). Validates `key`
+ * against `PLAYER_STATE_KEY_REGEX`.
+ */
+export declare const clearPlayerStateUpdate: import("@temporalio/common").UpdateDefinition<{
+    cleared: boolean;
+}, [{
+    key: string;
+}], string>;
+/**
+ * Read the named slot. Returns `null` when the slot is empty.
+ * `key` defaults to `PLAYER_STATE_DEFAULT_KEY` ('main').
+ *
+ * Peer-readable: any player in the ensemble may query any other player's
+ * saved state (audit identity is the entry's `savedBy`). Mirrors the
+ * `recall`/`attachment_info` ergonomics.
+ */
+export declare const playerStateQuery: import("@temporalio/workflow").QueryDefinition<PlayerStateEntry | null, [{
+    key?: string;
+}], string>;
+/** List names of populated slots (sorted). Returns `[]` when no slots are saved. */
+export declare const playerStateKeysQuery: import("@temporalio/workflow").QueryDefinition<string[], [], string>;
+export declare const submitOutboxUpdate: import("@temporalio/common").UpdateDefinition<string, [OutboxEntryInput], string>;
+export declare const outboxQuery: import("@temporalio/workflow").QueryDefinition<OutboxEntry[], [], string>;
+/**
+ * Q5.2 — runId of the current workflow execution. Returned as the raw
+ * UUID string from `workflowInfo().runId`; the dashboard truncates to
+ * `XXXX·XXXX` (first 4 + last 4 + middle dot) client-side so this query
+ * stays a thin pass-through.
+ */
+export declare const getRunIdQuery: import("@temporalio/workflow").QueryDefinition<string, [], string>;
+/**
+ * Q5.5 — messaging counters + outbox status summary. The dashboard
+ * renders three KV rows under `Messages`. Counters are monotonic
+ * across the workflow's lifetime (preserved across continueAsNew via
+ * SessionInput).
+ *
+ * `outbox` is a reduce-helper string: `"empty"` / `"N pending"` /
+ * `"N pending (oldest 2m)"` once the oldest pending entry is older than
+ * the stale threshold. Computing this server-side keeps the wire shape
+ * tight.
+ */
+export declare const getMessagingStateQuery: import("@temporalio/workflow").QueryDefinition<{
+    received: number;
+    sent: number;
+    outbox: string;
+}, [], string>;
+/**
+ * Q5.6 — activity counter + last-activity timestamp. Critical-path for
+ * W1's tempo computation: the maestro fan-queries this from each
+ * session to compute msgs/min buckets. `activityCount` increments at
+ * the same ~20 sites that already update `lastActivityTime` (cue,
+ * outbox push, schedule fire, report, recruit, restart, destroy,
+ * migrate, etc.). Heartbeats and lifecycle plumbing don't bump it.
+ *
+ * `lastActivityAt` is ISO so the maestro can compute clock-relative
+ * deltas without re-parsing.
+ */
+export declare const getActivityStateQuery: import("@temporalio/workflow").QueryDefinition<{
+    activityCount: number;
+    lastActivityAt: string;
+}, [], string>;
+/**
+ * Q5.7 — current attachment lease window. Returns `{ expiresAt,
+ * leaseMs }` as numbers (epoch ms / ms) so the dashboard can compute
+ * "expires in 54s" without parsing ISO strings every render. Both
+ * fields are `null` when no active lease (phase ∈ booting / detached /
+ * gone).
+ *
+ * The underlying `Attachment.expiresAt` is stored as an ISO string for
+ * historical reasons; the query handler parses to epoch ms at the
+ * boundary.
+ */
+export declare const getLeaseStateQuery: import("@temporalio/workflow").QueryDefinition<{
+    expiresAt: number | null;
+    leaseMs: number | null;
+}, [], string>;
+export declare const testForceContinueAsNewSignal: import("@temporalio/workflow").SignalDefinition<[], "testForceContinueAsNew">;
+export declare const setQualityGateSignal: import("@temporalio/workflow").SignalDefinition<[{
+    task: string;
+    criteria: string[];
+    createdBy: string;
+}], string>;
+export declare const evaluateGateCriteriaSignal: import("@temporalio/workflow").SignalDefinition<[{
+    task: string;
+    evaluations: Array<{
+        index: number;
+        status: "passed" | "failed";
+        notes?: string;
+    }>;
+    evaluatedBy: string;
+}], string>;
+export declare const qualityGatesQuery: import("@temporalio/workflow").QueryDefinition<QualityGate[], [], string>;
+export declare const setWorktreeSignal: import("@temporalio/workflow").SignalDefinition<[WorktreeEntry], string>;
+export declare const removeWorktreeSignal: import("@temporalio/workflow").SignalDefinition<[string], string>;
+export declare const worktreesQuery: import("@temporalio/workflow").QueryDefinition<WorktreeEntry[], [], string>;
+export declare const setStageSignal: import("@temporalio/workflow").SignalDefinition<[{
+    name: string;
+    players: string[];
+    failurePolicy?: "halt" | "continue";
+    createdBy: string;
+}], string>;
+export declare const cancelStageSignal: import("@temporalio/workflow").SignalDefinition<[string], string>;
+export declare const stagesQuery: import("@temporalio/workflow").QueryDefinition<StageEntry[], [], string>;

package/dist/workflows/signals.js

@@ -0,0 +1,239 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setStageSignal = exports.worktreesQuery = exports.removeWorktreeSignal = exports.setWorktreeSignal = exports.qualityGatesQuery = exports.evaluateGateCriteriaSignal = exports.setQualityGateSignal = exports.testForceContinueAsNewSignal = exports.getLeaseStateQuery = exports.getActivityStateQuery = exports.getMessagingStateQuery = exports.getRunIdQuery = exports.outboxQuery = exports.submitOutboxUpdate = exports.playerStateKeysQuery = exports.playerStateQuery = exports.clearPlayerStateUpdate = exports.savePlayerStateUpdate = exports.orphanSummaryQuery = exports.attachmentInfoQuery = exports.adapterExitedSignal = exports.requestDetachSignal = exports.heartbeatSignal = exports.setPreferredHostUpdate = exports.enqueueSpawnUpdate = exports.forceDetachUpdate = exports.claimAttachmentUpdate = exports.isDestroyedQuery = exports.destroyUpdate = exports.inFlightMessagesQuery = exports.processingEndUpdate = exports.processingStartUpdate = exports.historyQuery = exports.playerReportSignal = exports.commandSignal = exports.pausedQuery = exports.setPausedSignal = exports.outboxLockedQuery = exports.releaseHeldSignal = exports.allSentMessagesQuery = exports.allMessagesQuery = exports.pendingMessagesQuery = exports.getMetadataQuery = exports.getPartQuery = exports.updateMetadataSignal = exports.setNameSignal = exports.markDeliveredSignal = exports.setPartSignal = exports.recordSentMessageSignal = exports.receiveMessageSignal = void 0;
+exports.stagesQuery = exports.cancelStageSignal = void 0;
+const workflow_1 = require("@temporalio/workflow");
+// ── Player Signals ──
+// `isScheduled` + `scheduleName` are set by `src/activities/schedule-fire.ts`
+// when the message originated from the scheduler workflow — allows dashboards
+// and consumers to distinguish scheduled fires from direct cues. Documented in
+// docs/WIRE-PROTOCOL.md; runtime senders have populated both fields since the
+// scheduler shipped, but the TS type drifted (#251). Optional everywhere.
+// `broadcastId` (#357) is an additive optional field — same id on every fan-out
+// target of one `broadcast` invocation. The TUI uses it to fold N deliveries
+// into one chat row.
+// `attachmentTicket` (#318) is an additive optional field — coat-check ticket
+// the sender stashed via `coat_check_put`; the recipient pulls the body via
+// `coat_check_get`. Backward-compatible — pre-#318 cues simply don't have it.
+exports.receiveMessageSignal = (0, workflow_1.defineSignal)('receiveMessage');
+exports.recordSentMessageSignal = (0, workflow_1.defineSignal)('recordSentMessage');
+exports.setPartSignal = (0, workflow_1.defineSignal)('setPart');
+exports.markDeliveredSignal = (0, workflow_1.defineSignal)('markDelivered');
+exports.setNameSignal = (0, workflow_1.defineSignal)('setName');
+exports.updateMetadataSignal = (0, workflow_1.defineSignal)('updateMetadata');
+// ── Player Queries ──
+exports.getPartQuery = (0, workflow_1.defineQuery)('getPart');
+exports.getMetadataQuery = (0, workflow_1.defineQuery)('getMetadata');
+exports.pendingMessagesQuery = (0, workflow_1.defineQuery)('pendingMessages');
+exports.allMessagesQuery = (0, workflow_1.defineQuery)('allMessages');
+exports.allSentMessagesQuery = (0, workflow_1.defineQuery)('allSentMessages');
+// ── Hold / Release ──
+/** Release a held session — unlocks the outbox and delivers the stored initial message. */
+exports.releaseHeldSignal = (0, workflow_1.defineSignal)('releaseHeld');
+/** Query whether the session's outbox is locked (warm hold). */
+exports.outboxLockedQuery = (0, workflow_1.defineQuery)('outboxLocked');
+/** Set the paused state for the session (ensemble-wide pause/resume). */
+exports.setPausedSignal = (0, workflow_1.defineSignal)('setPaused');
+/** Query whether the session is paused. */
+exports.pausedQuery = (0, workflow_1.defineQuery)('paused');
+// ── Conductor Signals ──
+exports.commandSignal = (0, workflow_1.defineSignal)('command');
+exports.playerReportSignal = (0, workflow_1.defineSignal)('playerReport');
+// ── Conductor Queries ──
+exports.historyQuery = (0, workflow_1.defineQuery)('history');
+// ── Processing Lifecycle (fixes #99; phase machine hook in v0.25) ──
+// Suppress stale detection while the adapter is in a blocking operation (e.g. LLM tool call).
+// `messageId` is required for idempotency — at-least-once update retries otherwise corrupt the set.
+//
+// v0.25 extends the input to carry `expectedAttachmentId` and the return to carry
+// `inFlightCount`. The MVP shape (`{ messageId }`, `void`) remains supported by the
+// compat shim; when `expectedAttachmentId` is absent the handler operates on whatever
+// attachment is currently active (reconstructing MVP semantics).
+//
+// Post-PR-C, adapters always provide `expectedAttachmentId` so the workflow can reject
+// updates intended for a superseded attachment.
+/** Signal that the adapter has started processing an inbound message (blocking LLM/tool call). */
+exports.processingStartUpdate = (0, workflow_1.defineUpdate)('processingStart');
+/** Signal that the adapter has finished processing an inbound message. */
+exports.processingEndUpdate = (0, workflow_1.defineUpdate)('processingEnd');
+/** Query currently in-flight message IDs. */
+exports.inFlightMessagesQuery = (0, workflow_1.defineQuery)('inFlightMessages');
+// ── Destroy Verb (fixes #102; terminal per §8.5) ──
+// Permanent, terminal teardown. Once destroyed, the workflow refuses all attach-adjacent ops
+// and adapters (bridge) must exit cleanly instead of reconnecting.
+/** Destroy the session: abandon in-flight outbox per §2.5, emit audit event, COMPLETE. */
+exports.destroyUpdate = (0, workflow_1.defineUpdate)('destroy');
+/** Query whether the session has been destroyed. */
+exports.isDestroyedQuery = (0, workflow_1.defineQuery)('isDestroyed');
+// ── v0.25 Attachment Lifecycle (design §§8, §9.2, §11.1) ──
+/**
+ * Transactionally claim or renew the attachment lease on this workflow.
+ *
+ * - **First claim**: `expectedAttachmentId` absent, no live attachment → fresh `Attachment`
+ *   created, phase `booting → attached` (or `detached → attached`).
+ * - **Renewal**: `expectedAttachmentId` matches current attachment AND lease not expired
+ *   → extend `expiresAt` and `lastHeartbeatAt`. Returns same token.
+ * - **Conflict**: live attachment held by a different claimant → rejects with
+ *   `AttachmentConflict` ApplicationFailure.
+ * - **WorkflowGone**: phase is `gone` → rejects with `WorkflowGone`.
+ */
+exports.claimAttachmentUpdate = (0, workflow_1.defineUpdate)('claimAttachment');
+/**
+ * Revoke the current attachment. Options for drain-grace behavior during `draining` phase.
+ * Returns `{ reaped: true }` when a live attachment was revoked, `{ reaped: false }` when
+ * already detached (idempotent).
+ */
+exports.forceDetachUpdate = (0, workflow_1.defineUpdate)('forceDetach');
+/**
+ * Queue a spawn-outbox entry carrying the claim token. Called by `restart` after a successful
+ * `claimAttachment`. Workflow-side spawn-failure rollback lives in §8.4.
+ */
+exports.enqueueSpawnUpdate = (0, workflow_1.defineUpdate)('enqueueSpawn');
+/** Record a preferred host for daemon reconcile-on-boot targeting. */
+exports.setPreferredHostUpdate = (0, workflow_1.defineUpdate)('setPreferredHost');
+// ── v0.25 Attachment Signals ──
+/**
+ * Liveness heartbeat from the adapter. Resets `lastHeartbeatAt` and extends `expiresAt` to
+ * `workflow.now() + leaseMs` iff `attachmentId` matches the current attachment; otherwise ignored.
+ */
+exports.heartbeatSignal = (0, workflow_1.defineSignal)('heartbeat');
+/**
+ * Adapter-, conductor-, or operator-initiated request to detach gracefully.
+ * Phase transitions to `draining`; outbox continues to drain up to `deadlineMs` then
+ * the main loop reaps.
+ */
+exports.requestDetachSignal = (0, workflow_1.defineSignal)('requestDetach');
+/**
+ * Final acknowledgement from a detaching adapter. Collapses `draining → detached` immediately
+ * if `attachmentId` matches the current attachment; ignored on `detached` (no-op).
+ */
+exports.adapterExitedSignal = (0, workflow_1.defineSignal)('adapterExited');
+// ── v0.25 Attachment Queries ──
+/** Current attachment state + phase + in-flight count. Read by adapters, tools, and the TUI. */
+exports.attachmentInfoQuery = (0, workflow_1.defineQuery)('attachmentInfo');
+/**
+ * Daemon and CLI `restore` summary — metadata to render a detached-orphan card and decide
+ * whether auto-restore applies.
+ */
+exports.orphanSummaryQuery = (0, workflow_1.defineQuery)('orphanSummary');
+// ── Player Saveable State (#334 PR-1, ADR 0011) ──
+//
+// Per-session, player-curated state slots. Player-only writes (no `playerId`
+// arg → tool wires the calling player's own handle); peer reads via
+// `playerStateQuery`. Sized per design §3.3: max 4 slots × 32 KiB content
+// = 128 KiB structural max. Saturation rejects with `PlayerStateSlotsFull`
+// rather than evicting LRU.
+//
+// Validators run pre-handler so size/slot-cap rejections never commit
+// history events. See `src/utils/validation.ts` for the constants.
+/**
+ * Save curated state for the calling player into a named slot.
+ *
+ * Validation (pre-handler):
+ *  - `key` matches `PLAYER_STATE_KEY_REGEX` (alphanumeric + underscore + hyphen,
+ *    1–32 chars). `PlayerStateInvalidKey` on mismatch.
+ *  - `content` byte length ≤ `PLAYER_STATE_CONTENT_MAX` (32 KiB).
+ *    `PlayerStateContentTooLarge` on overflow.
+ *  - When the key is new and slots already at `PLAYER_STATE_SLOTS_MAX` (4),
+ *    rejects with `PlayerStateSlotsFull` and lists existing keys so the LLM
+ *    can pick which slot to clear.
+ *
+ * On success, writes `{ content, savedAt: workflowNow().toISOString(), savedBy }`
+ * to `playerState[key]`. Carried via `continueAsNew`.
+ */
+exports.savePlayerStateUpdate = (0, workflow_1.defineUpdate)('savePlayerState');
+/**
+ * Clear the named slot. Returns `{ cleared: true }` if the slot existed,
+ * `{ cleared: false }` if it was already empty (idempotent). Validates `key`
+ * against `PLAYER_STATE_KEY_REGEX`.
+ */
+exports.clearPlayerStateUpdate = (0, workflow_1.defineUpdate)('clearPlayerState');
+/**
+ * Read the named slot. Returns `null` when the slot is empty.
+ * `key` defaults to `PLAYER_STATE_DEFAULT_KEY` ('main').
+ *
+ * Peer-readable: any player in the ensemble may query any other player's
+ * saved state (audit identity is the entry's `savedBy`). Mirrors the
+ * `recall`/`attachment_info` ergonomics.
+ */
+exports.playerStateQuery = (0, workflow_1.defineQuery)('playerState');
+/** List names of populated slots (sorted). Returns `[]` when no slots are saved. */
+exports.playerStateKeysQuery = (0, workflow_1.defineQuery)('playerStateKeys');
+// ── Outbox Update + Query ──
+exports.submitOutboxUpdate = (0, workflow_1.defineUpdate)('submitOutbox');
+exports.outboxQuery = (0, workflow_1.defineQuery)('outbox');
+// ── #399 W2 — Session wire extensions (Q5.2 / Q5.5 / Q5.6 / Q5.7) ──
+//
+// Additive queries that surface session-level fields the dashboard
+// renders as `"—"` placeholders today. All counters live on the session
+// workflow + carry across continueAsNew via SessionInput.
+/**
+ * Q5.2 — runId of the current workflow execution. Returned as the raw
+ * UUID string from `workflowInfo().runId`; the dashboard truncates to
+ * `XXXX·XXXX` (first 4 + last 4 + middle dot) client-side so this query
+ * stays a thin pass-through.
+ */
+exports.getRunIdQuery = (0, workflow_1.defineQuery)('getRunId');
+/**
+ * Q5.5 — messaging counters + outbox status summary. The dashboard
+ * renders three KV rows under `Messages`. Counters are monotonic
+ * across the workflow's lifetime (preserved across continueAsNew via
+ * SessionInput).
+ *
+ * `outbox` is a reduce-helper string: `"empty"` / `"N pending"` /
+ * `"N pending (oldest 2m)"` once the oldest pending entry is older than
+ * the stale threshold. Computing this server-side keeps the wire shape
+ * tight.
+ */
+exports.getMessagingStateQuery = (0, workflow_1.defineQuery)('getMessagingState');
+/**
+ * Q5.6 — activity counter + last-activity timestamp. Critical-path for
+ * W1's tempo computation: the maestro fan-queries this from each
+ * session to compute msgs/min buckets. `activityCount` increments at
+ * the same ~20 sites that already update `lastActivityTime` (cue,
+ * outbox push, schedule fire, report, recruit, restart, destroy,
+ * migrate, etc.). Heartbeats and lifecycle plumbing don't bump it.
+ *
+ * `lastActivityAt` is ISO so the maestro can compute clock-relative
+ * deltas without re-parsing.
+ */
+exports.getActivityStateQuery = (0, workflow_1.defineQuery)('getActivityState');
+/**
+ * Q5.7 — current attachment lease window. Returns `{ expiresAt,
+ * leaseMs }` as numbers (epoch ms / ms) so the dashboard can compute
+ * "expires in 54s" without parsing ISO strings every render. Both
+ * fields are `null` when no active lease (phase ∈ booting / detached /
+ * gone).
+ *
+ * The underlying `Attachment.expiresAt` is stored as an ISO string for
+ * historical reasons; the query handler parses to epoch ms at the
+ * boundary.
+ */
+exports.getLeaseStateQuery = (0, workflow_1.defineQuery)('getLeaseState');
+// ── Test-only Signals ──
+//
+// **Test-only.** Forces the session workflow's main loop to take the
+// `continueAsNew` branch on its next iteration, regardless of
+// `workflowInfo().continueAsNewSuggested`. Used by the adapter reconnect test
+// (#226) to exercise the CAN-boundary rebind path without spamming ~10k
+// history events to hit the server's native suggestion threshold.
+//
+// Production senders do not exist — the signal is a test fixture. Kept on the
+// main signal surface (rather than a side channel) so the workflow worker
+// bundle needs no special build flag to accept it. The wire name is a plain
+// identifier so the wire-protocol drift detector can match it in the docs
+// table (the doc regex in `test/wire-protocol.test.ts` only accepts
+// identifier-shaped names to avoid picking up prose false positives).
+exports.testForceContinueAsNewSignal = (0, workflow_1.defineSignal)('testForceContinueAsNew');
+// ── Quality Gate Signals + Query (conductor-only) ──
+exports.setQualityGateSignal = (0, workflow_1.defineSignal)('setQualityGate');
+exports.evaluateGateCriteriaSignal = (0, workflow_1.defineSignal)('evaluateGateCriteria');
+exports.qualityGatesQuery = (0, workflow_1.defineQuery)('qualityGates');
+// ── Worktree Signals + Query (conductor-only) ──
+exports.setWorktreeSignal = (0, workflow_1.defineSignal)('setWorktree');
+exports.removeWorktreeSignal = (0, workflow_1.defineSignal)('removeWorktree');
+exports.worktreesQuery = (0, workflow_1.defineQuery)('worktrees');
+// ── Stage Signals + Query (conductor-only) ──
+exports.setStageSignal = (0, workflow_1.defineSignal)('setStage');
+exports.cancelStageSignal = (0, workflow_1.defineSignal)('cancelStage');
+exports.stagesQuery = (0, workflow_1.defineQuery)('stages');

package/examples/agents/tempo-composer.md

@@ -0,0 +1,56 @@
+---
+name: tempo-composer
+description: Software architect — designs system structure, defines interfaces, makes technology decisions. Focuses on the "what" and "why", not implementation.
+model: opus
+---
+
+You are the **Composer** of the ensemble — the Software Architect. You design the structure of the system: modules, boundaries, interfaces, data flow, and technical direction. You define *what* gets built and *why*, then hand off the *how* to soloists.
+
+## Responsibilities
+
+- Design system architecture: module boundaries, service decomposition, data flow
+- Define interfaces and contracts between components
+- Make technology choices with clear rationale
+- Analyze dependencies, coupling, and integration points
+- Identify scalability, security, and maintainability risks before they become problems
+- Review proposed designs and implementations for architectural consistency
+- Select API paradigms (REST, GraphQL, RPC) based on use case requirements
+
+## Working Style
+
+- **Understand before proposing**: Read existing code and architecture before suggesting changes. Respect what's already there.
+- **Think in systems**: Focus on boundaries, trade-offs, and data flow — not individual functions.
+- **Document decisions**: Every architectural decision should come with rationale and trade-offs considered. Write ADRs when the decision is significant.
+- **Be opinionated but open**: Have strong views on architecture, loosely held. Change your mind when presented with evidence.
+- **Delegate implementation**: Define the shape of the solution, then hand off to soloists. Don't get pulled into writing production code.
+- **Consider observability**: Design systems that are debuggable. Think about logging, tracing, and error reporting from the start.
+- **Don't over-architect**: Design the simplest structure that meets the known requirements. If you're adding abstraction layers without a concrete, present-tense benefit, remove them. Apply `/simplify` thinking — if a design element can't be justified by a real requirement, it doesn't belong.
+- **Avoid designing for imagined futures**: Add extensibility only where there's evidence you'll need it. Speculative abstractions become maintenance burdens. You can always refactor when the need is real.
+
+## Ensemble Collaboration
+
+- **`ensemble`**: Check who's active before proposing designs that affect multiple players' work. Understand the current state of implementation.
+- **`cue`**: Use to share design decisions, interface definitions, and architectural guidance with soloists. When a soloist asks a design question, respond with structured reasoning: context, options, recommendation, trade-offs.
+- **`report`**: Report to the conductor when:
+  - A design decision is made (so it can be communicated to affected players)
+  - You identify an architectural risk or concern
+  - You need input on requirements before you can finalize a design
+  - A design review is complete (with approve/reject/concerns)
+- **`who_am_i`**: Check your assignment and any type-specific instructions at startup.
+- **`agent_types`**: If you identify a need for a specialist (e.g., security review of your design), suggest the conductor recruit one.
+
+### When other players cue you
+
+- **Soloists asking design questions**: Respond promptly with clear, actionable guidance. Don't send them in circles.
+- **Conductor asking for design review**: Provide structured feedback — approved, changes requested, or concerns flagged — with specific reasoning.
+- **Tuners reporting architectural test gaps**: Acknowledge and adjust the design to improve testability if needed.
+
+## Context Pressure
+
+If you notice your context growing large, you're losing track of earlier instructions, or you find yourself repeating work, report to the conductor immediately with a structured summary:
+
+1. **Current task**: What you're working on right now
+2. **Key findings so far**: Important decisions, completed work, file paths changed
+3. **Recommended next steps**: What remains to be done
+
+This lets the conductor refresh your session with a clean context while preserving continuity.