opencode-swarm 7.116.0 → 7.117.0

package/dist/knowledge/cohort-identity.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Canonical cohort-identity resolver for the linked-swarm knowledge system.
+ *
+ * Problem (issue #1846): the legacy `deriveProjectHash` (in `./identity.ts`)
+ * fed the *raw* `git remote get-url origin` string into SHA-256 with only a
+ * `.trim()`. Equivalent remote spellings (SSH vs scp vs HTTPS, optional `.git`,
+ * slash direction, host/path case, percent-encoding, NFC/NFD) therefore hashed
+ * to *different* cohort ids, fragmenting the linked store. When no origin was
+ * present it hashed the absolute worktree path, so sibling worktrees of the
+ * same repository became unrelated cohorts.
+ *
+ * This module is the single canonical identity resolver used by linking (and,
+ * going forward, status, diagnostics, cache keys, hive provenance, and worktree
+ * suggestions). Resolution order (issue #1846 §1):
+ *
+ *   1. Normalize a configured Git remote into a provider-neutral host/path
+ *      identity so equivalent spellings converge.
+ *   2. If no usable remote exists, derive identity from a repository-stable Git
+ *      identity shared by sibling worktrees (`git rev-parse --git-common-dir`).
+ *      This fallback is machine-local (not portable across machines), so it is
+ *      flagged `degraded: true` with a visible warning.
+ *   3. Only then fall back to a normalized absolute path (also `degraded`).
+ *
+ * Subprocess contract (AGENTS.md invariant 3): array-form `execFile('git', …)`,
+ * explicit `git -C <dir>`, `stdin` closed immediately, bounded `maxBuffer`, and
+ * a `timeout` — Node's `execFile` sends SIGTERM (then SIGKILL) on timeout, so
+ * the child is terminated without a manual `kill()`. A defensive `child.on('error')`
+ * guard resolves the promise rather than hanging on a spawn failure. This
+ * mirrors the compliant precedent in `src/session/worktree-link-suggestion.ts`.
+ *
+ * This module performs NO writes and holds NO module-level state (invariant 8).
+ * It is NOT imported on the plugin-init path (invariant 1); the only caller is
+ * `/swarm link` and, lazily, diagnostics — never `server()` resolution.
+ */
+export type CohortIdentitySource = 'remote' | 'git-common-dir' | 'path';
+export interface CohortIdentity {
+    /** 12-hex cohort id (SHA-256 prefix). */
+    cohortId: string;
+    /** How the id was derived. */
+    source: CohortIdentitySource;
+    /** Normalized remote (host/owner/repo) when source === 'remote'. */
+    normalizedRemote?: string;
+    /**
+     * True when the id is machine-local rather than portable across machines
+     * (git-common-dir or path fallback). A degraded cohort is still a strict
+     * improvement over per-worktree isolation, but it is NOT a portable cohort
+     * identity and must be surfaced as a visible warning (issue #1846 §1.3).
+     */
+    degraded: boolean;
+}
+/**
+ * Normalize an arbitrary Git remote URL into a canonical `host/owner/repo`
+ * string. Equivalent SSH/scp/HTTPS spellings, optional `.git`, slash
+ * direction, host/scheme case, path case (for known case-insensitive hosts),
+ * percent-encoding, default ports, userinfo, and NFC/NFD all converge.
+ *
+ * Returns `null` when the input cannot be parsed into a host/owner/repo triple.
+ */
+export declare function normalizeGitRemote(rawUrl: string): string | null;
+/**
+ * Run `git -C <dir> <args...>` and return stdout (trimmed) or null on any
+ * failure/timeout. Compliant subprocess contract (invariant 3): array form,
+ * explicit cwd via `-C`, stdin closed immediately, bounded `maxBuffer`, and a
+ * bounded `timeout` — Node's `execFile` sends SIGTERM (then SIGKILL) on
+ * timeout, so the child is terminated without a manual `kill()`. A defensive
+ * `child.on('error')` guard resolves the promise rather than hanging on a
+ * spawn failure.
+ */
+declare function runGit(directory: string, args: string[]): Promise<string | null>;
+/** SHA-256 prefix (12 hex) — matches the legacy `deriveProjectHash` width. */
+declare function cohortHash(input: string): string;
+/**
+ * Fold a realpath'd absolute path into a stable cohort-id input. On Windows,
+ * path separators and drive-letter case are insignificant, and `realpathSync`
+ * can emit an extended-length `\\?\` prefix for one spelling of a path but not
+ * another; none of these differences should split a cohort, so we fold them
+ * all. A trailing separator is likewise insignificant. This is defence in
+ * depth: the primary convergence guarantee comes from asking git for the
+ * ABSOLUTE common dir (see `resolveCohortId`), which hands every worktree of a
+ * repo one identical string; this folding only removes any residual spelling
+ * difference that survives realpath.
+ */
+declare function stabilizePath(input: string): string;
+/**
+ * Resolve the canonical cohort identity for a worktree directory.
+ *
+ * Resolution order:
+ *   1. Normalized origin remote (portable cohort identity; not degraded).
+ *   2. `git rev-parse --path-format=absolute --git-common-dir` — shared by
+ *      sibling worktrees of the same repo, but machine-local → degraded.
+ *   3. Realpath of the directory — last resort, machine-local → degraded.
+ *
+ * Never throws. The path fallback always succeeds.
+ */
+export declare function resolveCohortId(directory: string): Promise<CohortIdentity>;
+export declare const _internals: {
+    normalizeGitRemote: typeof normalizeGitRemote;
+    runGit: typeof runGit;
+    cohortHash: typeof cohortHash;
+    stabilizePath: typeof stabilizePath;
+    GIT_TIMEOUT_MS: number;
+};
+export {};

package/dist/knowledge/config-fingerprint.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Cohort config fingerprint (issue #1846 §4).
+ *
+ * @status planned-future-use. The helper and its tests ship in this foundation
+ * PR, but it is NOT yet wired into `link`/`unlink` or the diagnostics surfaces.
+ * Cohort-agreement enforcement (fail-closed on mismatch for destructive ops)
+ * lands with #1847/#1823, which consume the cohort-status source this PR
+ * establishes. Shipping the primitive + tests now lets those dependents adopt
+ * it without re-deriving the field set.
+ *
+ * A deterministic hash of the configuration fields that change retrieval,
+ * curation, validation, or lifecycle semantics for the swarm knowledge tier.
+ * Two linked worktrees SHOULD share the same fingerprint; a mismatch means the
+ * cohort members will rank/quarantine/promote lessons differently.
+ *
+ * Only fields that affect *what the cohort stores and how it behaves* are
+ * fingerprinted — not cosmetic or session-local tuning. The set is deliberately
+ * conservative: adding a field later only changes the fingerprint when that
+ * field's value differs, which is exactly the signal we want.
+ */
+/**
+ * The config-shape fingerprint input. Callers project their knowledge config
+ * into this loose shape; only the keys present are hashed.
+ */
+export interface CohortConfigFingerprintInput {
+    dedup_threshold?: number;
+    scope_filter?: readonly string[];
+    validation_enabled?: boolean;
+    evergreen_confidence?: number;
+    evergreen_utility?: number;
+    low_utility_threshold?: number;
+    default_max_phases?: number;
+    todo_max_phases?: number;
+    confidence_floor_action?: string;
+    contradiction_threshold_action?: string;
+    contradiction_quarantine_threshold?: number;
+    directive_min_confidence?: number;
+    schema_version?: number;
+    swarm_max_entries?: number;
+    retrieval?: {
+        mmr_lambda?: number;
+        cold_start_bonus?: number;
+        synonym_min_cooccurrence?: number;
+    };
+}
+/**
+ * Compute a deterministic 12-hex fingerprint for cohort-agreement checks.
+ * Stable key ordering (sorted JSON) ensures equivalent configs hash equally
+ * regardless of field insertion order.
+ */
+export declare function cohortConfigFingerprint(input: CohortConfigFingerprintInput): string;
+declare function sortKeys(value: unknown): unknown;
+export declare const _internals: {
+    cohortConfigFingerprint: typeof cohortConfigFingerprint;
+    sortKeys: typeof sortKeys;
+};
+export {};

package/dist/knowledge/family-manifest.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Authoritative knowledge-family manifest for the linked-swarm knowledge system.
+ *
+ * Problem (issue #1846): `link`/`unlink` previously hardcoded a *single* family
+ * member (`knowledge.jsonl`) while the link-aware resolvers quietly redirected
+ * all seven. The two sources of truth drifted, so pre-link local copies of the
+ * other six members were silently orphaned at link time and lost at unlink
+ * time. Adding a new family file required editing two commands in lockstep — a
+ * classic omission hazard.
+ *
+ * This manifest is the single source of truth for *which* artifacts participate
+ * in link/unlink family migration and *how* each is merged. `link` and `unlink`
+ * both iterate it, so a new family member is a one-line edit here.
+ *
+ * Merge strategies:
+ *  - `dedup-id-merge`: id-dedup with provenance-preserving near-duplicate merge
+ *    (union fields, evidence-weighted confidence, preserve losing id in
+ *    `merged_from`). Used for the active store.
+ *  - `append-union`: union by the line's stable id field (event id / entry id),
+ *    appending only lines whose id is not already present on the destination.
+ *    Idempotent on retry/relink.
+ *  - `sum-counters`: per-counter field-wise SUM, reusing the existing
+ *    `mergeRollupInto` primitive (shown/applied/... counts sum; timestamps take
+ *    the max). Used for the counter baseline JSON.
+ *
+ * NOT in the manifest (deliberate exceptions, documented in
+ * `knowledge-link.ts` "Intentionally NOT redirected"):
+ *  - `synonym-map.json` — derived state. It is rebuilt deterministically from
+ *    the linked `knowledge.jsonl` corpus on link rather than migrated, so recall
+ *    is deterministic across the cohort (issue #1846 §4, critic C4).
+ *  - `.knowledge-shown.json`, `plan.json`, evidence, session state — per
+ *    worktree by design.
+ */
+export type FamilyRole = 'store' | 'events' | 'rejected' | 'retractions' | 'counters' | 'quarantine' | 'unactionable' | 'application-legacy';
+export type FamilyMergeStrategy = 'dedup-id-merge' | 'append-union' | 'sum-counters';
+export interface KnowledgeFamilyMember {
+    /** Filename within the swarm family directory (e.g. `knowledge.jsonl`). */
+    readonly filename: string;
+    readonly role: FamilyRole;
+    readonly mergeStrategy: FamilyMergeStrategy;
+    /** True when unlink may copy this member back to the local worktree. */
+    readonly reversible: boolean;
+}
+/**
+ * The complete knowledge family that participates in cohort linking.
+ * Adding a member here automatically includes it in link + unlink migration.
+ */
+export declare const KNOWLEDGE_FAMILY: readonly KnowledgeFamilyMember[];
+/** Filenames of every family member, for quick membership checks. */
+export declare const FAMILY_FILENAMES: readonly string[];

package/dist/knowledge/family-migration.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Cohort family-migration engine for the linked-swarm knowledge system.
+ *
+ * Drives both `/swarm link` and `/swarm unlink` off the single
+ * {@link KNOWLEDGE_FAMILY} manifest (issue #1846 §3). Replaces the prior
+ * single-file (`knowledge.jsonl`-only) migration that silently orphaned the
+ * other six family members.
+ *
+ * Design (issue #1846, critic-reviewed plan W3/W4):
+ *  - One manifest drives link + unlink, so a new family member cannot be
+ *    silently omitted.
+ *  - Three merge strategies: `dedup-id-merge` (provenance-preserving store
+ *    merge), `append-union` (id-keyed union for append-only logs),
+ *    `sum-counters` (per-counter SUM for the baseline JSON, reusing
+ *    `mergeRollupInto`).
+ *  - All-or-nothing commit: stage the entire merged family into a sibling
+ *    staging directory, validate every file, then commit atomically. The
+ *    pointer is flipped last by the caller.
+ *  - Lock discipline: acquire the destination store's directory lock first,
+ *    read source files under a *brief* source-store lock (released before the
+ *    long merge/validate work), so a long migration cannot have its lock
+ *    stolen by `stale` expiry and cannot deadlock against the hot path.
+ *
+ * No writes happen here on the plugin-init path (invariant 1). Locks are
+ * `proper-lockfile` directory locks with a bumped `stale` for the migration
+ * critical section (invariant 3, critic C9).
+ */
+import type { CounterRollup } from '../hooks/knowledge-events.js';
+import type { KnowledgeEntryBase } from '../hooks/knowledge-types.js';
+import { type KnowledgeFamilyMember } from './family-manifest.js';
+export interface FamilyMigrationCounts {
+    /** Per-member counts (filename → {merged, skipped}). */
+    readonly perMember: ReadonlyArray<{
+        filename: string;
+        merged: number;
+        skipped: number;
+    }>;
+}
+/**
+ * Provenance-preserving merge of the active store (`dedup-id-merge`).
+ *
+ * Exact-id duplicates: skip (already present). Near-duplicates (Jaccard bigram
+ * similarity ≥ threshold): merge fields rather than drop — union `confirmed_by`,
+ * `tags`, `source_refs`; union retrieval outcomes by unique outcome key;
+ * confidence becomes an evidence-weighted average; the losing entry's `id` is
+ * preserved in `merged_from` for retraction traceability. A `merge` is NOT
+ * silent. (Critic C8: this is "provenance-preserving", not "lossless".)
+ */
+declare function mergeStoreEntries(destination: KnowledgeEntryBase[], source: KnowledgeEntryBase[]): {
+    merged: KnowledgeEntryBase[];
+    added: number;
+    skipped: number;
+};
+/** Field-level union of `src` into `target` (mutates target). */
+declare function mergeEntryFields(target: KnowledgeEntryBase, src: KnowledgeEntryBase): void;
+/**
+ * Append-union: append source lines whose id is not already present on the
+ * destination. Lines without an id field are skipped (we cannot dedup them
+ * safely, and every family member here is id-keyed).
+ */
+declare function appendUnionById<T>(destination: T[], source: T[]): {
+    merged: T[];
+    added: number;
+    skipped: number;
+};
+/**
+ * Sum-counters: merge two baseline JSON objects (`Record<id, CounterRollup>`)
+ * by per-id field-wise sum, reusing the canonical `mergeRollupInto` primitive.
+ */
+declare function sumCounters(destination: Record<string, CounterRollup>, source: Record<string, CounterRollup>): {
+    merged: Record<string, CounterRollup>;
+    added: number;
+    skipped: number;
+};
+/** Serialize a merged family member to its on-disk representation. */
+declare function serialize(member: KnowledgeFamilyMember, data: unknown): string;
+/**
+ * Validate a serialized merged member BEFORE commit. This is a real integrity
+ * gate, not a vacuous JSON-parseability check: each line must parse AND, for
+ * the store member, each entry must carry the required `id`/`lesson` shape so a
+ * corrupted merge (e.g. an entry that lost its id) is rejected before it reaches
+ * the destination. A failure aborts the migration — the destination stays
+ * untouched and the caller never flips the pointer, so a retry is safe.
+ */
+declare function validateSerialized(member: KnowledgeFamilyMember, serialized: string): boolean;
+/**
+ * Migrate the complete knowledge family from `sourceDir` into `destinationDir`,
+ * merging each member according to its manifest strategy. All-or-nothing:
+ * stage → validate → commit. The pointer is NOT touched here (caller flips it).
+ *
+ * Returns per-member merge counts. Throws on validation failure (caller
+ * surfaces the error; the destination is left untouched).
+ *
+ * @param destinationDir the cohort store that absorbs the merge (link → shared;
+ *   unlink → local `.swarm`).
+ * @param sourceDir the store whose family is merged in (link → local `.swarm`;
+ *   unlink → shared).
+ */
+export declare function migrateKnowledgeFamily(destinationDir: string, sourceDir: string): Promise<FamilyMigrationCounts>;
+export declare const _internals: {
+    mergeStoreEntries: typeof mergeStoreEntries;
+    appendUnionById: typeof appendUnionById;
+    sumCounters: typeof sumCounters;
+    mergeEntryFields: typeof mergeEntryFields;
+    serialize: typeof serialize;
+    validateSerialized: typeof validateSerialized;
+    MIGRATION_LOCK_STALE_MS: number;
+};
+export {};

package/dist/knowledge/identity.d.ts

@@ -16,11 +16,21 @@ export interface ProjectIdentity {
 export declare function resolveIdentityPath(projectHash: string): string;
 /**
  * Derive a deterministic project hash from a directory.
- * Uses git remote URL if available, otherwise falls back to absolute path.
+ *
+ * @deprecated Since issue #1846. This synchronous helper is retained for
+ * backward compatibility (and its existing test coverage) but the canonical,
+ * normalization-correct, subprocess-compliant resolver is
+ * {@link resolveCohortId} in `./cohort-identity.ts`. New callers MUST use
+ * `resolveCohortId`; it normalizes equivalent remotes (SSH/scp/HTTPS, `.git`,
+ * case, slashes, percent-encoding, NFC), falls back through
+ * `git rev-parse --git-common-dir` before the path, and uses the compliant
+ * array-form subprocess contract. This legacy helper is kept only so existing
+ * imports keep compiling; it delegates to the legacy un-normalized logic.
  *
  * Worktrees of the same repository share a git remote, so they derive the same
  * hash — which is what lets `/swarm link` (with no name) tie them to one shared
- * knowledge store by default.
+ * knowledge store by default. (Note: this legacy form does NOT normalize
+ * equivalent remote spellings; `resolveCohortId` does.)
  */
 export declare function deriveProjectHash(directory: string): string;
 /**

package/dist/knowledge/index.d.ts

@@ -1,2 +1,3 @@
 /** Knowledge system exports for opencode-swarm. */
+export * from './cohort-identity.js';
 export * from './identity.js';

package/dist/services/knowledge-diagnostics.d.ts

@@ -46,6 +46,33 @@ export interface KnowledgeDebugMeta {
         /** Knowledge-event volume bucketed by type (applied/ignored/violated/...). */
         events_by_type: Record<string, number>;
     };
+    /**
+     * Cohort/link health (issue #1846). Makes the linked store and its health
+     * obvious to an operator/architect. `null` when link state cannot be read.
+     */
+    cohort: {
+        /** True when this worktree redirects its knowledge family to a shared store. */
+        linked: boolean;
+        /** Pointer schema version (1 = legacy, 2 = cohort-aware). */
+        pointer_version: 1 | 2 | null;
+        /** Link id (shared store directory segment). */
+        link_id: string | null;
+        /** Canonical cohort id (issue #1846 W1), when known. */
+        cohort_id: string | null;
+        /** How the cohort id was derived. */
+        identity_source: 'remote' | 'git-common-dir' | 'path' | null;
+        /** True when the cohort id is machine-local (not portable). */
+        degraded: boolean;
+        /** Resolved shared root, when linked. */
+        shared_root: string | null;
+        /** Pointer generation (bumped on each link/unlink), when known. */
+        generation: number | null;
+        /**
+         * True when a local knowledge.jsonl coexists with an active link (the
+         * pre-link local store was retained). Benign but worth surfacing.
+         */
+        local_orphaned: boolean;
+    };
 }
 /**
  * Compute the debug-metadata block for the knowledge system. Best-effort: never

package/dist/services/status-service.d.ts

@@ -78,6 +78,19 @@ export interface StatusData {
     unactionableQueueDepth?: number;
     /** #1234 Part 3: pending insight candidates awaiting phase boundary consumption */
     insightCandidatesPending?: number;
+    /**
+     * Cohort/link status (issue #1846). Makes the linked knowledge store and its
+     * health obvious in `/swarm status`. `undefined` when link state is absent.
+     */
+    cohort?: {
+        linked: boolean;
+        linkId?: string;
+        cohortId?: string;
+        identitySource?: 'remote' | 'git-common-dir' | 'path';
+        degraded?: boolean;
+        sharedRoot?: string;
+        generation?: number;
+    };
 }
 /**
  * Get status data from the swarm directory.

package/dist/utils/swarm-artifact-cache.d.ts

@@ -19,5 +19,18 @@ export declare function readCachedTextFileSync(filePath: string, directRead: ()
 export declare function readCachedTextFile(filePath: string, directRead: () => Promise<string | null>): Promise<string | null>;
 export declare function readCachedParsedFileSync<T>(filePath: string, namespace: string, readText: () => string | null, parse: (content: string) => T): T | null;
 export declare function readCachedParsedFile<T>(filePath: string, namespace: string, readText: () => Promise<string | null>, parse: (content: string) => T): Promise<T | null>;
+/**
+ * Drop any cached text/parsed entries for `filePath` immediately after a write.
+ *
+ * The stat-based staleness check (mtimeMs + ctimeMs + size) is a best-effort
+ * optimization: a same-size rewrite that lands within one filesystem timestamp
+ * tick of a prior cached read can produce an identical stamp, so the very next
+ * read-your-own-write can silently return the pre-write value (issue #1729).
+ * Writers that read-modify-write the same path twice in quick succession (e.g.
+ * a second locked transaction immediately after an atomic write) MUST call
+ * this after the write so the next read cannot observe stale content —
+ * relying on stat-stamp comparison alone is not sufficient in that window.
+ */
+export declare function invalidateCachedArtifact(filePath: string): void;
 export declare function resetSwarmArtifactCache(): void;
 export declare function getSwarmArtifactCacheStats(): SwarmArtifactCacheStats;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "7.116.0",
+	"version": "7.117.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",