@scrylog/cli 0.1.0

package/src/daemon/collectors/opencode/README.md

@@ -0,0 +1,106 @@
+# OpenCode Collector
+
+Monitors OpenCode sessions by connecting to running OpenCode instances via the
+`@opencode-ai/sdk` HTTP client. Uses SSE live events as the primary transport
+with HTTP polling as a fallback.
+
+## Data Flow
+
+```
+                          config.opencode.instances[]
+                                   │
+                                   │
+         ┌─────────────────────────▼──────────────────────────┐
+         │                     discovery                      │
+         │   discoverInstances()  │  parseOpencodeUrl()       │
+         │   discoverListeningPort()  │  findOpencodeInTree() │
+         └─────────────────────────┬──────────────────────────┘
+                                   │  DiscoveredInstance[]
+                                   │
+                                   ▼
+  ┌──────────────────────────────────────────────────────────────────┐
+  │                         collector.ts                             │
+  │                                                                  │
+  │   ┌───────────────┐            ┌───────────────────────────┐   │
+  │   │  60s refresh()│            │  SSE event.subscribe()    │   │
+  │   │  discover +   │            │                           │   │
+  │   │  connectInstance() ┌─────►│  session.status           │   │
+  │   └───────┬───────┘    │       │  session.updated/created  │   │
+  │           │            │       │  permission.updated       │   │
+  │           │    ┌───────┴───────┤  permission.replied       │   │
+  │           │    │ poll fallback │  session.deleted          │   │
+  │           │    │ (10s)         │  session.error            │   │
+  │           │    └───────┬───────┘                           │   │
+  │           │            │                                   │   │
+  │           │            ▼                                   │   │
+  │           │    ┌─────────────────┐                         │   │
+  │           └───►│ session-builder │  buildSessionModel()    │   │
+  │                │                 │  mapSessionStatus()     │   │
+  │                └────────┬────────┘                         │   │
+  │                         │                                   │   │
+  │                         ▼                                   │   │
+  │              store.upsertSession()                            │   │
+  │              store.syncChildSessionIds()                      │   │
+  │              store.registerSdkPid()                         │   │
+  └──────────────────────────────────────────────────────────────────┘
+         │
+         ▼
+    DaemonStore ──► /api/events SSE ──► TUI
+```
+
+## Modules
+
+| File | Responsibility | Key Exports |
+|------|-------------|-------------|
+| `discovery.ts` | Auto-discover OpenCode processes via `ps`, resolve ephemeral ports with `lsof`, parse command-line URLs | `discoverInstances()`, `parseOpencodeUrl()`, `hasExplicitPort()`, `discoverListeningPort()`, `findOpencodeInTree()`, `clearPidPortCache()`, `DiscoveredInstance` |
+| `session-builder.ts` | Map SDK `Session` + `SessionStatus` → `SessionModel`; compute `state` and `hasAttention` from pending permissions/questions | `buildSessionModel()`, `mapSessionStatus()`, `InstanceState` |
+| `collector.ts` | Maintain instance connections; subscribe to SSE; handle reconnects and poll fallback; dispatch events to `session-builder` | `OpenCodeCollector` (implements `Collector`) |
+| `index.ts` | Public re-exports | `OpenCodeCollector`, discovery + session-builder functions |
+
+## State Mapping (`session-builder.ts`)
+
+| SDK `SessionStatus` | State | Attention |
+|---------------------|-------|-----------|
+| `busy` | `working` | `false` |
+| `idle` | `idle` | `false` |
+| `retry` | `working` | `false` |
+| *(any + pending permission/question)* | `waiting-input` | `true` |
+
+## Transports
+
+| Transport | Trigger | Events Handled |
+|-----------|---------|----------------|
+| **SSE** | Primary. Established on `connectInstance()`. | `session.status`, `session.updated`, `session.created`, `session.deleted`, `session.idle`, `session.error`, `permission.updated`, `permission.replied` |
+| **Poll** | Fallback. Triggered when SSE disconnects or `connectInstance()` fails. | Fetches full session list + status map every 10s. |
+
+The collector seeds pending permissions on initial connect by calling the
+(optional) `permission.list` SDK endpoint. This avoids stale "waiting-input"
+states before the first SSE event arrives.
+
+## Instance Lifecycle
+
+```
+  discovered  ──►  connectInstance()  ──►  subscribeSSE()
+       │                                          │
+       │                                          ▼ (on disconnect/error)
+       │                              startPollFallback() ──►  pollInstance()
+       │                                          │
+       │                                          ▼ (on re-connect)
+       │                              stop poll timer ──► subscribeSSE()
+       │                                          │
+       └──────────────────────────────────────────┘
+              teardownInstance() on instance gone
+```
+
+## Interactions
+
+| Component | How |
+|-----------|-----|
+| `GitCollector` | Resolves `session.directory` → `project` in `buildSessionModel()` |
+| `TmuxCollector` | Uses `parseOpencodeUrl()` to derive instance URLs from pane process trees; uses `store.registerSdkPid()` results for PID-ancestry matching |
+| `DaemonStore` | Upserts sessions; registers SDK PIDs for tmux deduplication; rebuilds parent→child links |
+| `Scheduler` | Calls `start()` → sets up `60s` discovery interval |
+
+## Detection Source Produced
+
+- `"opencode-sdk"` — session discovered and maintained via `@opencode-ai/sdk` HTTP/SSE

package/src/daemon/collectors/opencode/collector.ts

@@ -0,0 +1,543 @@
+import type { ScrylogConfig } from "../../../shared/config";
+import type { SessionModel, SessionState } from "../../../shared/types";
+import type { DaemonStore } from "../../store";
+import type { Collector } from "../../scheduler";
+import type { Logger } from "../../../shared/logger";
+import { NOOP_LOGGER } from "../../../shared/logger";
+import { createOpencodeClient } from "@opencode-ai/sdk";
+import type { Session, SessionStatus } from "@opencode-ai/sdk";
+import type { GitCollector } from "../git";
+import { discoverInstances, type DiscoveredInstance, clearPidPortCache } from "./discovery";
+import { buildSessionModel, type InstanceState } from "./session-builder";
+
+// ── Collector ─────────────────────────────────────────────────────────────────
+
+export class OpenCodeCollector implements Collector {
+  name = "opencode";
+  private instances: InstanceState[] = [];
+  private store?: DaemonStore;
+  private config?: ScrylogConfig;
+  private logger: Logger = NOOP_LOGGER;
+  private discoveryTimer?: ReturnType<typeof setInterval>;
+  private gitCollector?: GitCollector;
+  private refreshing = false;
+  private skippedRefreshes = 0;
+  private errorCount = 0;
+
+  constructor(gitCollector?: GitCollector) {
+    this.gitCollector = gitCollector;
+  }
+
+  async start(store: DaemonStore, config: ScrylogConfig, logger: Logger): Promise<void> {
+    this.store = store;
+    this.config = config;
+    this.logger = logger;
+
+    if (config.opencode.instances.length > 0) {
+      logger.info("opencode", "Collector started — using configured instances", {
+        event: "collector.started",
+        collector: this.name,
+        instances: config.opencode.instances,
+      });
+    } else if (config.opencode.autoDiscover) {
+      logger.info("opencode", "Collector started — auto-discover enabled", { event: "collector.started", collector: this.name, autoDiscover: true });
+    } else {
+      logger.info("opencode", "Collector started — discovery disabled (no instances configured, autoDiscover=false)", { event: "collector.started", collector: this.name, autoDiscover: false });
+    }
+
+    await this.safeRefresh();
+
+    // Re-discover instances periodically (in case opencode starts later)
+    this.discoveryTimer = setInterval(() => void this.safeRefresh(), 60_000);
+  }
+
+  async stop(): Promise<void> {
+    if (this.discoveryTimer) {
+      clearInterval(this.discoveryTimer);
+    }
+
+    for (const inst of this.instances) {
+      this.teardownInstance(inst);
+    }
+    this.instances = [];
+
+    this.logger.info("opencode", "Collector stopped", { event: "collector.stopped", collector: this.name });
+  }
+
+  // ── Internal ───────────────────────────────────────────────────────────────
+
+  private async safeRefresh(): Promise<void> {
+    const store = this.store!;
+    if (this.refreshing) {
+      this.skippedRefreshes += 1;
+      store.setCollectorStatus(this.name, { skippedPolls: this.skippedRefreshes });
+      return;
+    }
+    this.refreshing = true;
+    const startedAt = Date.now();
+    try {
+      await this.refresh();
+      store.setCollectorStatus(this.name, { lastDurationMs: Date.now() - startedAt, skippedPolls: this.skippedRefreshes, errorCount: this.errorCount });
+    } finally {
+      this.refreshing = false;
+    }
+  }
+
+  private async refresh(): Promise<void> {
+    const config = this.config!;
+    const discovered: DiscoveredInstance[] = [];
+
+    if (config.opencode.instances.length > 0) {
+      for (const url of config.opencode.instances) {
+        discovered.push({ url });
+      }
+      this.logger.debug("opencode", "Using configured instances", { urls: config.opencode.instances });
+    } else if (config.opencode.autoDiscover) {
+      discovered.push(...discoverInstances(this.logger, config.daemon.commandTimeoutMs));
+    }
+
+    // Connect to new instances
+    const existingUrls = new Set(this.instances.map((i) => i.url));
+    for (const disc of discovered) {
+      if (!existingUrls.has(disc.url)) {
+        this.logger.debug("opencode", "Connecting to new instance", { url: disc.url, pid: disc.pid });
+        const inst: InstanceState = {
+          url: disc.url,
+          pid: disc.pid,
+          sessions: new Map(),
+          status: new Map(),
+          pendingPermissions: new Map(),
+          pendingQuestions: new Map(),
+        };
+        this.instances.push(inst);
+        void this.connectInstance(inst);
+      }
+    }
+
+    // Tear down instances no longer discovered
+    const discoveredUrls = new Set(discovered.map((d) => d.url));
+    for (const inst of this.instances) {
+      if (!discoveredUrls.has(inst.url)) {
+        this.logger.debug("opencode", "Removing instance no longer discovered", { url: inst.url });
+        this.teardownInstance(inst);
+        this.instances = this.instances.filter((i) => i.url !== inst.url);
+      }
+    }
+  }
+
+  private async connectInstance(inst: InstanceState): Promise<void> {
+    const store = this.store!;
+    this.logger.info("opencode", "Connecting to instance", { event: "integration.connecting", instanceUrl: inst.url });
+
+    try {
+      const client = createOpencodeClient({ baseUrl: inst.url });
+
+      // Load initial sessions
+      const listResult = await client.session.list({ throwOnError: false });
+      if (!listResult.data) {
+        this.logger.warn("opencode", "Instance returned no session data", { event: "integration.invalid_response", instanceUrl: inst.url });
+        return;
+      }
+
+      const sessions = (listResult.data as Session[]) ?? [];
+
+      const statusMapResult = await client.session.status({ throwOnError: false });
+      const statusMap = (statusMapResult.data as { [key: string]: SessionStatus } | undefined) ?? {};
+
+      // Seed pending permissions on connect
+      let pendingSeedCount = 0;
+      try {
+        // Use dynamic access since permission API may not exist on all SDK versions
+        const permClient = (client as unknown as Record<string, { list: (opts: unknown) => Promise<{ data?: unknown }> }>)["permission"];
+        if (permClient?.list) {
+          const permResult = await permClient.list({ throwOnError: false });
+          const pending = (permResult.data as Array<{ id: string; sessionID: string }> | undefined) ?? [];
+          for (const req of pending) {
+            if (!inst.pendingPermissions.has(req.sessionID)) {
+              inst.pendingPermissions.set(req.sessionID, new Set());
+            }
+            inst.pendingPermissions.get(req.sessionID)!.add(req.id);
+            pendingSeedCount++;
+          }
+          if (pendingSeedCount > 0) {
+            this.logger.debug("opencode", "Seeded pending permissions on connect", { url: inst.url, count: pendingSeedCount });
+          }
+        }
+      } catch {
+        // permission.list may not exist on older opencode versions; ignore
+      }
+
+      for (const session of sessions) {
+        const status: SessionStatus = statusMap[session.id] ?? { type: "idle" };
+        const model = buildSessionModel(session, status, inst.url, inst.pendingPermissions, inst.pendingQuestions, this.gitCollector);
+        inst.sessions.set(session.id, model);
+        inst.status.set(session.id, status);
+        store.upsertSession(model);
+      }
+
+      // Rebuild parent→child links after initial load
+      store.syncChildSessionIds();
+
+      // Register PID in store for PID-ancestry dedup
+      if (inst.pid) {
+        store.registerSdkPid(inst.pid, inst.url);
+      }
+
+      this.logger.info("opencode", "Connected to instance", {
+        event: "integration.connected",
+        instanceUrl: inst.url,
+        sessions: sessions.length,
+        pendingPermissions: pendingSeedCount,
+      });
+
+      store.setCollectorStatus(this.name, { running: true, lastRunAt: Date.now() });
+
+      // Subscribe to SSE events
+      this.subscribeSSE(inst, client);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      this.logger.warn("opencode", "Failed to connect to instance", { event: "integration.connect_failed", instanceUrl: inst.url, errorMessage: msg });
+      store.setCollectorStatus(this.name, { lastError: msg });
+      // Start polling fallback
+      this.startPollFallback(inst);
+    }
+  }
+
+  private subscribeSSE(
+    inst: InstanceState,
+    client: ReturnType<typeof createOpencodeClient>,
+  ): void {
+    const store = this.store!;
+    const abort = new AbortController();
+    inst.sseAbort = abort;
+
+    const connect = async () => {
+      try {
+        // Use client.event.subscribe() (GET /event) instead of client.global.event()
+        // global.event() only emits server.* events (heartbeat, connected).
+        // event.subscribe() delivers all session/permission events for this instance.
+        const sseResult = await client.event.subscribe({ throwOnError: false });
+        if (!sseResult.stream) {
+          this.logger.warn("opencode", "SSE stream unavailable", { event: "integration.unavailable", instanceUrl: inst.url, transport: "sse" });
+          return;
+        }
+
+        this.logger.info("opencode", "SSE stream subscribed", { event: "integration.subscribed", instanceUrl: inst.url, transport: "sse" });
+
+        // event.subscribe() yields Event directly: { type: string, properties: unknown }
+        for await (const event of sseResult.stream as AsyncIterable<{
+          type?: string;
+          properties?: unknown;
+        }>) {
+          if (abort.signal.aborted) break;
+
+          const payload = event;
+          if (!payload?.type) continue;
+
+          // Log ALL events including heartbeats so we can confirm stream is alive
+          this.logger.debug("opencode", "SSE event received", {
+            event: "integration.event_received",
+            instanceUrl: inst.url,
+            type: payload.type,
+          });
+
+          // Skip internal server heartbeat/connected events — not actionable
+          if (payload.type === "server.heartbeat" || payload.type === "server.connected") continue;
+
+          if (payload.type === "session.status") {
+            const props = payload.properties as { sessionID: string; status: SessionStatus } | undefined;
+            if (!props) continue;
+            const existing = inst.sessions.get(props.sessionID);
+            if (existing) {
+              const prevStatus = inst.status.get(props.sessionID);
+              const prevState = existing.state;
+              inst.status.set(props.sessionID, props.status);
+              const updated = buildSessionModel(
+                { id: props.sessionID, title: existing.summary, time: { created: 0, updated: existing.lastActivity }, directory: existing.currentPath ?? "" } as Session,
+                props.status,
+                inst.url,
+                inst.pendingPermissions,
+                inst.pendingQuestions,
+              );
+              const merged: SessionModel = { ...existing, state: updated.state, hasAttention: updated.hasAttention };
+              inst.sessions.set(props.sessionID, merged);
+              store.upsertSession(merged);
+              if (prevState !== merged.state) {
+                this.logger.debug("opencode", "Session state changed via SSE", {
+                  sessionId: props.sessionID,
+                  from: prevState,
+                  to: merged.state,
+                  sdkStatus: props.status.type,
+                  prevSdkStatus: prevStatus?.type,
+                });
+              }
+            }
+          } else if (payload.type === "session.idle") {
+            // Explicit idle signal — treat as status update to idle
+            const props = payload.properties as { sessionID?: string } | undefined;
+            if (props?.sessionID) {
+              const existing = inst.sessions.get(props.sessionID);
+              if (existing && existing.state !== "idle") {
+                const idleStatus: SessionStatus = { type: "idle" };
+                inst.status.set(props.sessionID, idleStatus);
+                const merged: SessionModel = { ...existing, state: "idle", hasAttention: false };
+                inst.sessions.set(props.sessionID, merged);
+                store.upsertSession(merged);
+                this.logger.debug("opencode", "Session state changed via SSE", {
+                  sessionId: props.sessionID,
+                  from: existing.state,
+                  to: "idle",
+                  sdkStatus: "idle",
+                });
+              }
+            }
+          } else if (payload.type === "session.updated" || payload.type === "session.created") {
+            // properties.info carries the full Session object — no extra API call needed
+            const props = payload.properties as { info?: Session } | undefined;
+            if (props?.info) {
+              const session = props.info;
+              const status = inst.status.get(session.id) ?? { type: "idle" as const };
+              const model = buildSessionModel(session, status, inst.url, inst.pendingPermissions, inst.pendingQuestions, this.gitCollector);
+              inst.sessions.set(session.id, model);
+              inst.status.set(session.id, status);
+              store.upsertSession(model);
+              // Rebuild parent→child links whenever a session is created or updated
+              store.syncChildSessionIds();
+              this.logger.debug("opencode", `Session ${payload.type.replace("session.", "")} via SSE`, {
+                sessionId: session.id,
+                title: session.title,
+              });
+            }
+          } else if (payload.type === "session.deleted") {
+            const props = payload.properties as { info?: { id?: string } } | undefined;
+            const sessionId = props?.info?.id;
+            if (sessionId) {
+              this.logger.debug("opencode", "Session deleted via SSE", { sessionId });
+              inst.sessions.delete(sessionId);
+              inst.pendingPermissions.delete(sessionId);
+              store.removeSession(`opencode:${sessionId}`);
+              // Rebuild parent→child links after deletion
+              store.syncChildSessionIds();
+            }
+          } else if (payload.type === "session.error") {
+            const props = payload.properties as { sessionID?: string; error?: { name?: string; data?: { message?: string; statusCode?: number } } } | undefined;
+            if (props?.sessionID) {
+              this.logger.warn("opencode", "Session error via SSE", {
+                sessionId: props.sessionID,
+                errorName: props.error?.name,
+                error: props.error?.data?.message,
+                statusCode: props.error?.data?.statusCode,
+              });
+            }
+          } else if (payload.type === "permission.updated") {
+            // permission.updated fires when a tool permission prompt is pending
+            // properties IS the Permission object directly
+            const perm = payload.properties as { id?: string; sessionID?: string; type?: string; title?: string } | undefined;
+            if (perm?.id && perm.sessionID) {
+              if (!inst.pendingPermissions.has(perm.sessionID)) {
+                inst.pendingPermissions.set(perm.sessionID, new Set());
+              }
+              inst.pendingPermissions.get(perm.sessionID)!.add(perm.id);
+              this.logger.debug("opencode", "Permission requested — session needs attention", {
+                sessionId: perm.sessionID,
+                permId: perm.id,
+                permType: perm.type,
+                title: perm.title,
+              });
+              this.refreshSessionState(inst, perm.sessionID, store);
+            }
+          } else if (payload.type === "permission.replied") {
+            // properties: { sessionID, permissionID, response }
+            const props = payload.properties as { sessionID?: string; permissionID?: string; response?: string } | undefined;
+            if (props?.permissionID && props.sessionID) {
+              inst.pendingPermissions.get(props.sessionID)?.delete(props.permissionID);
+              this.logger.debug("opencode", "Permission replied — unblocking session", {
+                sessionId: props.sessionID,
+                permId: props.permissionID,
+                response: props.response,
+              });
+              this.refreshSessionState(inst, props.sessionID, store);
+            }
+          }
+        }
+      } catch (error) {
+        if (abort.signal.aborted) return;
+        const msg = error instanceof Error ? error.message : String(error);
+        this.errorCount += 1;
+      this.logger.warn("opencode", "SSE disconnected — falling back to polling", { event: "integration.disconnected", instanceUrl: inst.url, transport: "sse", errorMessage: msg });
+        store.setCollectorStatus(this.name, { lastError: msg, errorCount: this.errorCount });
+        this.startPollFallback(inst);
+      }
+    };
+
+    void connect();
+  }
+
+  /** Re-compute and push updated state for a single session after permission/question change */
+  private refreshSessionState(inst: InstanceState, sessionId: string, store: DaemonStore): void {
+    const existing = inst.sessions.get(sessionId);
+    if (!existing) return;
+    const status = inst.status.get(sessionId) ?? { type: "idle" as const };
+    const prevState = existing.state;
+    const updated = buildSessionModel(
+      { id: sessionId, title: existing.summary, time: { created: 0, updated: existing.lastActivity }, directory: existing.currentPath ?? "" } as Session,
+      status,
+      inst.url,
+      inst.pendingPermissions,
+      inst.pendingQuestions,
+    );
+    const merged: SessionModel = { ...existing, state: updated.state, hasAttention: updated.hasAttention };
+    inst.sessions.set(sessionId, merged);
+    store.upsertSession(merged);
+    if (prevState !== merged.state) {
+      this.logger.debug("opencode", "Session state changed via permission/question event", {
+        sessionId,
+        from: prevState,
+        to: merged.state,
+        hasAttention: merged.hasAttention,
+      });
+    }
+  }
+
+  private async loadSingleSession(
+    inst: InstanceState,
+    client: ReturnType<typeof createOpencodeClient>,
+    sessionId: string,
+  ): Promise<void> {
+    const store = this.store!;
+    try {
+      const [sessionResult, statusMapResult] = await Promise.all([
+        client.session.get({ path: { id: sessionId }, throwOnError: false }),
+        client.session.status({ throwOnError: false }),
+      ]);
+      const session = sessionResult.data as Session | undefined;
+      const statusMap = (statusMapResult.data as { [key: string]: SessionStatus } | undefined) ?? {};
+      const status = statusMap[sessionId] ?? { type: "idle" as const };
+      if (!session) return;
+
+      const model = buildSessionModel(session, status, inst.url, inst.pendingPermissions, inst.pendingQuestions, this.gitCollector);
+      inst.sessions.set(sessionId, model);
+      inst.status.set(sessionId, status);
+      store.upsertSession(model);
+    } catch {
+      // Ignore per-session load errors
+    }
+  }
+
+  private startPollFallback(inst: InstanceState): void {
+    if (inst.pollTimer) return;
+    this.logger.warn("opencode", "Starting poll fallback", { event: "collector.fallback_started", instanceUrl: inst.url, intervalMs: 10_000 });
+    inst.pollTimer = setInterval(() => void this.safePollInstance(inst), 10_000);
+    void this.safePollInstance(inst);
+  }
+
+  /**
+   * skippedPolls in collector status aggregates two counters:
+   * - `skippedRefreshes`: global discovery cycles skipped due to concurrent safeRefresh
+   * - `inst.skippedPolls`: per-instance poll cycles skipped due to concurrent safePollInstance
+   * This reports the sum for the current instance only.
+   */
+  private async safePollInstance(inst: InstanceState): Promise<void> {
+    const store = this.store!;
+    if (inst.polling) {
+      inst.skippedPolls = (inst.skippedPolls ?? 0) + 1;
+      store.setCollectorStatus(this.name, { skippedPolls: this.skippedRefreshes + (inst.skippedPolls ?? 0) });
+      return;
+    }
+    inst.polling = true;
+    const startedAt = Date.now();
+    try {
+      await this.pollInstance(inst);
+      store.setCollectorStatus(this.name, { lastDurationMs: Date.now() - startedAt, skippedPolls: this.skippedRefreshes + (inst.skippedPolls ?? 0), errorCount: this.errorCount });
+    } finally {
+      inst.polling = false;
+    }
+  }
+
+  private async pollInstance(inst: InstanceState): Promise<void> {
+    const store = this.store!;
+    try {
+      const client = createOpencodeClient({ baseUrl: inst.url });
+      const listResult = await client.session.list({ throwOnError: false });
+      if (!listResult.data) return;
+
+      // Ensure PID is registered even if connectInstance previously failed.
+      // Without this, pollInstance keeps sessions alive but sdkPidSet stays
+      // empty, causing the tmux collector to create a duplicate fallback entry.
+      if (inst.pid && !store.getSdkPids().has(inst.pid)) {
+        store.registerSdkPid(inst.pid, inst.url);
+      }
+
+      const sessions = (listResult.data as Session[]) ?? [];
+      const seenIds = new Set<string>();
+
+      const statusMapResult = await client.session.status({ throwOnError: false });
+      const statusMap = (statusMapResult.data as { [key: string]: SessionStatus } | undefined) ?? {};
+
+      for (const session of sessions) {
+        seenIds.add(session.id);
+        const status: SessionStatus = statusMap[session.id] ?? { type: "idle" };
+        const prevState = inst.sessions.get(session.id)?.state;
+        const model = buildSessionModel(session, status, inst.url, inst.pendingPermissions, inst.pendingQuestions, this.gitCollector);
+        inst.sessions.set(session.id, model);
+        inst.status.set(session.id, status);
+        store.upsertSession(model);
+        if (prevState !== undefined && prevState !== model.state) {
+          this.logger.debug("opencode", "Session state changed via poll", {
+            sessionId: session.id,
+            from: prevState,
+            to: model.state,
+            sdkStatus: status.type,
+          });
+        }
+      }
+
+      // Remove sessions no longer in list
+      for (const [id] of inst.sessions) {
+        if (!seenIds.has(id)) {
+          inst.sessions.delete(id);
+          inst.pendingPermissions.delete(id);
+          inst.pendingQuestions.delete(id);
+          store.removeSession(`opencode:${id}`);
+        }
+      }
+
+      this.logger.debug("opencode", "Poll cycle complete", { event: "collector.poll_completed", collector: this.name, instanceUrl: inst.url, sessions: sessions.length });
+      store.setCollectorStatus(this.name, { running: true, lastRunAt: Date.now() });
+      // Rebuild parent→child links after each poll cycle
+      store.syncChildSessionIds();
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      this.errorCount += 1;
+      this.logger.warn("opencode", "Poll error", { event: "collector.poll_failed", collector: this.name, instanceUrl: inst.url, errorMessage: msg });
+      store.setCollectorStatus(this.name, {
+        lastError: msg,
+        errorCount: this.errorCount,
+      });
+    }
+  }
+
+  private teardownInstance(inst: InstanceState): void {
+    this.logger.info("opencode", "Tearing down instance", { event: "integration.teardown", instanceUrl: inst.url, sessions: inst.sessions.size });
+    if (inst.sseAbort) {
+      inst.sseAbort.abort();
+    }
+    if (inst.pollTimer) {
+      clearInterval(inst.pollTimer);
+    }
+    if (inst.pid) {
+      this.store?.unregisterSdkPid(inst.pid);
+      clearPidPortCache(inst.pid);
+    }
+    const store = this.store;
+    if (store) {
+      for (const [id] of inst.sessions) {
+        store.removeSession(`opencode:${id}`);
+      }
+    }
+    inst.sessions.clear();
+    inst.status.clear();
+    inst.pendingPermissions.clear();
+    inst.pendingQuestions.clear();
+  }
+}