@interactive-inc/flume 0.10.1 → 0.11.0

package/README.md

@@ -48,6 +48,7 @@ if (running instanceof Error) throw running
 
 // later
 await running.close()
+await running.drain() // outside callbacks: finish accepted callback work and diagnostics
 ```
 
 `new Flume({ sources, ...options })` — a single options object; `sources` is the only required field, everything else is optional. There is one unified firehose: `onEvent` (push) and `FlumeRunning.stream()` (pull) both deliver the same `FlumeStreamItem` — received events **and** every log (status transitions, errors, debug) merged into one stream. The consumer filters by `item.kind` (`"event"` / `"log"`) and `item.log.level`. This is built for piping the whole picture into an agent (Claude / Codex) so it notices disconnects on its own. `onError` is a convenience filter that additionally receives only the `level: "error"` logs (route it straight to Sentry).
@@ -70,8 +71,10 @@ Flume  ──open()──▶  FlumeRunning  ──close()──▶  FlumeClosed
 ```
 
 - `Flume.open()` returns `FlumeRunning | FlumeStartError`. Branch with `instanceof Error`. On partial failure (one source fails while another succeeds), the already-opened sources are rolled back and a `FlumeStartError` is returned with per-source detail in `.message`. Calling `open()` a second time on the same `Flume` instance returns `FlumeStartError` at runtime — the type system also rejects calling `open()` on the returned `FlumeRunning`/`FlumeClosed` handles.
-- `FlumeRunning.close()` returns a `FlumeClosed` snapshot. `close()` is idempotent and concurrent-safe.
-- `FlumeClosed` exposes only `statuses()` — a frozen snapshot of each source's final state. No `open`, no `close`, no leaking source references.
+- `FlumeRunning.close()` waits for sources to stop and returns a `FlumeClosed` snapshot. It is idempotent and concurrent-safe, and can be awaited inside `onEvent` or `onError`.
+- `FlumeRunning.drain()` waits for accepted callbacks and their failure diagnostics. Call it **outside callbacks**, normally after `close()`, when shutdown must also finish callback work. Calling it inside a callback would wait for that callback itself.
+- `open()` and `close()` do not wait for observation callbacks. A slow callback cannot hold startup or source shutdown open. Callback delivery remains serial; accepted callbacks may finish after `close()` returns.
+- `FlumeClosed` exposes `statuses()` and `errors()` — frozen snapshots of final source states and disconnect failures. No `open`, no `close`, no leaking source references.
 - An `AbortSignal` on `Flume` drives an automatic transition to `FlumeClosed`.
 - `FlumeRunning.kind === "running"` and `FlumeClosed.kind === "closed"` provide a runtime discriminator when generic code holds the union.
 
@@ -89,8 +92,11 @@ const closed = await running.close()
 closed.close() // type error
 closed.open() // type error
 closed.statuses() // [{ source: "discord", status: "disconnected" }, ...]
+await running.drain() // finish callback delivery before exiting the host process
 ```
 
+Migration from 0.10.1: shutdown code that relied on `close()` waiting for `onEvent` / `onError` should now use `await running.close(); await running.drain()` outside those callbacks. A callback may use `await running.close()` on its own. Pull streams finish after the accepted callbacks and their failure diagnostics have drained. A callback that never settles can therefore keep `drain()` and stream completion pending, while source shutdown still completes.
+
 ## Dynamic groups
 
 A `Flume` is single-use: its source set is fixed at construction and the FSM is terminal once closed. To add or drop sources at runtime, compose at a higher level with `FlumeConfluence` — it holds many `Flume` instances, merges all their firehoses into one `onEvent`, and lets you `add` / `remove` groups while the others keep running.
@@ -100,7 +106,7 @@ import { FlumeConfluence } from "@interactive-inc/flume"
 
 const confluence = new FlumeConfluence({
   onEvent: (item) => {
-    if (item.kind === "event") feedToAgent(item.event)
+    if (item.kind === "event") feedToAgent(item.groupId, item.event)
     if (item.kind === "log" && item.log.action === "status") noticeDisconnect(item.log)
   },
   reconnect: { maxAttempts: 10 },
@@ -112,7 +118,9 @@ await confluence.remove("team-a") // stops only team-a
 await confluence.closeAll()
 ```
 
-`add(id, sources)` starts a fresh `Flume` for that group and returns `Error | null` (a duplicate id or a failed start is returned, never thrown). The `id` is just a management handle — the merged stream itself is untagged; identify the origin via the `source` field inside each item. Each group is an independent `Flume`, so a failure in one group never rolls back another. Reconstructing a group (rather than mutating one in place) loses only its reconnect counters, dedup caches, and Discord session resume — acceptable on a deliberate add/remove.
+`add(id, sources)` starts a fresh `Flume` for that group and returns `Error | null` (a duplicate id or a failed start is returned, never thrown). Every merged item is stamped with that id as `groupId`, while `item.event.source` / `item.log.source` identifies the protocol source inside the group. Each group is an independent `Flume`, so a failure in one group never rolls back another. `replace(id, sources)` opens a replacement first and closes the previous group only after the new one is ready; a failed replacement leaves the previous group running.
+
+Source instances are single-use. Reusing an existing instance returns a `FlumeStartError` and preserves its current owner's connection. `remove()` / `closeAll()` wait for source shutdown; callbacks already accepted by those groups may finish afterward.
 
 ## Sub-entries
 
@@ -126,24 +134,32 @@ import { FlumeGitHubSource } from "@interactive-inc/flume/github"
 import { FlumeTimeSource } from "@interactive-inc/flume/time"
 ```
 
-- `@interactive-inc/flume` — `Flume`, `FlumeConfluence`, `FlumeRunning`, `FlumeClosed`, `FlumeSource` (abstract base for third-party sources), `createFlumeDefaultDeps`, errors, types
+- `@interactive-inc/flume` — `Flume`, `FlumeConfluence`, `FlumeRunning`, `FlumeClosed`, `FlumeSource` (abstract base for third-party sources), `createFlumeDefaultDeps`, errors, types, and the common `attempt` / `safe*` utilities used by custom sources
 - `@interactive-inc/flume/discord` — `FlumeDiscordSource`, `FlumeDiscordGatewayIntents`, `flumeExtractDiscordMeta`
 - `@interactive-inc/flume/slack` — `FlumeSlackSource`, `flumeExtractSlackMeta`
 - `@interactive-inc/flume/github` — `FlumeGitHubSource`, `flumeExtractGitHubMeta`
-- `@interactive-inc/flume/time` — `FlumeTimeSource`, `parseCron`, `flumeCronNext`
+- `@interactive-inc/flume/time` — `FlumeTimeSource`, `parseCron`, `flumeCronNext`, `flumeCollectCatchupMatches`
 
 ## Custom sources
 
 Extend `FlumeSource` to plug in any protocol. The base class owns `start`/`stop`/`status`, the per-source event queue, status emission (logged on every transition), and consumed/stopped guards. You implement `connect` (open the protocol, emit events, set status) and `disconnect` (tear it down).
 
 ```ts
-import { FlumeSource } from "@interactive-inc/flume"
-import type { FlumeSourceStartContext } from "@interactive-inc/flume"
+import {
+  attempt,
+  FlumeSource,
+  safeErrorMessage,
+  safeInvokeCallback,
+  safeJsonParse,
+  safeNow,
+  safeReadText,
+} from "@interactive-inc/flume"
+import type { FlumeSourceStartContext, FlumeTimerHandle } from "@interactive-inc/flume"
 
 class MyWebhookSource extends FlumeSource {
   readonly name = "my-webhook"
 
-  private timer: ReturnType<typeof setInterval> | null = null
+  private timer: FlumeTimerHandle | null = null
 
   constructor(private readonly options: { url: string; pollInterval?: number }) {
     super()
@@ -152,34 +168,73 @@ class MyWebhookSource extends FlumeSource {
   protected async connect(ctx: FlumeSourceStartContext): Promise<Error | null> {
     this.setStatus("connecting")
     const interval = (this.options.pollInterval ?? 30) * 1000
-    this.timer = ctx.deps.setInterval(() => this.poll(ctx), interval) as ReturnType<
-      typeof setInterval
-    >
+    const timer = attempt(() => ctx.deps.setInterval(() => this.runPoll(ctx), interval))
+    if (timer instanceof Error) return timer
+    this.timer = timer
     this.setStatus("connected")
     return null
   }
 
   protected disconnect(): void {
-    if (this.timer) clearInterval(this.timer)
+    const timer = this.timer
     this.timer = null
+    const ctx = this.context
+    if (timer === null || ctx === null) return
+
+    const result = attempt(() => ctx.deps.clearInterval(timer))
+    if (result instanceof Error) {
+      ctx.log.error({
+        action: "timer.clear.error",
+        message: safeErrorMessage({ error: result }),
+        error: result,
+      })
+    }
+  }
+
+  private runPoll(ctx: FlumeSourceStartContext): void {
+    safeInvokeCallback({
+      fn: async () => {
+        const result = await this.poll(ctx)
+        if (result instanceof Error) {
+          ctx.log.error({
+            action: "poll.error",
+            message: safeErrorMessage({ error: result }),
+            error: result,
+          })
+        }
+      },
+      onError: (error) => {
+        ctx.log.error({
+          action: "poll.unhandled",
+          message: safeErrorMessage({ error }),
+          error,
+        })
+      },
+    })
   }
 
-  private async poll(ctx: FlumeSourceStartContext): Promise<void> {
-    const res = await ctx.deps.fetch(this.options.url)
-    const payload = await res.json()
+  private async poll(ctx: FlumeSourceStartContext): Promise<Error | null> {
+    const response = await attempt(() => ctx.deps.fetch(this.options.url))
+    if (response instanceof Error) return response
+    const raw = await safeReadText({ response, context: this.name })
+    if (raw instanceof Error) return raw
+    const payload = safeJsonParse(raw)
+    if (payload instanceof Error) return payload
+
     this.emit({
       source: "custom",
       sourceName: this.name,
       type: "webhook",
       data: { payload },
       meta: { event_type: "webhook" },
-      receivedAt: ctx.deps.now(),
+      receivedAt: safeNow({ deps: ctx.deps }),
     })
+    return null
   }
 }
 ```
 
-`this.emit({...})` queues events through the base's serial queue and routes them to `ctx.onEvent` with `attempt()` isolation. `this.setStatus(...)` deduplicates idempotent transitions and logs the change (which is how status surfaces to consumers). Subclasses never need to write try/catch.
+`this.emit({...})` queues events through the base's serial queue and routes them to `ctx.onEvent` with `attempt()` isolation. `this.setStatus(...)` deduplicates idempotent transitions and logs the change. IO started after `connect()` returns, such as timer callbacks, must use `attempt()` or `safeInvokeCallback()` as shown above; both are exported from the root entry so custom sources do not need raw try/catch.
 
 ## Time source
 
@@ -211,6 +266,8 @@ new FlumeTimeSource({
 
 `tick.firedAt` is the scheduled wall-clock time (epoch ms), not the exact `setTimeout` firing instant. A throwing `message()` is isolated and falls back to the defaults. Parse the cron up front with `parseCron(expr)` (returns `FlumeCron | FlumeParseError`) or compute the next fire with `flumeCronNext(cron, afterMs)`.
 
+With `statePersister`, state writes are serialized in tick order and source shutdown waits for queued writes to settle. A failed write is logged and later writes still run. Keep the persister's IO bounded and avoid waiting for Flume lifecycle completion inside it. Stopping during `load()` releases startup immediately and ignores a late result; cancellation of the host's underlying read remains the persister's responsibility. Use `catchupPolicy` (`off`, `lastOnly`, or `missed`) to control replay on the next start. When multiple sources share a persistence key, the host must also serialize or atomically order their writes.
+
 ## Pull stream
 
 `FlumeRunning.stream()` is the pull form of the same firehose as `onEvent` — an async iterator over `FlumeStreamItem`, handy for feeding an agent (Claude / Codex) with `for await`, where backpressure falls out naturally from how fast you pull.
@@ -225,10 +282,10 @@ for await (const item of running.stream()) {
   if (item.kind === "event") await handleWithAgent(item.event)
   if (item.kind === "log" && item.log.action === "status") noticeDisconnect(item.log)
 }
-// loop ends when the flume stops (running.close() or signal abort)
+// after close / signal abort, the loop ends once accepted callback diagnostics are delivered
 ```
 
-The iterator ends cleanly when the flume stops; `break`ing out unsubscribes automatically. When a slow consumer lets the buffer overflow, the oldest items are dropped by default:
+The iterator ends cleanly after source shutdown and accepted callback work; `break`ing out unsubscribes automatically. When a slow consumer lets the buffer overflow, the oldest items are dropped by default:
 
 ```ts
 running.stream({ buffer: 5000, onOverflow: "drop-newest" })
@@ -284,7 +341,7 @@ type FlumeEvent = FlumeDiscordEvent | FlumeSlackEvent | FlumeGitHubEvent | Flume
 
 ## Observability
 
-Flume never calls a third-party service. Every internal action is reported through the firehose (`onEvent` push / `stream()` pull) as `{ kind: "log", log }` items — there are no silent paths. Each `FlumeLog` is tagged with `source: "flume"`, `source: "discord"`, `source: "slack"`, `source: "github"`, `source: "time"`, or your custom source's `name`. `onError` is a convenience filter that additionally receives only the `level: "error"` subset (route it straight to Sentry).
+Flume never calls a third-party service. Every internal action is reported through the firehose (`onEvent` push / `stream()` pull) as `{ kind: "log", log }` items — there are no silent internal paths. Each `FlumeLog` is tagged with `source: "flume"`, `source: "discord"`, `source: "slack"`, `source: "github"`, `source: "time"`, or your custom source's `name`. `onError` is a convenience filter that additionally receives only the `level: "error"` subset (route it straight to Sentry).
 
 ```ts
 type FlumeLog = {
@@ -307,6 +364,9 @@ What gets logged:
 - Reconnect — `reconnect.scheduled` (with delay in ms), `reconnect.exhausted` (with attempt count), `reconnect.reset` (on successful connect after retries), `reconnect.cancel` (on stop).
 - Status transitions — `status` action with `previous → next`.
 - Errors — `level: "error"` carries the `error` field; use `onError` for a pre-filtered error sink.
+- Observation sink failures — a failed `onEvent` emits `onEvent.error` to `onError` and the pull stream; a failed `onError` emits `onError.error` to `onEvent` and the pull stream. `detail` identifies the callback plus the failed item's kind, source, and event type or log action. `FlumeConfluence` also stamps `groupId` onto logs sent to its `onError`. The peer notification is attempted once, without recursive reporting.
+
+For maximum diagnostics, configure both callbacks or keep a pull stream consumer. If both push callbacks fail, both failure logs remain available to the pull stream; startup logs are replayed to its first subscriber. `FlumeConfluence` has no pull iterator, so configure its `onError` as the independent diagnostic sink.
 
 Route it anywhere — Sentry, Datadog, `console`, a file — your choice. Filter the log items out of the firehose:
 
@@ -396,9 +456,9 @@ new Flume({
 
 ## Safety
 
-- Ordering — each source has its own `FlumeSerialQueue` and per-source events are delivered FIFO. Cross-source ordering between events from different sources is undefined (no global serialization). `onEvent` invocations are awaited and run one at a time per source, so async callbacks don't race and `close()` drains in-flight events before transitioning state.
+- Ordering — each source has its own `FlumeSerialQueue` and per-source events are published FIFO. The public `onEvent` and `onError` callbacks share one global queue, so callback invocations never race across sources. `close()` stops the sources; a subsequent `drain()` waits for callbacks and their failure diagnostics. Pull subscribers receive items when they are published and have independent bounded buffers. The push callback queue is unbounded; use pull-only consumption for a bounded slow consumer.
 - Duplicate suppression — Slack envelopes are deduped by `envelope_id` (`FlumeSlackSeenCache`) to absorb ack retries. GitHub notifications are deduped by `id + updated_at` (`FlumeGitHubSeenCache`). Discord uses session resume so the Gateway does not re-emit dispatches.
-- Partial-failure rollback — if any source fails during `Flume.open()`, the already-started sources are stopped and a `FlumeStartError` is returned with per-source detail.
+- Partial-failure rollback — if any source fails during `Flume.open()`, sources acquired by that open are stopped, including partially connected failures. A source that refused reuse remains with its existing owner. A `FlumeStartError` is returned with per-source detail.
 - Idempotent close — `FlumeRunning.close()` is safe to call concurrently; the first call wins and subsequent callers receive the same `FlumeClosed` snapshot. The same guard exists at source level: a double-`close()` (e.g. via signal abort racing a manual close) does not re-invoke `disconnect()`.
 
 ## Errors
@@ -410,9 +470,9 @@ Flume does not throw on protocol/network failures. Every entry point returns `T
 - `FlumeHttpError` — HTTP call returned an error payload (e.g. Slack `ok: false`)
 - `FlumeParseError` — Unparseable WebSocket frame
 
-Exceptions thrown from `onEvent` are caught and logged (never rethrown into the protocol loop).
+Exceptions thrown or rejected from `onEvent` / `onError` are isolated and emitted as `onEvent.error` / `onError.error` diagnostics; they are never rethrown into the protocol loop.
 
-The library guarantees that no exception escapes any public surface — constructors, `open()`, `close()`, the `onEvent` invocation path, the `stream()` iterator, the abort-signal path, and the `onError` callback all route IO and user-supplied callbacks through internal `safe*` wrappers and the generic `attempt()` helper. A misbehaving `onEvent` / `onError` will be logged and isolated rather than crashing the protocol loop.
+With type-valid constructor input, the library guarantees that protocol IO and user callback failures do not escape `open()`, `close()`, the `onEvent` invocation path, the `stream()` iterator, the abort-signal path, or the `onError` callback. These boundaries route work through internal `safe*` wrappers and the generic `attempt()` helper.
 
 ## Supported sources
 
@@ -442,11 +502,11 @@ const github = new FlumeGitHubSource({ token })
 
 ```bash
 bun install
-bunx vp pack       # build dist/
-bunx tsc --noEmit  # typecheck
-bunx vitest run    # tests
-bunx vp lint       # lint
-bunx vp fmt        # format
+vp pack            # build dist/
+vp run typecheck   # typecheck
+vp test            # tests
+vp lint            # lint
+vp fmt             # format
 ```
 
 The library itself is runtime-agnostic. The dev toolchain (build / test / lint) uses Bun + `vite-plus` + `vitest`, but the published `dist/` is plain ESM with TypeScript declarations and runs on Node 22+, Bun, Deno, Cloudflare Workers, or modern browsers. Runtimes without a global `WebSocket` (e.g. fetch-only edge functions) can still use `FlumeGitHubSource`; `FlumeDiscordSource` / `FlumeSlackSource` will return `FlumeStartError` at `open()` time if `deps.WebSocket` is `null`.

package/dist/discord.js

@@ -1,8 +1,8 @@
-import { a as safeNow, c as attempt, i as FlumeLogger, l as safeNormalizeError, o as FlumeStartError, r as safeInvokeCallback, s as FlumeParseError, t as FlumeSource, u as safeErrorMessage } from "./flume-source.js";
-import { t as FlumeConnectionError } from "./connection-error.js";
-import { i as safeRandom, n as scheduleFlumeReconnect, r as FlumeReconnector, t as safeStringify } from "./safe-stringify.js";
+import { a as safeInvokeCallback, c as FlumeParseError, d as safeErrorMessage, i as safeNow, l as attempt, r as FlumeLogger, s as FlumeStartError, t as FlumeSource, u as safeNormalizeError } from "./flume-source.js";
+import { n as safeRandom, r as FlumeConnectionError, t as safeStringify } from "./safe-stringify.js";
 import { t as isRecord } from "./is-record.js";
 import { t as safeJsonParse } from "./safe-json-parse.js";
+import { n as FlumeReconnector, t as scheduleFlumeReconnect } from "./schedule-reconnect.js";
 import { z } from "zod/v4";
 //#region lib/discord/discord-gateway-session.ts
 var FlumeDiscordGatewaySession = class FlumeDiscordGatewaySession {

package/dist/flume-source.d.ts

@@ -244,7 +244,9 @@ type FlumeTimeMessage = {
 /**
  * 起動 / 終了をまたいだ状態を 1 つ載せる純粋な DI ポート。flume 内部で fs / db / network を
  * 触らないように、I/O の場所と方式は host が決める。load の失敗は null 復帰扱い、save の
- * 失敗は best-effort (source 側で log するが throw しない)
+ * 失敗は best-effort (source 側で log するが throw しない)。Time source は save を直列実行し、
+ * stop 時に queued save の完了を待つ。persister 内から Flume の終了を await しない。
+ * stop は load の待機を解除するが、host 側で開始した read IO 自体は中断しない。
  */
 type FlumeStatePersister<S> = {
   load(): Promise<S | null>;
@@ -342,6 +344,8 @@ declare abstract class FlumeSource {
    * subclass が protocol 状態遷移をユーザーに通知する。同一 (status, detail) の連続は冪等
    */
   protected setStatus(status: FlumeStatus, detail?: string): void;
+  /** await をまたぐ接続処理が、停止後に新しいリソースを作らないための guard。 */
+  protected get isStopped(): boolean;
   /** subclass が現在の status を読みたい場合 */
   protected get currentStatus(): FlumeStatus;
   /** subclass が start ctx を再参照したい場合 (stop 後は null) */

package/dist/flume-source.js

@@ -82,6 +82,30 @@ var FlumeStartError = class extends Error {
 	}
 };
 //#endregion
+//#region lib/errors/source-reuse-error.ts
+/** 起動を取得する前の拒否。Flume は他の起動処理が所有する Source を rollback しない。 */
+var FlumeSourceReuseError = class extends FlumeStartError {};
+//#endregion
+//#region lib/utils/safe-invoke-callback.ts
+/**
+* fire-and-forget でユーザーコールバックを呼び出す。sync throw と async reject のどちらも
+* `onError(Error)` に正規化して通知。`onError` 自身が throw しても外に漏らさない。
+* 戻り値を持たない fire-and-forget 専用のため log/出力先には依存しない (caller が onError で決める)
+*/
+function safeInvokeCallback(props) {
+	try {
+		Promise.resolve(props.fn()).catch((err) => {
+			try {
+				props.onError(safeNormalizeError({ value: err }));
+			} catch {}
+		}).catch(() => {});
+	} catch (err) {
+		try {
+			props.onError(safeNormalizeError({ value: err }));
+		} catch {}
+	}
+}
+//#endregion
 //#region lib/utils/safe-now.ts
 /**
 * `deps.now()` を保護する。throw / 非数値 / 非有限値が返った場合は `Date.now()` へ
@@ -145,64 +169,26 @@ var FlumeLogger = class FlumeLogger {
 			error: input.error,
 			detail: input.detail
 		};
-		try {
-			Promise.resolve(handler(log)).catch(() => {});
-		} catch {}
+		safeInvokeCallback({
+			fn: () => handler(log),
+			onError: () => {}
+		});
 	}
 };
 //#endregion
-//#region lib/utils/safe-invoke-callback.ts
-/**
-* fire-and-forget でユーザーコールバックを呼び出す。sync throw と async reject のどちらも
-* `onError(Error)` に正規化して通知。`onError` 自身が throw しても外に漏らさない。
-* 戻り値を持たない fire-and-forget 専用のため log/出力先には依存しない (caller が onError で決める)
-*/
-function safeInvokeCallback(props) {
-	try {
-		Promise.resolve(props.fn()).catch((err) => {
-			try {
-				props.onError(safeNormalizeError({ value: err }));
-			} catch {}
-		}).catch(() => {});
-	} catch (err) {
-		try {
-			props.onError(safeNormalizeError({ value: err }));
-		} catch {}
-	}
-}
-//#endregion
 //#region lib/utils/serial-queue.ts
 /**
 * 投入順を保ったまま task を直列実行する。各 task は前の完了を待ってから走る。
 * task が throw しても後続には伝播しない (キュー自体は止まらない)。
-* maxDepth を超えた場合は新規 task を drop し onOverflow に通知。
-* cancel() 後は add() が no-op になり、既に積まれた未実行 task も実行せずに流れ落ちる。
 * drain() は待機中に追加された task も含めてキューが空になるまで待つ
 */
 var FlumeSerialQueue = class {
-	props;
 	chain = Promise.resolve();
-	depth = 0;
-	cancelled = false;
-	constructor(props = {}) {
-		this.props = props;
-	}
 	add(task) {
-		if (this.cancelled) return Promise.resolve();
-		if (this.props.maxDepth !== void 0 && this.depth >= this.props.maxDepth) {
-			this.props.onOverflow?.({
-				dropped: 1,
-				depth: this.depth
-			});
-			return Promise.resolve();
-		}
-		this.depth++;
 		const completion = this.chain.then(async () => {
 			try {
-				if (!this.cancelled) await task();
-			} catch {} finally {
-				this.depth--;
-			}
+				await task();
+			} catch {}
 		});
 		this.chain = completion;
 		return completion;
@@ -214,15 +200,6 @@ var FlumeSerialQueue = class {
 			if (this.chain === current) return;
 		}
 	}
-	cancel() {
-		this.cancelled = true;
-	}
-	size() {
-		return this.depth;
-	}
-	isCancelled() {
-		return this.cancelled;
-	}
 };
 //#endregion
 //#region lib/source-helpers/flume-status-emitter.ts
@@ -312,8 +289,8 @@ var FlumeSource = class {
 	abortHandler = null;
 	queue = new FlumeSerialQueue();
 	async start(ctx) {
-		if (this.consumed) return new FlumeStartError(`${this.name}: already started`);
-		if (this.stopped) return new FlumeStartError(`${this.name}: already stopped`);
+		if (this.consumed) return new FlumeSourceReuseError("Source already started");
+		if (this.stopped) return new FlumeSourceReuseError("Source already stopped");
 		this.consumed = true;
 		this.ctx = ctx;
 		this.statusEmitter = new FlumeStatusEmitter({
@@ -355,7 +332,7 @@ var FlumeSource = class {
 	*/
 	emit(event) {
 		const ctx = this.ctx;
-		if (!ctx) return;
+		if (!ctx || this.stopped) return;
 		this.queue.add(async () => {
 			const result = await attempt(() => Promise.resolve(ctx.onEvent(event)));
 			if (result instanceof Error) ctx.log.error({
@@ -369,8 +346,13 @@ var FlumeSource = class {
 	* subclass が protocol 状態遷移をユーザーに通知する。同一 (status, detail) の連続は冪等
 	*/
 	setStatus(status, detail) {
+		if (this.stopped) return;
 		this.statusEmitter?.set(status, detail);
 	}
+	/** await をまたぐ接続処理が、停止後に新しいリソースを作らないための guard。 */
+	get isStopped() {
+		return this.stopped;
+	}
 	/** subclass が現在の status を読みたい場合 */
 	get currentStatus() {
 		return this.statusEmitter?.value ?? "disconnected";
@@ -414,4 +396,4 @@ var FlumeSource = class {
 	}
 };
 //#endregion
-export { safeNow as a, attempt as c, FlumeLogger as i, safeNormalizeError as l, FlumeSerialQueue as n, FlumeStartError as o, safeInvokeCallback as r, FlumeParseError as s, FlumeSource as t, safeErrorMessage as u };
+export { safeInvokeCallback as a, FlumeParseError as c, safeErrorMessage as d, safeNow as i, attempt as l, FlumeSerialQueue as n, FlumeSourceReuseError as o, FlumeLogger as r, FlumeStartError as s, FlumeSource as t, safeNormalizeError as u };

package/dist/github.js

@@ -1,7 +1,6 @@
-import { a as safeNow, c as attempt, i as FlumeLogger, l as safeNormalizeError, s as FlumeParseError, t as FlumeSource, u as safeErrorMessage } from "./flume-source.js";
-import { t as FlumeHttpError } from "./http-error.js";
+import { c as FlumeParseError, d as safeErrorMessage, i as safeNow, l as attempt, r as FlumeLogger, t as FlumeSource, u as safeNormalizeError } from "./flume-source.js";
+import { n as FlumeHttpError, t as safeReadText } from "./safe-read-text.js";
 import { t as safeJsonParse } from "./safe-json-parse.js";
-import { t as safeReadText } from "./safe-read-text.js";
 import { z } from "zod/v4";
 //#region lib/github/extract-github-meta.ts
 function flumeExtractGitHubMeta(notification) {
@@ -161,10 +160,10 @@ var FlumeGitHubPoller = class {
 	async poll() {
 		if (this.inFlight || this.isStoppedFlag) return null;
 		this.inFlight = true;
-		try {
-			return await this.pollOnce();
-		} catch (err) {
-			const cause = safeNormalizeError({ value: err });
+		const attempted = await attempt(async () => ({ result: await this.pollOnce() }));
+		this.inFlight = false;
+		if (attempted instanceof Error) {
+			const cause = safeNormalizeError({ value: attempted });
 			const error = new FlumeHttpError({
 				message: `poll loop threw: ${safeErrorMessage({ error: cause })}`,
 				status: 0,
@@ -177,9 +176,8 @@ var FlumeGitHubPoller = class {
 			});
 			if (!this.bootstrapped) return error;
 			return null;
-		} finally {
-			this.inFlight = false;
 		}
+		return attempted.result;
 	}
 	async pollOnce() {
 		const params = new URLSearchParams({