agent-tempo 1.0.1

package/dist/adapters/opencode/server-bridge.js

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * Thin HTTP/SSE wrapper around `opencode serve`.
+ *
+ * Hand-rolled over native `fetch` rather than `@opencode-ai/sdk` per design
+ * §8.3 LoC tightening proposal #2 — the SDK is auto-generated from
+ * OpenAPI 3.1, so it pulls in OpenAPI runtime + per-endpoint typed clients
+ * for ~50 endpoints. Our hot path uses ~5 endpoints + the `/event` SSE
+ * stream; the SDK weight isn't worth it. The architectural shape of the
+ * adapter is identical either way.
+ *
+ * The SDK is still listed as an `optionalDependency` and `require.resolve`
+ * gates the recruit pre-flight (ADR 0015 §85) — operators install it as
+ * the signal that opencode integration is intended on this host. Adapter
+ * runtime, however, never imports it.
+ *
+ * Contract surface (5 methods + 1 generator):
+ *   - `waitForHealth(timeoutMs)`
+ *   - `getHealth()`
+ *   - `createSession()`
+ *   - `promptAsync(sessionId, body)`
+ *   - `abortSession(sessionId)`
+ *   - `deleteSession(sessionId)`
+ *   - `subscribeEvents(abortSignal)` — async generator yielding parsed events
+ *
+ * Design reference: docs/design/449-opencode-adapter.md §5.3, §8.1.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenCodeServerBridge = void 0;
+/** Default health-probe poll interval. Tight loop — opencode boots in <1s. */
+const HEALTH_POLL_INTERVAL_MS = 200;
+class OpenCodeServerBridge {
+    baseUrl;
+    log;
+    fetchImpl;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/$/, '');
+        this.log = opts.log ?? ((..._args) => { });
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+    }
+    /**
+     * Poll `GET /global/health` until 200 or `timeoutMs` elapses. Throws on
+     * timeout — caller is the adapter `run()` and a missing health probe
+     * means opencode didn't boot.
+     */
+    async waitForHealth(timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        let lastErr = null;
+        while (Date.now() < deadline) {
+            try {
+                const res = await this.fetchImpl(`${this.baseUrl}/global/health`);
+                if (res.ok)
+                    return;
+                lastErr = new Error(`/global/health returned ${res.status}`);
+            }
+            catch (err) {
+                // Connection refused while opencode is still booting — keep polling.
+                lastErr = err;
+            }
+            await sleep(HEALTH_POLL_INTERVAL_MS);
+        }
+        throw new Error(`opencode serve did not become healthy within ${timeoutMs}ms${lastErr ? ` (last error: ${lastErr?.message ?? lastErr})` : ''}`);
+    }
+    /** `GET /global/health` — version + healthy flag. */
+    async getHealth() {
+        const res = await this.fetchImpl(`${this.baseUrl}/global/health`);
+        if (!res.ok) {
+            throw new Error(`/global/health returned ${res.status} ${res.statusText}`);
+        }
+        return (await res.json());
+    }
+    /** `POST /session` — create a new session; returns the session id + meta. */
+    async createSession() {
+        const res = await this.fetchImpl(`${this.baseUrl}/session`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: '{}',
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throw new Error(`POST /session returned ${res.status} ${res.statusText}${body ? ': ' + body : ''}`);
+        }
+        return (await res.json());
+    }
+    /**
+     * `POST /session/:id/prompt_async` — send a turn; returns 204 immediately
+     * and the turn streams over `/event` SSE. Caller is responsible for
+     * subscribing to events first.
+     */
+    async promptAsync(sessionId, body) {
+        const res = await this.fetchImpl(`${this.baseUrl}/session/${encodeURIComponent(sessionId)}/prompt_async`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new Error(`prompt_async returned ${res.status} ${res.statusText}${text ? ': ' + text : ''}`);
+        }
+    }
+    /**
+     * `POST /session/:id/abort` — graceful turn cancellation. The primary
+     * cancellation path on lease revocation; subprocess SIGTERM is the
+     * fallback only if this hangs.
+     *
+     * Best-effort — swallows non-2xx so the adapter's superseded path can
+     * still fall through to subprocess kill without surfacing an error.
+     */
+    async abortSession(sessionId, opts) {
+        try {
+            await this.fetchImpl(`${this.baseUrl}/session/${encodeURIComponent(sessionId)}/abort`, { method: 'POST', signal: opts?.signal });
+        }
+        catch (err) {
+            this.log('abortSession suppressed error:', err?.message ?? err);
+        }
+    }
+    /**
+     * `DELETE /session/:id` — free server-side session resources. Called on
+     * graceful detach. Best-effort — swallows non-2xx.
+     */
+    async deleteSession(sessionId) {
+        try {
+            await this.fetchImpl(`${this.baseUrl}/session/${encodeURIComponent(sessionId)}/`, { method: 'DELETE' });
+        }
+        catch (err) {
+            this.log('deleteSession suppressed error:', err?.message ?? err);
+        }
+    }
+    /**
+     * `GET /event` — SSE stream of session events. Returns an async
+     * generator that yields parsed `OpenCodeEvent` objects until the
+     * abort signal fires or the stream closes.
+     *
+     * The caller is responsible for filtering events by session id —
+     * `/event` is global per `opencode serve` instance, but the v1
+     * subprocess-per-player model means there's only ever one session
+     * per stream anyway. Phase 2 subprocess-shared optimization would
+     * make filtering meaningful.
+     */
+    async *subscribeEvents(signal) {
+        const res = await this.fetchImpl(`${this.baseUrl}/event`, {
+            headers: { accept: 'text/event-stream' },
+            signal,
+        });
+        if (!res.ok || !res.body) {
+            throw new Error(`/event returned ${res.status} ${res.statusText}`);
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder('utf-8');
+        let buffer = '';
+        try {
+            while (true) {
+                const { value, done } = await reader.read();
+                if (done)
+                    return;
+                buffer += decoder.decode(value, { stream: true });
+                // SSE: events are separated by blank lines (\n\n). One event may
+                // span multiple `data:` lines; concatenate and parse as JSON.
+                let sep = buffer.indexOf('\n\n');
+                while (sep !== -1) {
+                    const block = buffer.slice(0, sep);
+                    buffer = buffer.slice(sep + 2);
+                    const event = parseSseBlock(block);
+                    if (event)
+                        yield event;
+                    sep = buffer.indexOf('\n\n');
+                }
+            }
+        }
+        finally {
+            // Release the reader so the underlying connection can close.
+            try {
+                reader.releaseLock();
+            }
+            catch { /* already released */ }
+        }
+    }
+}
+exports.OpenCodeServerBridge = OpenCodeServerBridge;
+/**
+ * Parse one SSE block (the text between two blank-line separators) into
+ * an `OpenCodeEvent`. Returns `null` on parse failure or empty `data`.
+ *
+ * Format per SSE spec:
+ *   event: foo       (optional — most OpenCode events use only `data:`)
+ *   data: { ... }
+ *   data: ...        (continuation of data; concatenated with `\n`)
+ */
+function parseSseBlock(block) {
+    const dataLines = [];
+    for (const line of block.split('\n')) {
+        if (line.startsWith('data:')) {
+            dataLines.push(line.slice(5).trimStart());
+        }
+        // event: / id: / retry: lines ignored — agent-tempo only consumes data.
+    }
+    if (dataLines.length === 0)
+        return null;
+    const payload = dataLines.join('\n');
+    if (!payload)
+        return null;
+    try {
+        const parsed = JSON.parse(payload);
+        if (parsed && typeof parsed === 'object' && typeof parsed.type === 'string') {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        // Non-JSON event — opencode shouldn't emit these; ignore safely.
+        return null;
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/dist/adapters/sdk/base.d.ts

@@ -0,0 +1,95 @@
+/**
+ * SDK-class adapter base.
+ *
+ * Class hierarchy per design §4.1: `SdkAttachment extends BaseAttachment`. Concrete
+ * SDK adapters (copilot, future `headless-claude`) extend this.
+ *
+ * PR-C commit 3 fills in the shared SDK lifecycle on top of the V2 attachment
+ * machinery landed in commit 2's `BaseAttachment`:
+ *
+ *   - **Processing-signal pairing.** `deliver()` wraps each SDK turn in
+ *     `processingStart` (update) → `invokeSdk()` (concrete) → `processingEnd`
+ *     (update) → `markDelivered` (signal). Updates are synchronous (§7.1) — a
+ *     dropped `processingStart` is observable, not silent.
+ *   - **Split-brain cancellation.** When the base-class phase watcher fires
+ *     `onLeaseRevoked`, `SdkAttachment` calls the concrete `onSuperseded()`
+ *     hook. The concrete adapter (Copilot, headless-claude, …) aborts the
+ *     in-flight `sendAndWait` via its SDK-specific mechanism and exits.
+ *     Residual ghost-reply window is documented in §9.3.
+ *
+ * **This file runs in the Node.js adapter process, NOT the Temporal workflow
+ * sandbox.** Node.js timers are appropriate here; workflow-bundle code lives
+ * elsewhere (in `src/workflows/`).
+ *
+ * Design reference: docs/design/session-lifecycle-rebuild-v2.md §§4.1, 4.4, 6.1,
+ * 6.2, 7.1, 9.3.
+ */
+import type { WorkflowHandle } from '@temporalio/client';
+import { BaseAttachment, type BaseAttachmentOptions } from '../base';
+import type { Message, DetachReason } from '../../types';
+/** Per-message result from `SdkAttachment.deliver()`. */
+export interface SdkDeliverResult {
+    /** Whatever `invokeSdk()` returned — up to the concrete adapter to define. */
+    sdkResult: unknown;
+    /** Time spent inside `invokeSdk()` in milliseconds. */
+    elapsedMs: number;
+}
+/**
+ * Abstract base for SDK-class adapters.
+ *
+ * Owns processing-signal pairing and split-brain cancellation wiring. Concrete
+ * subclasses (`CopilotSdkAttachment`, future `HeadlessClaudeAttachment`) provide:
+ *
+ *   - `invokeSdk(prompt, timeoutMs)` — the actual blocking SDK call.
+ *   - `onSuperseded()` — abort the in-flight SDK call on lease revocation.
+ *
+ * Subclasses set up the V2 lifecycle by calling `startV2Lifecycle(workflowId)`
+ * on `BaseAttachment` (inherited from commit 2) to claim the attachment + start
+ * heartbeat + phase watcher. Then they drive a poll loop that calls
+ * `this.deliver(msg)` per message; `deliver()` handles the processing-signal
+ * pairing and the final `markDelivered` ack.
+ */
+export declare abstract class SdkAttachment extends BaseAttachment {
+    /** Subclass hook — cancel the in-flight SDK invocation (AbortController / session.cancel / disconnect). */
+    protected abstract onSuperseded(): void;
+    /**
+     * Whether we are currently inside an `invokeSdk` call. Read by `onSuperseded`
+     * implementations to decide whether cancellation actually has an effect.
+     */
+    protected sdkInFlight: boolean;
+    constructor(options?: BaseAttachmentOptions);
+    /**
+     * Deliver one message through the SDK turn. Wire-protocol surface:
+     *
+     *   1. `processingStart` update — synchronous (§7.1). If the update rejects
+     *      with `AttachmentMismatch` or `WorkflowGone`, we propagate the error
+     *      without calling `invokeSdk` — lease revocation is already in flight
+     *      via the phase watcher and the ghost-turn SHOULD be skipped.
+     *   2. `invokeSdk(prompt, timeoutMs)` — the concrete blocking call. Runs
+     *      under `sdkInFlight = true` so `onSuperseded` can identify the target.
+     *   3. `processingEnd` update — synchronous, in a `finally` so any throw
+     *      from `invokeSdk` still releases the in-flight marker on the workflow.
+     *      Errors here are logged and swallowed: if the workflow is gone or the
+     *      attachment was revoked, the processing set is meaningless.
+     *   4. `markDelivered` signal — fires only on successful `invokeSdk` return,
+     *      so at-least-once delivery survives crashes mid-turn.
+     *
+     * @param pinned    Pinned `WorkflowHandle` returned by `startV2Lifecycle()`.
+     * @param msg       Representative message for the in-flight set — its id is
+     *                  used in `processingStart`/`processingEnd`.
+     * @param prompt    Formatted prompt for the SDK (concrete subclass formats).
+     * @param timeoutMs SDK invocation timeout.
+     * @param invokeSdk Concrete SDK call. Receives formatted prompt + timeout.
+     * @param ackIds    Message ids to mark delivered after the SDK turn completes.
+     *                  Defaults to `[msg.id]`. Copilot's bridge joins multiple
+     *                  pending messages into a single prompt and acks them all
+     *                  with one `markDelivered` signal — pass the full batch.
+     */
+    protected deliver(pinned: WorkflowHandle, msg: Message, prompt: string, timeoutMs: number, invokeSdk: (prompt: string, timeoutMs: number) => Promise<unknown>, ackIds?: string[]): Promise<SdkDeliverResult>;
+    /**
+     * Subclass-facing convenience: call this from `startV2Lifecycle` path to
+     * fire `adapterExited` on clean shutdown and tear down the V2 machinery.
+     * Forwards to `BaseAttachment.stopV2Lifecycle` with graceful=true.
+     */
+    protected detachGracefully(reason?: DetachReason): Promise<void>;
+}

package/dist/adapters/sdk/base.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SdkAttachment = void 0;
+const base_1 = require("../base");
+const signals_1 = require("../../workflows/signals");
+const log = (...args) => console.error('[agent-tempo:sdk-adapter]', ...args);
+/**
+ * Abstract base for SDK-class adapters.
+ *
+ * Owns processing-signal pairing and split-brain cancellation wiring. Concrete
+ * subclasses (`CopilotSdkAttachment`, future `HeadlessClaudeAttachment`) provide:
+ *
+ *   - `invokeSdk(prompt, timeoutMs)` — the actual blocking SDK call.
+ *   - `onSuperseded()` — abort the in-flight SDK call on lease revocation.
+ *
+ * Subclasses set up the V2 lifecycle by calling `startV2Lifecycle(workflowId)`
+ * on `BaseAttachment` (inherited from commit 2) to claim the attachment + start
+ * heartbeat + phase watcher. Then they drive a poll loop that calls
+ * `this.deliver(msg)` per message; `deliver()` handles the processing-signal
+ * pairing and the final `markDelivered` ack.
+ */
+class SdkAttachment extends base_1.BaseAttachment {
+    /**
+     * Whether we are currently inside an `invokeSdk` call. Read by `onSuperseded`
+     * implementations to decide whether cancellation actually has an effect.
+     */
+    sdkInFlight = false;
+    constructor(options = {}) {
+        super(options);
+        // Wire the V2 lease-revoked signal (fired by BaseAttachment's phase watcher
+        // when `attachmentInfo.currentAttachment.attachmentId` diverges from our
+        // token) into the concrete subclass's cancel hook. BaseAttachment has
+        // already stopped the heartbeat + watcher at this point — our job is to
+        // abort the blocking SDK turn before it produces a ghost reply (§9.3).
+        this.onLeaseRevoked((reason) => {
+            log(`lease revoked (${reason}) — firing onSuperseded`);
+            try {
+                this.onSuperseded();
+            }
+            catch (err) {
+                log('onSuperseded threw:', err?.message ?? err);
+            }
+        });
+    }
+    /**
+     * Deliver one message through the SDK turn. Wire-protocol surface:
+     *
+     *   1. `processingStart` update — synchronous (§7.1). If the update rejects
+     *      with `AttachmentMismatch` or `WorkflowGone`, we propagate the error
+     *      without calling `invokeSdk` — lease revocation is already in flight
+     *      via the phase watcher and the ghost-turn SHOULD be skipped.
+     *   2. `invokeSdk(prompt, timeoutMs)` — the concrete blocking call. Runs
+     *      under `sdkInFlight = true` so `onSuperseded` can identify the target.
+     *   3. `processingEnd` update — synchronous, in a `finally` so any throw
+     *      from `invokeSdk` still releases the in-flight marker on the workflow.
+     *      Errors here are logged and swallowed: if the workflow is gone or the
+     *      attachment was revoked, the processing set is meaningless.
+     *   4. `markDelivered` signal — fires only on successful `invokeSdk` return,
+     *      so at-least-once delivery survives crashes mid-turn.
+     *
+     * @param pinned    Pinned `WorkflowHandle` returned by `startV2Lifecycle()`.
+     * @param msg       Representative message for the in-flight set — its id is
+     *                  used in `processingStart`/`processingEnd`.
+     * @param prompt    Formatted prompt for the SDK (concrete subclass formats).
+     * @param timeoutMs SDK invocation timeout.
+     * @param invokeSdk Concrete SDK call. Receives formatted prompt + timeout.
+     * @param ackIds    Message ids to mark delivered after the SDK turn completes.
+     *                  Defaults to `[msg.id]`. Copilot's bridge joins multiple
+     *                  pending messages into a single prompt and acks them all
+     *                  with one `markDelivered` signal — pass the full batch.
+     */
+    async deliver(pinned, msg, prompt, timeoutMs, invokeSdk, ackIds) {
+        if (!this.token) {
+            throw new Error('SdkAttachment.deliver called with no attachment token — did startV2Lifecycle run?');
+        }
+        // (1) Announce in-flight work. Synchronous per §7.1 — if the workflow has
+        // been destroyed or the lease revoked, the update throws and we bail
+        // before burning an SDK turn.
+        await pinned.executeUpdate(signals_1.processingStartUpdate, {
+            args: [{
+                    messageId: msg.id,
+                    expectedAttachmentId: this.token.attachmentId,
+                }],
+        });
+        const t0 = Date.now();
+        let sdkResult;
+        this.sdkInFlight = true;
+        try {
+            // (2) Concrete SDK call. Blocks until the LLM turn completes or the
+            // concrete adapter aborts via `onSuperseded`.
+            sdkResult = await invokeSdk(prompt, timeoutMs);
+        }
+        finally {
+            this.sdkInFlight = false;
+            // (3) Always release the in-flight marker, even on throw. Swallow errors:
+            // if the workflow is gone or the lease was revoked during the turn, the
+            // in-flight set is already dead-lettered on the workflow side.
+            try {
+                await pinned.executeUpdate(signals_1.processingEndUpdate, {
+                    args: [{
+                            messageId: msg.id,
+                            expectedAttachmentId: this.token.attachmentId,
+                        }],
+                });
+            }
+            catch (err) {
+                log(`processingEnd suppressed error: ${err?.message ?? err}`);
+            }
+        }
+        const elapsedMs = Date.now() - t0;
+        // (4) Ack delivery only after the SDK turn completed cleanly. If invokeSdk
+        // threw, we never reach here and messages stay pending for retry.
+        // C4 (PR-C dual-QA follow-up): use the typed signal constant so the
+        // ts-morph wire-protocol drift detector can see the reference — a string
+        // literal would be invisible to the static scan.
+        const toAck = ackIds ?? [msg.id];
+        try {
+            await pinned.signal(signals_1.markDeliveredSignal, toAck);
+        }
+        catch (err) {
+            log(`markDelivered suppressed error: ${err?.message ?? err}`);
+        }
+        return { sdkResult, elapsedMs };
+    }
+    /**
+     * Subclass-facing convenience: call this from `startV2Lifecycle` path to
+     * fire `adapterExited` on clean shutdown and tear down the V2 machinery.
+     * Forwards to `BaseAttachment.stopV2Lifecycle` with graceful=true.
+     */
+    async detachGracefully(reason = 'user-stop') {
+        await this.stopV2Lifecycle(reason, /* graceful */ true);
+    }
+}
+exports.SdkAttachment = SdkAttachment;

package/dist/adapters/sdk/system-prompt.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared SDK-class adapter system-prompt helpers (#536).
+ *
+ * Two SDK-class adapters in this repo currently mirror an *identical*
+ * "use your MCP tools to reply" framing onto the model — copilot
+ * (`src/adapters/copilot/adapter.ts:283-297`) and, post-#536,
+ * claude-code-headless (`src/adapters/claude-code-headless/adapter.ts`).
+ * Pre-#536 the framing only existed on copilot's side, hand-typed
+ * inline; this module factors it out so:
+ *
+ *   - There is one canonical source for the prompt content (no copy
+ *     drift when someone tweaks the wording in one place and forgets
+ *     the other).
+ *   - The MAESTRO_ACK augmentation that copilot's poll loop applies
+ *     to human-from-dashboard messages is identifiable by name from
+ *     either adapter's prompt-build site.
+ *
+ * **Why not `buildServerInstructions` from `src/server-tools.ts`?**
+ * The other two SDK-class adapters (claude-api, opencode) DO use
+ * `buildServerInstructions` for their per-turn system prompt. Copilot
+ * predates that helper and ships its own inline framing with a more
+ * explicit "tools available" enumeration. Issue #536 directs
+ * claude-code-headless to mirror **copilot's** content (so the two
+ * adapters speak the same dialect to the model), not the canonical
+ * helper. A future consolidation pass could migrate ALL four SDK
+ * adapters onto `buildServerInstructions` — out of scope here.
+ */
+/**
+ * SDK-class adapter system-prompt template, parameterized by ensemble.
+ *
+ * Lifted verbatim from `src/adapters/copilot/adapter.ts:283-297` (the
+ * pre-#536 inline `systemMessage.content`). Both copilot and
+ * claude-code-headless feed this into their per-turn invocation:
+ *   - copilot via `sessionConfig.systemMessage` to the SDK's
+ *     `createSession` call.
+ *   - claude-code-headless via `--append-system-prompt <content>` on
+ *     the per-turn `claude -p` argv.
+ *
+ * Returning a function (rather than a constant) preserves the
+ * `${ensemble}` interpolation hook — different ensembles see different
+ * names without templating in the call site.
+ *
+ * @param opts.ensemble Ensemble name shown to the model in the first
+ *   line ("You are part of the …"). Pass `config.ensemble`.
+ */
+export declare function buildSdkSystemPrompt(opts: {
+    ensemble: string;
+}): string;
+/**
+ * Per-message augmentation appended to messages whose `isMaestro`
+ * field is `true`. The maestro flag identifies messages originating
+ * from a human operator at the dashboard (vs. ensemble-internal
+ * cues from other player sessions).
+ *
+ * Lifted verbatim from `src/adapters/copilot/adapter.ts:462`. Both
+ * copilot's poll-loop prompt-build and claude-code-headless's
+ * per-turn `buildPromptText` apply this conditionally per
+ * `m.isMaestro` — a human-from-dashboard message gets the ack
+ * directive; an ensemble-internal cue does not.
+ *
+ * The leading `\n\n` separates the directive from the human's
+ * message text inside the same prompt frame.
+ */
+export declare const MAESTRO_ACK = "\n\n[IMPORTANT: This message is from a human (Maestro). Immediately cue the sender back with a brief acknowledgment and your planned next step before doing the work.]";

package/dist/adapters/sdk/system-prompt.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Shared SDK-class adapter system-prompt helpers (#536).
+ *
+ * Two SDK-class adapters in this repo currently mirror an *identical*
+ * "use your MCP tools to reply" framing onto the model — copilot
+ * (`src/adapters/copilot/adapter.ts:283-297`) and, post-#536,
+ * claude-code-headless (`src/adapters/claude-code-headless/adapter.ts`).
+ * Pre-#536 the framing only existed on copilot's side, hand-typed
+ * inline; this module factors it out so:
+ *
+ *   - There is one canonical source for the prompt content (no copy
+ *     drift when someone tweaks the wording in one place and forgets
+ *     the other).
+ *   - The MAESTRO_ACK augmentation that copilot's poll loop applies
+ *     to human-from-dashboard messages is identifiable by name from
+ *     either adapter's prompt-build site.
+ *
+ * **Why not `buildServerInstructions` from `src/server-tools.ts`?**
+ * The other two SDK-class adapters (claude-api, opencode) DO use
+ * `buildServerInstructions` for their per-turn system prompt. Copilot
+ * predates that helper and ships its own inline framing with a more
+ * explicit "tools available" enumeration. Issue #536 directs
+ * claude-code-headless to mirror **copilot's** content (so the two
+ * adapters speak the same dialect to the model), not the canonical
+ * helper. A future consolidation pass could migrate ALL four SDK
+ * adapters onto `buildServerInstructions` — out of scope here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAESTRO_ACK = void 0;
+exports.buildSdkSystemPrompt = buildSdkSystemPrompt;
+/**
+ * SDK-class adapter system-prompt template, parameterized by ensemble.
+ *
+ * Lifted verbatim from `src/adapters/copilot/adapter.ts:283-297` (the
+ * pre-#536 inline `systemMessage.content`). Both copilot and
+ * claude-code-headless feed this into their per-turn invocation:
+ *   - copilot via `sessionConfig.systemMessage` to the SDK's
+ *     `createSession` call.
+ *   - claude-code-headless via `--append-system-prompt <content>` on
+ *     the per-turn `claude -p` argv.
+ *
+ * Returning a function (rather than a constant) preserves the
+ * `${ensemble}` interpolation hook — different ensembles see different
+ * names without templating in the call site.
+ *
+ * @param opts.ensemble Ensemble name shown to the model in the first
+ *   line ("You are part of the …"). Pass `config.ensemble`.
+ */
+function buildSdkSystemPrompt(opts) {
+    return (`You are part of the "${opts.ensemble}" ensemble coordinated via Temporal. ` +
+        `You have MCP tools available — ALWAYS use these tools directly, NEVER try to run them as shell commands:\n` +
+        `- set_name: Set your player name (call this FIRST if instructed)\n` +
+        `- ensemble: List active sessions\n` +
+        `- cue: Send a message to another player\n` +
+        `- set_part: Update your status/description\n` +
+        `- listen: Check for pending messages\n` +
+        `- recruit: Spawn a new player session\n` +
+        `- report: Report to the conductor\n` +
+        `- stop: Stop a session\n\n` +
+        `When you receive a message from another session, treat it like a coworker asking for help — respond promptly using your MCP tools.`);
+}
+/**
+ * Per-message augmentation appended to messages whose `isMaestro`
+ * field is `true`. The maestro flag identifies messages originating
+ * from a human operator at the dashboard (vs. ensemble-internal
+ * cues from other player sessions).
+ *
+ * Lifted verbatim from `src/adapters/copilot/adapter.ts:462`. Both
+ * copilot's poll-loop prompt-build and claude-code-headless's
+ * per-turn `buildPromptText` apply this conditionally per
+ * `m.isMaestro` — a human-from-dashboard message gets the ack
+ * directive; an ensemble-internal cue does not.
+ *
+ * The leading `\n\n` separates the directive from the human's
+ * message text inside the same prompt frame.
+ */
+exports.MAESTRO_ACK = '\n\n[IMPORTANT: This message is from a human (Maestro). Immediately cue the sender back with a brief acknowledgment and your planned next step before doing the work.]';

package/dist/adapters/terminal-error.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared terminal-class error classifier for adapter code (#249 Bug 4).
+ *
+ * The Temporal TS SDK conflates two terminal sub-kinds on pinned-runId
+ * signal/query failures:
+ *   (a) the closed run's specific runId no longer accepting traffic (CAN,
+ *       true COMPLETE, TERMINATED, FAILED), and
+ *   (b) the workflow id having been fully GC'd.
+ * Both surface as `WorkflowNotFoundError` with message
+ * "workflow execution already completed". This classifier says "yes, this is a
+ * terminal-class error" vs "transient, keep retrying" — it does NOT distinguish
+ * the sub-kinds. Callers that need sub-kind resolution consult
+ * `fetchHistory` (see {@link BaseAttachment.handleRunEndError}).
+ *
+ * **Extracted from `BaseAttachment.isTerminalErr` to break a code-duplication
+ * risk** — both the heartbeat/watcher ticks (in `base.ts`) and the delivery
+ * poller (in `claude-code/adapter.ts`) need to classify the same errors, and
+ * divergence between the two would re-create the #249 Bug 4 regression surface.
+ * One implementation, one import point.
+ *
+ * Uses name/message-sniffing rather than `instanceof` to tolerate the slightly
+ * different shapes errors take between `@temporalio/client` and the raw gRPC
+ * layer. The tradeoff is a narrow window where gRPC could add a new phrasing
+ * for the same error class — but that's caught by the existing adapter
+ * reconnect integration tests.
+ */
+export declare function isTerminalWorkflowError(err: unknown): boolean;

package/dist/adapters/terminal-error.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTerminalWorkflowError = isTerminalWorkflowError;
+/**
+ * Shared terminal-class error classifier for adapter code (#249 Bug 4).
+ *
+ * The Temporal TS SDK conflates two terminal sub-kinds on pinned-runId
+ * signal/query failures:
+ *   (a) the closed run's specific runId no longer accepting traffic (CAN,
+ *       true COMPLETE, TERMINATED, FAILED), and
+ *   (b) the workflow id having been fully GC'd.
+ * Both surface as `WorkflowNotFoundError` with message
+ * "workflow execution already completed". This classifier says "yes, this is a
+ * terminal-class error" vs "transient, keep retrying" — it does NOT distinguish
+ * the sub-kinds. Callers that need sub-kind resolution consult
+ * `fetchHistory` (see {@link BaseAttachment.handleRunEndError}).
+ *
+ * **Extracted from `BaseAttachment.isTerminalErr` to break a code-duplication
+ * risk** — both the heartbeat/watcher ticks (in `base.ts`) and the delivery
+ * poller (in `claude-code/adapter.ts`) need to classify the same errors, and
+ * divergence between the two would re-create the #249 Bug 4 regression surface.
+ * One implementation, one import point.
+ *
+ * Uses name/message-sniffing rather than `instanceof` to tolerate the slightly
+ * different shapes errors take between `@temporalio/client` and the raw gRPC
+ * layer. The tradeoff is a narrow window where gRPC could add a new phrasing
+ * for the same error class — but that's caught by the existing adapter
+ * reconnect integration tests.
+ */
+function isTerminalWorkflowError(err) {
+    const e = err;
+    const name = e?.name ?? '';
+    const msg = e?.message ?? '';
+    return (name.includes('WorkflowNotFound') ||
+        name.includes('WorkflowExecutionAlreadyCompleted') ||
+        msg.includes('WorkflowGone') ||
+        msg.includes('NOT_FOUND') ||
+        msg.includes('workflow execution already completed'));
+}

package/dist/channel.d.ts

@@ -0,0 +1,3 @@
+import { WorkflowHandle } from '@temporalio/client';
+import { Message } from './types';
+export declare function startMessagePoller(handle: WorkflowHandle, onMessages: (messages: Message[]) => Promise<void> | void): () => void;