opencode-swarm 7.137.2 → 7.137.3

package/dist/observability/catalog.d.ts

@@ -1,14 +1,13 @@
 /**
  * The event catalog (issue #2029).
  *
- * Exactly 39 entries, matching the `TelemetryEvent` union at
- * `src/telemetry.ts:15-86`. Thirty-eight of them predate this change; the 39th is
- * `agent_conflict_detected`, which before this change was emitted in
- * production through a force-cast past the type system before this change
- * (at `src/hooks/conflict-resolution.ts:67-70` in the BASE tree; the replacement typed call is
- * `:73` here) and was absent from the union. That
- * 39th entry is the already-found instance of the defect class this contract
- * exists to close: an event kind can enter the stream with no registration.
+ * Exactly 40 entries, matching the `TelemetryEvent` union at
+ * `src/telemetry.ts:15-91`. Thirty-eight predate the #2029 contract; the 39th is
+ * `agent_conflict_detected` (previously emitted through a force-cast past the
+ * type system), and the 40th is `close_archive_result` (issue #2030 — the
+ * structured close/archive result event). Both late additions are instances of
+ * the defect class this contract exists to close: an event kind entering the
+ * stream with no registration.
  *
  * Every entry names a real producer `file:line`, a retention owner issue at or
  * above #2030 — every entry today cites the #2030-#2051 programme, but only the
@@ -61,7 +60,7 @@ export interface CatalogEntry {
     /**
      * Whether an event of this kind must carry `trace.parentSpanId`.
      *
-     * `false` for all 39 entries today, and that is a truthful statement about
+     * `false` for all 40 entries today, and that is a truthful statement about
      * the current system rather than a placeholder: no producer supplies a
      * parent span, so `createObservation` never sets one. Setting this to `true`
      * for a kind whose producer cannot supply a parent would make every

package/dist/telemetry.d.ts

@@ -17,8 +17,8 @@ export type TelemetryEvent = 'session_started' | 'session_ended' | 'agent_activa
  | 'execution_stall_denied'
 /**
  * Issue #2063 B4 — a read/glob/grep/bash call resolved to a path inside the
- * INSTALLED opencode-swarm package and was denied. `target` is relative to
- * the package root so no user home path is written to the ledger.
+ * INSTALLED opencode-swarm package and was denied. `target` is relative to the
+ * package root so no user home path is written to the ledger.
  */
  | 'swarm_internals_read_denied' | 'prm_pattern_detected' | 'prm_course_correction_injected' | 'prm_escalation_triggered' | 'prm_hard_stop'
 /**
@@ -26,7 +26,7 @@ export type TelemetryEvent = 'session_started' | 'session_ended' | 'agent_activa
  * `prm_hard_stop` TRIGGER emitted by `src/prm/escalation.ts`. A trigger with
  * no matching delivery means the containment never reached the agent.
  */
- | 'prm_hard_stop_delivered' | 'agent_conflict_detected';
+ | 'prm_hard_stop_delivered' | 'agent_conflict_detected' | 'close_archive_result';
 /** Stable classification for how a reviewer-gate decision was established. */
 export type ReviewerGateEvidenceKind = 'genuine' | 'fallback' | 'data_quality' | 'block';
 /**
@@ -78,6 +78,31 @@ export declare function addTelemetryListener(callback: TelemetryListener): void;
  * @param maxBytes - Size threshold in bytes (default: 10MB)
  */
 export declare function rotateTelemetryIfNeeded(maxBytes?: number): void;
+/**
+ * Flush any buffered telemetry records to disk and reopen the append stream.
+ *
+ * Why this exists (issue #2030 item 8): `/swarm close` archives
+ * `telemetry.jsonl` via `fs.copyFile`, but the writer holds an open buffered
+ * `WriteStream` whose in-memory buffer is not reflected in the on-disk file
+ * until the OS accepts the bytes. Archiving without flushing silently loses the
+ * tail records of the session.
+ *
+ * Ordering (race fix, swarm-pr-review F-003): the replacement stream is created
+ * and assigned to `_writeStream` BEFORE `end()` is called on the old handle, so
+ * a concurrent `emit()` that races across the await lands on the live stream.
+ * The old handle's write callback would otherwise fire
+ * `ERR_STREAM_WRITE_AFTER_END`, latch `_disabled = true`, and kill telemetry for
+ * every subsequent session until restart (server-scoped plugin process). This
+ * mirrors the already-safe `rotateTelemetryIfNeeded` ordering.
+ *
+ * `WriteStream.end(cb)` invokes `cb` on the `'finish'` event — AFTER the buffer
+ * has been drained to the OS — so awaiting that callback is the documented way
+ * to guarantee the on-disk file contains every emitted record up to this point.
+ *
+ * Fail-open: any error during reopen disables telemetry rather than throwing —
+ * a flush failure must never block the close pipeline.
+ */
+export declare function flushAndDrainTelemetry(): Promise<void>;
 export declare const telemetry: {
     sessionStarted(sessionId: string, agentName: string): void;
     sessionEnded(sessionId: string, reason: string): void;
@@ -136,6 +161,35 @@ export declare const telemetry: {
     prmCourseCorrectionInjected(sessionId: string, pattern: string, level: number): void;
     prmEscalationTriggered(sessionId: string, pattern: string, level: number, occurrenceCount: number): void;
     prmHardStop(sessionId: string, pattern: string, level: number, occurrenceCount: number): void;
+    /**
+     * Close/archive structured result (issue #2030). This single event is the
+     * shared source of truth for both the user-facing close summary prose and
+     * the telemetry stream, so the two cannot disagree. Carries per-artifact
+     * structured fields plus aggregate `archive_valid`/`archive_empty` health
+     * facts. Row counts are counts ONLY — no row content is ever emitted (issue
+     * item 4/9), enabling PR 16 to alarm and PR 20 to report without leaking
+     * data.
+     */
+    closeArchiveResult(data: {
+        archive_valid: boolean;
+        archive_empty: boolean;
+        file_count: number;
+        bundle: string;
+        artifacts: Array<{
+            artifact: string;
+            requiredness: string;
+            attempt: string;
+            validation: string;
+            source_disposition: string;
+            method: string;
+            reason_code: string;
+            row_counts?: {
+                schema_migrations_max_version: number | null;
+                project_constraints: number;
+                qa_gate_profile: number;
+            };
+        }>;
+    }): void;
     /**
      * Issue #2063 C2 — the PRM hard-stop DENIAL was actually delivered to the
      * agent (thrown by the guardrails `toolBefore` consumer). `prm_hard_stop`
@@ -157,6 +211,7 @@ export declare const _internals: {
     telemetry: typeof telemetry;
     emit: typeof emit;
     rotateTelemetryIfNeeded: typeof rotateTelemetryIfNeeded;
+    flushAndDrainTelemetry: typeof flushAndDrainTelemetry;
     heartbeatListenerCount: () => number;
     createObservation: typeof createObservation;
     toLegacyTelemetryLine: typeof toLegacyTelemetryLine;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "7.137.2",
+	"version": "7.137.3",
 	"description": "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",