opencode-swarm 7.54.0 → 7.56.0

package/dist/background/completion-observer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Background subagent completion OBSERVER (issue #1151, PR 2 Stage A).
+ *
+ * Registers as a swarm `event` hook to watch for the upstream background-completion signal:
+ * a message part with `synthetic === true` whose text is a task envelope with
+ * `state="completed"` or `state="error"`. When such a part correlates to a durable pending
+ * background-delegation record, it is logged (debug-gated) as the empirical confirmation
+ * instrument operators use to verify the runtime signal in a real environment.
+ *
+ * Stage A is strictly READ-ONLY: this observer NEVER advances workflow gates, records gate
+ * evidence, or mutates the durable store. Gate-affecting completion ingestion is Stage B,
+ * gated on runtime confirmation produced by exactly this observer.
+ *
+ * The `synthetic` flag is the trust gate (set by OpenCode, not the model/user). Non-synthetic
+ * text that merely looks like an envelope is ignored. The observer is fail-open: any error is
+ * swallowed so it can never block event delivery or plugin load (Invariant 1/10).
+ */
+interface ObserverConfig {
+    enabled: boolean;
+}
+/**
+ * Build the Stage A completion observer. Returns an `event` handler suitable for the
+ * OpenCode plugin `event` hook. No-op (cheap early return) when the feature is disabled.
+ */
+export declare function createBackgroundCompletionObserver(opts: {
+    config: ObserverConfig;
+    directory: string;
+}): {
+    event: (input: {
+        event: unknown;
+    }) => Promise<void>;
+};
+export {};

package/dist/background/pending-delegations.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Durable pending background-delegation store (issue #1151, PR 2 Stage A).
+ *
+ * Append-only JSONL event log under project-root `.swarm/background-delegations.jsonl`.
+ * Each line is a full record snapshot; readers fold to the latest snapshot per
+ * `correlationId`. This tracks background swarm `Task` dispatches so a later (Stage B)
+ * trusted completion can be correlated to a real dispatch. The stale sweep bounds the
+ * number of permanently-running (unresolved) entries by transitioning them to `stale`, so
+ * the folded in-memory view stays bounded by distinct correlationIds. Note: the on-disk
+ * log itself is append-only and is NOT compacted in Stage A — each dispatch leaves a small,
+ * fixed number of lines; on-disk compaction of dropped/stale records is a future stage.
+ *
+ * Stage A scope: dispatch records a `pending` snapshot and the stale sweep records
+ * `stale` snapshots. There is NO gate advancement and NO completion mutation here — the
+ * completion observer (Stage A) is read-only. Gate-affecting completion ingestion is
+ * Stage B, gated on runtime confirmation of the upstream completion signal.
+ *
+ * Concurrency: all writes (append, sweep) run under a single project-scoped lock via
+ * `withEvidenceLock`, so concurrent dispatches/sweeps cannot interleave appends. Reads are
+ * lock-free (line-oriented; partial trailing lines are skipped defensively).
+ *
+ * Containment: the path is validated with `validateSwarmPath`, so it can never escape
+ * `.swarm/` (Invariant 4).
+ */
+export declare const BACKGROUND_DELEGATIONS_FILE = "background-delegations.jsonl";
+export type BackgroundDelegationStatus = 'pending' | 'completed' | 'error' | 'stale';
+export interface BackgroundDelegationRecord {
+    schemaVersion: 1;
+    /** Subagent session id from the dispatch envelope — the correlation key. */
+    correlationId: string;
+    /** Structured jobId from dispatch metadata when available, else null. */
+    jobId: string | null;
+    /** Subagent session id (== correlationId; kept explicit for clarity/forward-compat). */
+    subagentSessionId: string;
+    /** Parent (dispatching) session id. */
+    parentSessionId: string;
+    /** Tool callID of the dispatching Task call. */
+    callID: string;
+    /** Canonical swarm role (e.g. "reviewer", "test_engineer"). */
+    normalizedAgent: string;
+    /** Raw, possibly swarm-prefixed agent name (e.g. "mega_reviewer"). */
+    swarmPrefixedAgent: string;
+    /** Plan/evidence task id resolved at dispatch, or null. */
+    planTaskId: string | null;
+    evidenceTaskId: string | null;
+    status: BackgroundDelegationStatus;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Read and fold the store to the latest snapshot per correlationId. Lock-free and
+ * defensive: a missing file yields an empty list, and malformed/partial lines are skipped
+ * (never throws). Records are returned in first-seen correlationId order.
+ *
+ * Cost: O(lines on disk) per call — a full read + parse + fold with no in-memory cache.
+ * This is intentionally simple and acceptable at Stage A volumes (a swarm has few concurrent
+ * background delegations, and the on-disk log is small). If sustained high-throughput
+ * background load ever makes this hot, a future stage should add a stat-invalidated in-memory
+ * cache and/or JSONL compaction (the same future-compaction work noted in the module header).
+ */
+export declare function readDelegations(directory: string): BackgroundDelegationRecord[];
+/** Returns the folded record for a correlationId, or null. Lock-free read. */
+export declare function findByCorrelationId(directory: string, correlationId: string): BackgroundDelegationRecord | null;
+export interface RecordPendingInput {
+    correlationId: string;
+    jobId: string | null;
+    subagentSessionId: string;
+    parentSessionId: string;
+    callID: string;
+    normalizedAgent: string;
+    swarmPrefixedAgent: string;
+    planTaskId: string | null;
+    evidenceTaskId: string | null;
+}
+/**
+ * Record a `pending` background delegation. Runs the stale sweep first (lazy maintenance,
+ * no plugin-init cost), then appends the pending snapshot — all under one lock acquisition
+ * so concurrent dispatches cannot interleave. Best-effort: returns null on lock timeout or
+ * write failure (Stage A has no gate effects, so a missed record is non-fatal).
+ */
+export declare function recordPendingDelegation(directory: string, input: RecordPendingInput, options?: {
+    staleTimeoutMs?: number;
+}): Promise<BackgroundDelegationRecord | null>;
+/**
+ * Public stale sweep: acquires the store lock and marks overdue pendings as `stale`.
+ * Best-effort; returns the number swept (0 on lock timeout / error).
+ */
+export declare function sweepStaleDelegations(directory: string, timeoutMs: number): Promise<number>;

package/dist/background/task-envelope.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Background subagent task-envelope parsing (issue #1151, PR 2 Stage A).
+ *
+ * OpenCode background subagents (v1.16.2) render task dispatch/completion as a stable
+ * XML-ish envelope via the upstream `renderOutput`:
+ *
+ *   <task id="<subagentSessionID>" state="running|completed|error">
+ *   <summary>...</summary>
+ *   <task_result>...</task_result>   (or <task_error> for state="error")
+ *   </task>
+ *
+ * - The dispatch tool result carries `state="running"` and the subagent session id.
+ * - The deferred completion arrives as a synthetic parent message part whose text is the
+ *   same envelope with `state="completed"` or `state="error"`.
+ *
+ * These parsers are intentionally pure and defensive — they never throw — so they can be
+ * used both at dispatch (tool.execute.after output) and at completion observation time.
+ */
+export type TaskEnvelopeState = 'running' | 'completed' | 'error';
+export interface TaskEnvelope {
+    /** The subagent session id from `<task id="...">` — the cross-event correlation key. */
+    sessionId: string;
+    state: TaskEnvelopeState;
+}
+/**
+ * Parse a task envelope from arbitrary text. Returns null when the text does not contain
+ * a well-formed opening `<task id="..." state="...">` tag. Never throws.
+ */
+export declare function parseTaskEnvelope(text: unknown): TaskEnvelope | null;
+/**
+ * Extract the subagent session id and (optional) jobId from a background `Task` dispatch
+ * result (the `tool.execute.after` output object `{ title, output, metadata }`).
+ *
+ * - `subagentSessionId` is parsed from the rendered `output` envelope `<task id="...">`.
+ * - `jobId` is read defensively from `metadata.jobId` (the installed plugin SDK types this
+ *   field as `any`; upstream sets `{ background: true, jobId }`). Absent → null.
+ *
+ * Both are best-effort; either may be null.
+ */
+export declare function extractDispatchIds(output: unknown): {
+    subagentSessionId: string | null;
+    jobId: string | null;
+};

package/dist/cli/index.js

@@ -52,7 +52,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "opencode-swarm",
-    version: "7.54.0",
+    version: "7.56.0",
     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",
@@ -17302,7 +17302,9 @@ var init_schema = __esm(() => {
     delegation_tracker: exports_external.boolean().default(false),
     agent_awareness_max_chars: exports_external.number().min(50).max(2000).default(300),
     delegation_gate: exports_external.boolean().default(true),
-    delegation_max_chars: exports_external.number().min(500).max(20000).default(4000)
+    delegation_max_chars: exports_external.number().min(500).max(20000).default(4000),
+    background_subagents: exports_external.boolean().default(false),
+    background_pending_timeout_minutes: exports_external.number().int().min(1).max(1440).default(30)
   });
   ScoringWeightsSchema = exports_external.object({
     phase: exports_external.number().min(0).max(5).default(1),
@@ -36809,7 +36811,7 @@ function clusterEntries(entries) {
 function uniqueStrings(arr) {
   return [...new Set(arr.filter((s) => typeof s === "string" && s.length > 0))];
 }
-function renderSkillMarkdown(cluster, mode = "active") {
+function renderSkillMarkdown(cluster, mode = "active", generatedAt = new Date().toISOString()) {
   const description = cluster.title.length > 200 ? `${cluster.title.slice(0, 197)}\u2026` : cluster.title;
   const ids = cluster.entries.map((e) => `  - ${e.id}`).join(`
 `);
@@ -36819,6 +36821,9 @@ function renderSkillMarkdown(cluster, mode = "active") {
   lines.push(`description: ${escapeYaml(description)}`);
   lines.push("generated_from_knowledge:");
   lines.push(ids);
+  lines.push("source_knowledge_ids:");
+  lines.push(ids);
+  lines.push(`generated_at: ${generatedAt}`);
   lines.push(`confidence: ${cluster.avgConfidence.toFixed(2)}`);
   lines.push(`status: ${mode === "active" ? "active" : "draft"}`);
   lines.push("---");
@@ -37007,6 +37012,62 @@ async function stampSourceEntries(directory, slug, ids) {
   if (touchedHive)
     await rewriteKnowledge(hivePath, hive);
 }
+function parseDraftFrontmatter(content) {
+  const stripped = content.charCodeAt(0) === 65279 ? content.slice(1) : content;
+  const openFence = stripped.match(/^---[ \t]*\r?\n/);
+  if (!openFence)
+    return null;
+  const fenceLen = openFence[0].length;
+  const closeFence = stripped.slice(fenceLen).match(/\n---[ \t]*(\r?\n|$)/);
+  if (!closeFence)
+    return null;
+  const closeStart = fenceLen + (closeFence.index ?? 0);
+  const body = stripped.slice(fenceLen, closeStart).replace(/\r\n/g, `
+`);
+  const lines = body.split(`
+`);
+  const out = {
+    sourceKnowledgeIds: []
+  };
+  let inLegacyIdsList = false;
+  let inSourceIdsList = false;
+  for (const raw of lines) {
+    const line = raw;
+    if (inLegacyIdsList || inSourceIdsList) {
+      const m = line.match(/^\s+-\s+(\S{1,64})\s*$/);
+      if (m) {
+        out.sourceKnowledgeIds.push(m[1]);
+        continue;
+      }
+      inLegacyIdsList = false;
+      inSourceIdsList = false;
+    }
+    const nm = line.match(/^name:\s*(\S+)\s*$/);
+    if (nm) {
+      out.name = nm[1];
+      continue;
+    }
+    const st = line.match(/^status:\s*(\S+)\s*$/);
+    if (st) {
+      out.status = st[1];
+      continue;
+    }
+    const ga = line.match(/^generated_at:\s*(\S+)\s*$/);
+    if (ga) {
+      out.generatedAt = ga[1];
+      continue;
+    }
+    if (/^generated_from_knowledge:\s*$/.test(line)) {
+      inLegacyIdsList = true;
+      continue;
+    }
+    if (/^source_knowledge_ids:\s*$/.test(line)) {
+      out.sourceKnowledgeIds = [];
+      inSourceIdsList = true;
+    }
+  }
+  return out;
+}
 async function listSkills(directory) {
   const result = {
     proposals: [],
@@ -38336,7 +38397,7 @@ var init_skill_improver_quota = __esm(() => {
 
 // src/services/skill-improver.ts
 import { existsSync as existsSync12 } from "fs";
-import { mkdir as mkdir7, rename as rename5, writeFile as writeFile6 } from "fs/promises";
+import { mkdir as mkdir7, readFile as readFile7, rename as rename5, writeFile as writeFile6 } from "fs/promises";
 import * as path18 from "path";
 function timestampSlug(d) {
   return d.toISOString().replace(/[:.]/g, "-");
@@ -38353,15 +38414,63 @@ async function gatherInventory(directory) {
   const hive = existsSync12(hivePath) ? await readKnowledge(hivePath) : [];
   const archived = [...swarm, ...hive].filter((e) => e.status === "archived").length;
   const skills = await listSkills(directory);
+  const knowledgeById = new Map([...swarm, ...hive].map((entry) => [entry.id, entry]));
+  const staleActiveSkills = [];
+  let metadataReadable = 0;
+  for (const skill of skills.active) {
+    let content;
+    try {
+      content = await readFile7(skill.path, "utf-8");
+    } catch {
+      continue;
+    }
+    const fm = parseDraftFrontmatter(content);
+    if (!fm)
+      continue;
+    metadataReadable += 1;
+    const reasons = [];
+    if (fm.sourceKnowledgeIds.length === 0) {
+      reasons.push("missing_source_knowledge_ids");
+    }
+    if (!fm.generatedAt) {
+      reasons.push("missing_generated_at");
+    } else {
+      const generatedAtMs = Date.parse(fm.generatedAt);
+      if (!Number.isFinite(generatedAtMs)) {
+        reasons.push("invalid_generated_at");
+      } else {
+        for (const id of fm.sourceKnowledgeIds) {
+          const source = knowledgeById.get(id);
+          if (!source) {
+            reasons.push(`missing_source:${id}`);
+            continue;
+          }
+          const updatedAtMs = Date.parse(source.updated_at);
+          if (Number.isFinite(updatedAtMs) && updatedAtMs > generatedAtMs) {
+            reasons.push(`updated_after_generation:${id}`);
+          }
+        }
+      }
+    }
+    if (reasons.length > 0) {
+      staleActiveSkills.push({
+        slug: skill.slug,
+        reasons: reasons.slice(0, 6)
+      });
+    }
+  }
   const matureCandidates = swarm.concat(hive).filter((e) => e.status !== "archived" && e.confidence >= 0.85 && !e.generated_skill_slug && (e.confirmed_by ?? []).length >= 2);
   return {
     knowledge: { swarm: swarm.length, hive: hive.length, archived },
     skills: {
       proposals: skills.proposals.length,
-      active: skills.active.length
+      active: skills.active.length,
+      stale: staleActiveSkills.length,
+      metadataReadable
     },
     highConfidenceClusters: matureCandidates.length,
-    matureCandidates
+    matureCandidates,
+    staleActiveSkills
   };
 }
 function buildSystemPrompt(targets, cfg) {
@@ -38385,10 +38494,16 @@ hive_entries: ${inv.knowledge.hive}
 archived: ${inv.knowledge.archived}
 draft_skills: ${inv.skills.proposals}
 active_skills: ${inv.skills.active}
+active_skills_with_readable_metadata: ${inv.skills.metadataReadable}
+stale_active_skills: ${inv.skills.stale}
 mature_uncompiled_clusters: ${inv.highConfidenceClusters}
 
 TOP MATURE CANDIDATES (first 25):
 ${matureRows || "(none)"}
+
+STALE ACTIVE SKILLS (first 10):
+${inv.staleActiveSkills.slice(0, 10).map((s) => `- ${s.slug} | ${s.reasons.join(", ")}`).join(`
+`) || "(none)"}
 `;
 }
 function isAbortError(err) {
@@ -38417,7 +38532,11 @@ function buildDeterministicProposal(args) {
   lines.push("## Inventory snapshot");
   lines.push(`- Knowledge entries: swarm=${args.inventory.knowledge.swarm}, hive=${args.inventory.knowledge.hive}, archived=${args.inventory.knowledge.archived}`);
   lines.push(`- Generated skills: proposals=${args.inventory.skills.proposals}, active=${args.inventory.skills.active}`);
+  lines.push(`- Active skills with readable metadata: ${args.inventory.skills.metadataReadable} (stale=${args.inventory.skills.stale})`);
   lines.push(`- High-confidence un-skill'd clusters: ${args.inventory.highConfidenceClusters}`);
+  if (args.inventory.staleActiveSkills.length > 0) {
+    lines.push(`- Stale active skills: ${args.inventory.staleActiveSkills.map((s) => s.slug).join(", ")}`);
+  }
   lines.push("");
   lines.push("## Recommendations");
   if (args.inventory.highConfidenceClusters > 0) {
@@ -39912,7 +40031,7 @@ var init_curate = __esm(() => {
 // src/tools/co-change-analyzer.ts
 import * as child_process3 from "child_process";
 import { randomUUID as randomUUID2 } from "crypto";
-import { readdir, readFile as readFile7, stat as stat2 } from "fs/promises";
+import { readdir, readFile as readFile8, stat as stat2 } from "fs/promises";
 import * as path21 from "path";
 import { promisify } from "util";
 function getExecFileAsync() {
@@ -40039,7 +40158,7 @@ async function getStaticEdges(directory) {
   const sourceFiles = await scanSourceFiles(directory);
   for (const sourceFile of sourceFiles) {
     try {
-      const content = await readFile7(sourceFile, "utf-8");
+      const content = await readFile8(sourceFile, "utf-8");
       const importRegex = /(?:import|require)\s*(?:\(?\s*['"`]|.*?from\s+['"`])([^'"`]+)['"`]/g;
       for (let match = importRegex.exec(content);match !== null; match = importRegex.exec(content)) {
         const importPath = match[1].trim();
@@ -40823,11 +40942,11 @@ var init_version_check = __esm(() => {
 
 // src/services/knowledge-diagnostics.ts
 import { existsSync as existsSync14 } from "fs";
-import { readFile as readFile8 } from "fs/promises";
+import { readFile as readFile9 } from "fs/promises";
 async function readRawLines(filePath) {
   if (!existsSync14(filePath))
     return { entries: [], corrupt: 0 };
-  const content = await readFile8(filePath, "utf-8");
+  const content = await readFile9(filePath, "utf-8");
   const entries = [];
   let corrupt = 0;
   for (const line of content.split(`
@@ -46047,7 +46166,7 @@ var KNOWLEDGE_SCHEMA_VERSION = 2;
 // src/hooks/knowledge-migrator.ts
 import { randomUUID as randomUUID3 } from "crypto";
 import { existsSync as existsSync19, readFileSync as readFileSync13 } from "fs";
-import { mkdir as mkdir8, readFile as readFile9, writeFile as writeFile7 } from "fs/promises";
+import { mkdir as mkdir8, readFile as readFile10, writeFile as writeFile7 } from "fs/promises";
 import * as path29 from "path";
 async function migrateKnowledgeToExternal(_directory, _config) {
   return {
@@ -46080,7 +46199,7 @@ async function migrateContextToKnowledge(directory, config3) {
       skippedReason: "no-context-file"
     };
   }
-  const contextContent = await readFile9(contextPath, "utf-8");
+  const contextContent = await readFile10(contextPath, "utf-8");
   if (contextContent.trim().length === 0) {
     return {
       migrated: false,
@@ -47329,7 +47448,7 @@ import { existsSync as existsSync20 } from "fs";
 import {
   appendFile as appendFile5,
   mkdir as mkdir9,
-  readFile as readFile10,
+  readFile as readFile11,
   rename as rename6,
   writeFile as writeFile8
 } from "fs/promises";
@@ -47678,7 +47797,7 @@ function validateLoadedProposals(values, config3) {
 async function readJsonl(filePath) {
   if (!existsSync20(filePath))
     return [];
-  const content = await readFile10(filePath, "utf-8");
+  const content = await readFile11(filePath, "utf-8");
   const records = [];
   for (const line of content.split(`
 `)) {
@@ -47763,7 +47882,7 @@ var init_prompt_block = __esm(() => {
 
 // src/memory/jsonl-migration.ts
 import { existsSync as existsSync21 } from "fs";
-import { copyFile, mkdir as mkdir10, readFile as readFile11, stat as stat3, writeFile as writeFile9 } from "fs/promises";
+import { copyFile, mkdir as mkdir10, readFile as readFile12, stat as stat3, writeFile as writeFile9 } from "fs/promises";
 import * as path31 from "path";
 function resolveMemoryStorageDir(rootDirectory, config3 = {}) {
   const resolved = resolveConfig(config3);
@@ -47827,7 +47946,7 @@ async function readMigrationReport(rootDirectory, config3 = {}) {
   if (!existsSync21(reportPath))
     return null;
   try {
-    return JSON.parse(await readFile11(reportPath, "utf-8"));
+    return JSON.parse(await readFile12(reportPath, "utf-8"));
   } catch {
     return null;
   }
@@ -47928,7 +48047,7 @@ async function readJsonlRows(filePath) {
   if (!existsSync21(filePath)) {
     return { rows: [], invalidRows: [], totalRows: 0 };
   }
-  const content = await readFile11(filePath, "utf-8");
+  const content = await readFile12(filePath, "utf-8");
   const rows = [];
   const invalidRows = [];
   let totalRows = 0;

package/dist/config/schema.d.ts

@@ -93,6 +93,8 @@ export declare const HooksConfigSchema: z.ZodObject<{
     agent_awareness_max_chars: z.ZodDefault<z.ZodNumber>;
     delegation_gate: z.ZodDefault<z.ZodBoolean>;
     delegation_max_chars: z.ZodDefault<z.ZodNumber>;
+    background_subagents: z.ZodDefault<z.ZodBoolean>;
+    background_pending_timeout_minutes: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 export type HooksConfig = z.infer<typeof HooksConfigSchema>;
 export declare const ScoringWeightsSchema: z.ZodObject<{
@@ -958,6 +960,8 @@ export declare const PluginConfigSchema: z.ZodObject<{
         agent_awareness_max_chars: z.ZodDefault<z.ZodNumber>;
         delegation_gate: z.ZodDefault<z.ZodBoolean>;
         delegation_max_chars: z.ZodDefault<z.ZodNumber>;
+        background_subagents: z.ZodDefault<z.ZodBoolean>;
+        background_pending_timeout_minutes: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
     gates: z.ZodOptional<z.ZodObject<{
         syntax_check: z.ZodDefault<z.ZodObject<{