@kata-sh/pi-symphony-extension 0.1.0

package/src/progress.test.ts

@@ -0,0 +1,175 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { describe, expect, it, vi } from "vitest";
+import { SYMPHONY_PROGRESS_FRAMES, withSymphonyLoader, withSymphonyProgress } from "./progress.ts";
+
+const borderedLoaderMocks = vi.hoisted(() => ({
+  constructorCalls: [] as Array<{ tui: unknown; theme: unknown; message: string; options: unknown }>,
+  instances: [] as Array<{ signal: AbortSignal; onAbort: (() => void) | undefined; abort: () => void }>,
+  signals: [] as AbortSignal[],
+}));
+
+vi.mock("@earendil-works/pi-coding-agent", () => ({
+  BorderedLoader: class MockBorderedLoader {
+    readonly controller: AbortController;
+    readonly signal: AbortSignal;
+    onAbort: (() => void) | undefined;
+
+    constructor(tui: unknown, theme: unknown, message: string, options?: unknown) {
+      this.controller = new AbortController();
+      this.signal = this.controller.signal;
+      borderedLoaderMocks.constructorCalls.push({ tui, theme, message, options });
+      borderedLoaderMocks.instances.push(this);
+      borderedLoaderMocks.signals.push(this.signal);
+    }
+
+    abort() {
+      this.controller.abort();
+      this.onAbort?.();
+    }
+  },
+}));
+
+function commandContext(options: { hasUI?: boolean } = {}) {
+  let resolveCustom: ((value: unknown) => void) | undefined;
+  const setWorkingIndicator = vi.fn();
+  const setWorkingMessage = vi.fn();
+  const setStatus = vi.fn();
+  const hasUI = options.hasUI ?? true;
+  const custom = vi.fn(async (factory: Parameters<ExtensionCommandContext["ui"]["custom"]>[0]) => {
+    const resultPromise = new Promise((resolve) => {
+      resolveCustom = resolve;
+    });
+    await factory(
+      {} as Parameters<typeof factory>[0],
+      {} as Parameters<typeof factory>[1],
+      {} as Parameters<typeof factory>[2],
+      (result: unknown) => {
+        resolveCustom?.(result);
+      },
+    );
+    return resultPromise;
+  });
+
+  const ctx = {
+    hasUI,
+    ui: { setWorkingIndicator, setWorkingMessage, setStatus, custom },
+  } as unknown as ExtensionCommandContext;
+
+  return { ctx, setWorkingIndicator, setWorkingMessage, setStatus, custom };
+}
+
+describe("withSymphonyProgress", () => {
+  it("sets indicator, message, and status, then restores after success", async () => {
+    const { ctx, setWorkingIndicator, setWorkingMessage, setStatus } = commandContext();
+    const restoreStatus = vi.fn();
+
+    const result = await withSymphonyProgress(ctx, { message: "Starting Symphony...", restoreStatus }, async () => "started");
+
+    expect(result).toBe("started");
+    expect(SYMPHONY_PROGRESS_FRAMES).toEqual(["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]);
+    expect(setWorkingIndicator).toHaveBeenNthCalledWith(1, { frames: SYMPHONY_PROGRESS_FRAMES, intervalMs: 120 });
+    expect(setWorkingMessage).toHaveBeenNthCalledWith(1, "Starting Symphony...");
+    expect(setStatus).toHaveBeenCalledWith("symphony", "Starting Symphony...");
+    expect(setWorkingIndicator).toHaveBeenNthCalledWith(2);
+    expect(setWorkingMessage).toHaveBeenNthCalledWith(2);
+    expect(restoreStatus).toHaveBeenCalledWith(ctx);
+    expect(setWorkingMessage.mock.invocationCallOrder[1]).toBeLessThan(restoreStatus.mock.invocationCallOrder[0]);
+  });
+
+  it("restores indicator, message, and status after failure", async () => {
+    const { ctx, setWorkingIndicator, setWorkingMessage } = commandContext();
+    const restoreStatus = vi.fn();
+
+    await expect(
+      withSymphonyProgress(ctx, { message: "Refreshing Symphony...", restoreStatus }, async () => {
+        throw new Error("refresh failed");
+      }),
+    ).rejects.toThrow("refresh failed");
+
+    expect(setWorkingIndicator).toHaveBeenNthCalledWith(2);
+    expect(setWorkingMessage).toHaveBeenNthCalledWith(2);
+    expect(restoreStatus).toHaveBeenCalledWith(ctx);
+  });
+});
+
+describe("withSymphonyLoader", () => {
+  it("shows a bordered loader, passes its AbortSignal, restores status, and returns the operation result", async () => {
+    borderedLoaderMocks.constructorCalls.length = 0;
+    borderedLoaderMocks.instances.length = 0;
+    borderedLoaderMocks.signals.length = 0;
+    const { ctx, setStatus, custom } = commandContext();
+    const restoreStatus = vi.fn();
+    const operation = vi.fn(async (signal: AbortSignal) => {
+      expect(signal).toBe(borderedLoaderMocks.signals[0]);
+      return "attached";
+    });
+
+    const result: string | undefined = await withSymphonyLoader(ctx, { message: "Attaching Symphony...", restoreStatus }, operation);
+
+    expect(result).toBe("attached");
+    expect(setStatus).toHaveBeenCalledWith("symphony", "Attaching Symphony...");
+    expect(custom).toHaveBeenCalledOnce();
+    expect(borderedLoaderMocks.constructorCalls).toHaveLength(1);
+    expect(borderedLoaderMocks.constructorCalls[0]?.message).toBe("Attaching Symphony...");
+    expect(operation).toHaveBeenCalledWith(expect.any(AbortSignal));
+    expect(restoreStatus).toHaveBeenCalledWith(ctx);
+  });
+
+  it("closes the custom loader promptly when cancelled", async () => {
+    borderedLoaderMocks.constructorCalls.length = 0;
+    borderedLoaderMocks.instances.length = 0;
+    borderedLoaderMocks.signals.length = 0;
+    const { ctx } = commandContext();
+    const restoreStatus = vi.fn();
+    const operation = vi.fn(() => new Promise<string>(() => {}));
+
+    const resultPromise = withSymphonyLoader(ctx, { message: "Cancelling Symphony...", restoreStatus }, operation);
+
+    await vi.waitFor(() => expect(operation).toHaveBeenCalledOnce());
+    const loader = borderedLoaderMocks.instances[0];
+    expect(loader).toBeDefined();
+
+    loader?.abort();
+
+    const result = await resultPromise;
+
+    expect(result).toBeUndefined();
+    expect(operation).toHaveBeenCalledWith(loader?.signal);
+    expect(loader?.signal.aborted).toBe(true);
+    expect(restoreStatus).toHaveBeenCalledWith(ctx);
+  });
+
+  it("runs the operation without calling custom when UI is unavailable", async () => {
+    const { ctx, setStatus, custom } = commandContext({ hasUI: false });
+    const restoreStatus = vi.fn();
+    const operation = vi.fn(async (signal: AbortSignal) => {
+      expect(signal).toBeInstanceOf(AbortSignal);
+      expect(signal.aborted).toBe(false);
+      return "initialized";
+    });
+
+    const result = await withSymphonyLoader(ctx, { message: "Initializing Symphony...", restoreStatus }, operation);
+
+    expect(result).toBe("initialized");
+    expect(setStatus).toHaveBeenCalledWith("symphony", "Initializing Symphony...");
+    expect(custom).not.toHaveBeenCalled();
+    expect(operation).toHaveBeenCalledWith(expect.any(AbortSignal));
+    expect(restoreStatus).toHaveBeenCalledWith(ctx);
+  });
+
+  it("restores status and propagates loader operation failures", async () => {
+    borderedLoaderMocks.constructorCalls.length = 0;
+    borderedLoaderMocks.instances.length = 0;
+    borderedLoaderMocks.signals.length = 0;
+    const { ctx } = commandContext();
+    const restoreStatus = vi.fn();
+
+    await expect(
+      withSymphonyLoader(ctx, { message: "Stopping Symphony...", restoreStatus }, async () => {
+        throw new Error("stop failed");
+      }),
+    ).rejects.toThrow("stop failed");
+
+    expect(restoreStatus).toHaveBeenCalledWith(ctx);
+  });
+});

package/src/progress.ts

@@ -0,0 +1,75 @@
+import { BorderedLoader, type ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+export const SYMPHONY_PROGRESS_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+export interface SymphonyProgressOptions {
+  message: string;
+  restoreStatus: (ctx: ExtensionCommandContext) => void;
+}
+
+export async function withSymphonyProgress<T>(
+  ctx: ExtensionCommandContext,
+  options: SymphonyProgressOptions,
+  fn: (signal: AbortSignal) => T | Promise<T>,
+): Promise<T> {
+  const controller = new AbortController();
+  ctx.ui.setWorkingIndicator({ frames: SYMPHONY_PROGRESS_FRAMES, intervalMs: 120 });
+  ctx.ui.setWorkingMessage(options.message);
+  ctx.ui.setStatus("symphony", options.message);
+
+  try {
+    return await fn(controller.signal);
+  } finally {
+    ctx.ui.setWorkingIndicator();
+    ctx.ui.setWorkingMessage();
+    options.restoreStatus(ctx);
+  }
+}
+
+export async function withSymphonyLoader<T>(
+  ctx: ExtensionCommandContext,
+  options: SymphonyProgressOptions,
+  fn: (signal: AbortSignal) => T | Promise<T>,
+): Promise<T | undefined> {
+  ctx.ui.setStatus("symphony", options.message);
+
+  try {
+    if (!ctx.hasUI) {
+      const controller = new AbortController();
+      return await fn(controller.signal);
+    }
+
+    let operationFailed = false;
+    let operationError: unknown;
+
+    const result = await ctx.ui.custom<T | undefined>((tui, theme, _keybindings, done) => {
+      const loader = new BorderedLoader(tui, theme, options.message);
+      let completed = false;
+      const complete = (value: T | undefined) => {
+        if (completed) return;
+        completed = true;
+        done(value);
+      };
+
+      loader.onAbort = () => complete(undefined);
+
+      void Promise.resolve()
+        .then(() => fn(loader.signal))
+        .then(
+          (value) => complete(value),
+          (error: unknown) => {
+            if (completed) return;
+            operationFailed = true;
+            operationError = error;
+            complete(undefined);
+          },
+        );
+      return loader;
+    });
+
+    if (operationFailed) throw operationError;
+    return result;
+  } finally {
+    options.restoreStatus(ctx);
+  }
+}

package/src/runtime-helpers.ts

@@ -0,0 +1,11 @@
+import { SymphonyExtensionError } from "./errors.ts";
+import type { SymphonyRuntime } from "./runtime.ts";
+
+export async function cleanupAbortedStart(runtime: SymphonyRuntime, baseUrl: string): Promise<void> {
+  try {
+    await runtime.processManager.stopOwned();
+  } catch (error) {
+    if (!(error instanceof SymphonyExtensionError && error.kind === "not_owned")) throw error;
+  }
+  runtime.clearAttachmentIfBaseUrl(baseUrl);
+}

package/src/runtime.test.ts

@@ -0,0 +1,237 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { SymphonyStateResponse } from "./http-client.ts";
+import { SymphonyRuntime } from "./runtime.ts";
+import { STATE_ENTRY_TYPE, type LastKnownSymphonyState } from "./state.ts";
+
+function contextWithEntries(entries: unknown[]): ExtensionContext {
+  return {
+    sessionManager: {
+      getEntries: () => entries,
+    },
+  } as unknown as ExtensionContext;
+}
+
+function lastKnownState(baseUrl: string): LastKnownSymphonyState {
+  return {
+    baseUrl,
+    runningCount: 1,
+    retryCount: 0,
+    blockedCount: 0,
+    completedCount: 2,
+    pollingChecking: false,
+    nextPollInMs: 1000,
+    updatedAt: "2026-05-14T00:00:01.000Z",
+  };
+}
+
+function stateResponse(overrides: Partial<SymphonyStateResponse> = {}): SymphonyStateResponse {
+  return {
+    running: {},
+    retry_queue: [],
+    blocked: [],
+    completed: [],
+    polling: { checking: false, next_poll_in_ms: 1000, poll_interval_ms: 30000 },
+    shared_context: { total_entries: 0, entries_by_scope: {}, oldest_entry_at: null, newest_entry_at: null },
+    supervisor: { active: true, steers_issued: 0, conflicts_detected: 0, patterns_detected: 0, escalations_created: 0 },
+    codex_totals: { input_tokens: 0, output_tokens: 0, total_tokens: 0, event_count: 0, seconds_running: 0 },
+    codex_rate_limits: null,
+    ...overrides,
+  };
+}
+
+describe("SymphonyRuntime", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("clears the active attachment and last known state", () => {
+    const runtime = new SymphonyRuntime();
+    const baseUrl = "http://127.0.0.1:8080";
+    runtime.state.attachedBaseUrl = baseUrl;
+    runtime.state.lastKnownState = lastKnownState(baseUrl);
+    runtime.client = {} as SymphonyRuntime["client"];
+
+    expect(runtime.clearAttachmentIfBaseUrl("http://127.0.0.1:8081")).toBe(false);
+    expect(runtime.state.attachedBaseUrl).toBe(baseUrl);
+
+    expect(runtime.clearAttachmentIfBaseUrl(baseUrl)).toBe(true);
+    expect(runtime.state.attachedBaseUrl).toBeUndefined();
+    expect(runtime.state.lastKnownState).toBeUndefined();
+    expect(runtime.client).toBeUndefined();
+  });
+
+  it("keeps restored state shared with the process manager", async () => {
+    const runtime = new SymphonyRuntime();
+
+    runtime.restore(
+      contextWithEntries([
+        {
+          type: "custom",
+          customType: STATE_ENTRY_TYPE,
+          data: {
+            attachedBaseUrl: "http://127.0.0.1:8080",
+            ownedProcess: {
+              pid: 123,
+              command: "symphony --no-tui",
+              cwd: "/repo",
+              baseUrl: "http://127.0.0.1:8080",
+              startedAt: "2026-05-14T00:00:00.000Z",
+            },
+          },
+        },
+      ]),
+    );
+
+    expect(runtime.state.ownedProcess?.pid).toBe(123);
+
+    await expect(runtime.processManager.stopOwned()).rejects.toMatchObject({ kind: "not_owned" });
+    expect(runtime.state.ownedProcess).toBeUndefined();
+  });
+
+  it("keeps the latest raw Symphony state after refresh", async () => {
+    const runtime = new SymphonyRuntime();
+    const response = stateResponse({ tracker_project_url: "https://linear.app/kata-sh/project/symphony" });
+    runtime.client = {
+      getState: vi.fn(async () => response),
+      toHealthSummary: vi.fn(() => lastKnownState("http://127.0.0.1:8080")),
+    } as unknown as SymphonyRuntime["client"];
+
+    await expect(runtime.refreshState()).resolves.toBe(response);
+
+    expect(runtime.lastState).toBe(response);
+    expect(runtime.state.lastKnownState?.runningCount).toBe(1);
+  });
+
+  it("clears recent events when attaching to a new server", async () => {
+    const runtime = new SymphonyRuntime();
+    runtime.recordEvent({ version: "v1", sequence: 1, timestamp: "2026-05-14T12:00:00Z", kind: "worker", severity: "error", event: "worker_failed", payload: {} });
+    const response = stateResponse({ tracker_project_url: "https://linear.app/kata-sh/project/symphony" });
+    const fetchStub: typeof fetch = async () =>
+      ({
+        ok: true,
+        status: 200,
+        text: async () => JSON.stringify(response),
+      }) as unknown as Response;
+    vi.stubGlobal("fetch", fetchStub);
+
+    await expect(runtime.attach("http://127.0.0.1:8080")).resolves.toEqual(response);
+
+    expect(runtime.recentEvents).toEqual([]);
+  });
+
+  it("requests a refresh before fetching the latest state", async () => {
+    const runtime = new SymphonyRuntime();
+    const calls: string[] = [];
+    const response = stateResponse();
+    runtime.client = {
+      refresh: vi.fn(async () => {
+        calls.push("refresh");
+        return { queued: true, coalesced: false, pendingRequests: 1 };
+      }),
+      getState: vi.fn(async () => {
+        calls.push("getState");
+        return response;
+      }),
+      toHealthSummary: vi.fn(() => lastKnownState("http://127.0.0.1:8080")),
+    } as unknown as SymphonyRuntime["client"];
+
+    await runtime.requestRefresh();
+
+    expect(calls).toEqual(["refresh", "getState"]);
+    expect(runtime.lastState).toBe(response);
+  });
+
+  it("steers a worker and refreshes state", async () => {
+    const runtime = new SymphonyRuntime();
+    const response = stateResponse();
+    runtime.client = {
+      steer: vi.fn(async () => ({ ok: true, issueId: "issue-123", issueIdentifier: "SIM-123", delivered: true, instructionPreview: "Use auth" })),
+      getState: vi.fn(async () => response),
+      toHealthSummary: vi.fn(() => lastKnownState("http://127.0.0.1:8080")),
+    } as unknown as SymphonyRuntime["client"];
+
+    await expect(runtime.steerWorker("SIM-123", "Use auth")).resolves.toMatchObject({ delivered: true });
+
+    expect(runtime.client?.steer).toHaveBeenCalledWith("SIM-123", "Use auth", undefined);
+    expect(runtime.client?.getState).toHaveBeenCalledOnce();
+  });
+
+  it("returns steer result even if post-steer refresh fails", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    const runtime = new SymphonyRuntime();
+    runtime.client = {
+      steer: vi.fn(async () => ({ ok: true, issueId: "issue-123", issueIdentifier: "SIM-123", delivered: true, instructionPreview: "Use auth" })),
+      getState: vi.fn(async () => {
+        throw new Error("temporary state fetch failure");
+      }),
+      toHealthSummary: vi.fn(() => lastKnownState("http://127.0.0.1:8080")),
+    } as unknown as SymphonyRuntime["client"];
+
+    await expect(runtime.steerWorker("SIM-123", "Use auth")).resolves.toMatchObject({ delivered: true });
+
+    expect(runtime.client?.steer).toHaveBeenCalledWith("SIM-123", "Use auth", undefined);
+    expect(runtime.client?.getState).toHaveBeenCalledOnce();
+    expect(warn).toHaveBeenCalledWith("Symphony state refresh failed after steer", expect.any(Error));
+  });
+
+  it("responds to an escalation and refreshes state", async () => {
+    const runtime = new SymphonyRuntime();
+    const response = stateResponse();
+    const escalationResponse = { ok: true };
+    const escalationDecision = { approved: true };
+    runtime.client = {
+      respondEscalation: vi.fn(async () => escalationResponse),
+      getState: vi.fn(async () => response),
+      toHealthSummary: vi.fn(() => lastKnownState("http://127.0.0.1:8080")),
+    } as unknown as SymphonyRuntime["client"];
+
+    await expect(runtime.respondToEscalation("esc-1", escalationDecision)).resolves.toEqual({ ok: true });
+
+    expect(runtime.client?.respondEscalation).toHaveBeenCalledWith("esc-1", escalationDecision, "pi-dashboard", undefined);
+    expect(runtime.client?.getState).toHaveBeenCalledOnce();
+    expect(runtime.lastState).toBe(response);
+  });
+
+  it("returns escalation response result even if post-response refresh fails", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    const runtime = new SymphonyRuntime();
+    runtime.client = {
+      respondEscalation: vi.fn(async () => ({ ok: true })),
+      getState: vi.fn(async () => {
+        throw new Error("temporary state fetch failure");
+      }),
+      toHealthSummary: vi.fn(() => lastKnownState("http://127.0.0.1:8080")),
+    } as unknown as SymphonyRuntime["client"];
+
+    await expect(runtime.respondToEscalation("esc-1", "approved")).resolves.toEqual({ ok: true });
+
+    expect(runtime.client?.respondEscalation).toHaveBeenCalledWith("esc-1", "approved", "pi-dashboard", undefined);
+    expect(runtime.client?.getState).toHaveBeenCalledOnce();
+    expect(warn).toHaveBeenCalledWith("Symphony state refresh failed after escalation response", expect.any(Error));
+  });
+
+  it("retains recent escalation lifecycle events", () => {
+    const runtime = new SymphonyRuntime();
+
+    runtime.recordEvent({ version: "v1", sequence: 1, timestamp: "2026-05-14T12:00:00Z", kind: "escalation_created", severity: "info", event: "escalation_created", payload: {} });
+    runtime.recordEvent({ version: "v1", sequence: 2, timestamp: "2026-05-14T12:00:01Z", kind: "escalation_responded", severity: "info", event: "escalation_responded", payload: {} });
+    runtime.recordEvent({ version: "v1", sequence: 3, timestamp: "2026-05-14T12:00:02Z", kind: "heartbeat", severity: "info", event: "heartbeat", payload: {} });
+
+    expect(runtime.recentEvents.map((event) => event.kind)).toEqual(["escalation_created", "escalation_responded"]);
+  });
+
+  it("retains the most recent worker and runtime events", () => {
+    const runtime = new SymphonyRuntime();
+
+    runtime.recordEvent({ version: "v1", sequence: 1, timestamp: "2026-05-14T12:00:00Z", kind: "heartbeat", severity: "info", event: "heartbeat", payload: {} });
+    for (let sequence = 2; sequence <= 27; sequence += 1) {
+      runtime.recordEvent({ version: "v1", sequence, timestamp: `2026-05-14T12:00:${String(sequence).padStart(2, "0")}Z`, kind: sequence % 2 === 0 ? "worker" : "runtime", severity: "info", event: "event", payload: {} });
+    }
+
+    expect(runtime.recentEvents).toHaveLength(20);
+    expect(runtime.recentEvents[0]?.sequence).toBe(8);
+    expect(runtime.recentEvents.at(-1)?.sequence).toBe(27);
+  });
+});

package/src/runtime.ts

@@ -0,0 +1,119 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { resolveSymphonyBinary } from "./binary-resolver.ts";
+import { formatError, SymphonyExtensionError } from "./errors.ts";
+import { SymphonyHttpClient, type EscalationRespondResponse, type SteerResponse, type SymphonyEventEnvelope, type SymphonyStateResponse } from "./http-client.ts";
+import { SymphonyProcessManager } from "./process-manager.ts";
+import {
+  createDefaultState,
+  restoreStateFromEntries,
+  snapshotStateForPersistence,
+  STATE_ENTRY_TYPE,
+  type ExtensionState,
+} from "./state.ts";
+
+export class SymphonyRuntime {
+  state: ExtensionState = createDefaultState();
+  processManager = new SymphonyProcessManager(this.state);
+  client?: SymphonyHttpClient;
+  lastState?: SymphonyStateResponse;
+  recentEvents: SymphonyEventEnvelope[] = [];
+
+  restore(ctx: ExtensionContext): void {
+    this.state = restoreStateFromEntries(ctx.sessionManager.getEntries());
+    this.processManager = new SymphonyProcessManager(this.state);
+    this.client = this.state.attachedBaseUrl ? new SymphonyHttpClient(this.state.attachedBaseUrl) : undefined;
+  }
+
+  persist(pi: { appendEntry: (customType: string, data?: unknown) => void }): void {
+    pi.appendEntry(STATE_ENTRY_TYPE, snapshotStateForPersistence(this.state));
+  }
+
+  async resolveBinary(ctx: ExtensionContext): Promise<string> {
+    return resolveSymphonyBinary({
+      cwd: ctx.cwd,
+      state: this.state,
+      promptForPath: ctx.hasUI
+        ? async () => ctx.ui.input("Symphony binary", "Absolute path to symphony executable")
+        : async () => undefined,
+    });
+  }
+
+  async attach(baseUrl: string, signal?: AbortSignal): Promise<SymphonyStateResponse> {
+    const client = new SymphonyHttpClient(baseUrl);
+    const state = await client.verify(signal);
+    this.client = client;
+    this.lastState = state;
+    this.recentEvents = [];
+    this.state.attachedBaseUrl = client.baseUrl;
+    this.state.lastKnownState = client.toHealthSummary(state);
+    return state;
+  }
+
+  clearAttachment(): void {
+    this.client = undefined;
+    this.state.attachedBaseUrl = undefined;
+    this.state.lastKnownState = undefined;
+    this.lastState = undefined;
+    this.recentEvents = [];
+  }
+
+  clearAttachmentIfBaseUrl(baseUrl: string | undefined): boolean {
+    if (!baseUrl || this.state.attachedBaseUrl !== baseUrl) return false;
+    this.clearAttachment();
+    return true;
+  }
+
+  async refreshState(signal?: AbortSignal): Promise<SymphonyStateResponse> {
+    if (!this.client) throw new SymphonyExtensionError("no_attachment", "No Symphony server is attached");
+    const state = await this.client.getState(signal);
+    this.lastState = state;
+    this.state.lastKnownState = this.client.toHealthSummary(state);
+    return state;
+  }
+
+  async requestRefresh(signal?: AbortSignal): Promise<SymphonyStateResponse> {
+    if (!this.client) throw new SymphonyExtensionError("no_attachment", "No Symphony server is attached");
+    await this.client.refresh(signal);
+    return this.refreshState(signal);
+  }
+
+  async steerWorker(issueIdentifier: string, instruction: string, signal?: AbortSignal): Promise<SteerResponse> {
+    if (!this.client) throw new SymphonyExtensionError("no_attachment", "No Symphony server is attached");
+    const result = await this.client.steer(issueIdentifier, instruction, signal);
+    try {
+      await this.refreshState(signal);
+    } catch (error) {
+      console.warn("Symphony state refresh failed after steer", error);
+    }
+    return result;
+  }
+
+  async respondToEscalation(requestId: string, response: unknown, signal?: AbortSignal): Promise<EscalationRespondResponse> {
+    if (!this.client) throw new SymphonyExtensionError("no_attachment", "No Symphony server is attached");
+    const result = await this.client.respondEscalation(requestId, response, "pi-dashboard", signal);
+    try {
+      await this.refreshState(signal);
+    } catch (error) {
+      console.warn("Symphony state refresh failed after escalation response", error);
+    }
+    return result;
+  }
+
+  recordEvent(event: SymphonyEventEnvelope): void {
+    if (event.kind !== "worker" && event.kind !== "runtime" && !event.kind.startsWith("escalation_")) return;
+    this.recentEvents = [...this.recentEvents, event].slice(-20);
+  }
+
+  statusText(): string {
+    const attached = this.state.attachedBaseUrl ? `attached: ${this.state.attachedBaseUrl}` : "attached: no";
+    const owned = this.state.ownedProcess ? `owned pid: ${this.state.ownedProcess.pid}` : "owned pid: none";
+    const last = this.state.lastKnownState
+      ? `running ${this.state.lastKnownState.runningCount}, retry ${this.state.lastKnownState.retryCount}, blocked ${this.state.lastKnownState.blockedCount}, completed ${this.state.lastKnownState.completedCount}`
+      : "state: unknown";
+    return `Symphony status\n${attached}\n${owned}\n${last}`;
+  }
+
+  errorText(error: unknown): string {
+    return formatError(error);
+  }
+}