opencode-swarm 7.86.0 → 7.87.0

package/dist/turbo/epic/task-commit.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Auto-commit on task completion — Rule 2 of the greenfield-smart redesign.
+ *
+ * When Epic Mode is active for the session and the project is a git repo,
+ * `update_task_status` calls `commitTaskCompletion` after a task transitions
+ * to `completed` and the durable plan write has succeeded. The resulting
+ * commit serves two purposes:
+ *
+ *   1. **Greenfield gate progress.** Each completed-and-committed task
+ *      advances `commitsObserved` so the activation gate
+ *      (`src/turbo/epic/activation.ts`) eventually opens. Without this,
+ *      an Epic-only workflow never produces commits and the gate
+ *      permanently blocks parallel promotion — the exact failure mode
+ *      Rule 4 of the redesign identified.
+ *
+ *   2. **Parallel-eligibility evidence (Rule 3).** Downstream tasks can
+ *      require their `depends:` upstream to be *committed* (not just
+ *      marked complete) before they fan out. The commit message format
+ *      `swarm(task <id>): ...` is the searchable marker the lane
+ *      planner consumes in `upstream-commits.ts`.
+ *
+ * Failure handling: every step degrades non-fatally. A failed commit must
+ * never block the durable task-status update — the plan ledger is the
+ * authoritative source (AGENTS.md #5), git is a downstream artifact.
+ *
+ * Subprocess discipline: delegates to `src/git/branch.ts`, which already
+ * enforces AGENTS.md #3 (explicit cwd, bounded timeout, array-form spawn,
+ * non-interactive). This module adds no new subprocess primitives.
+ */
+/** Result of a single task-commit attempt. */
+export interface CommitTaskCompletionResult {
+    /**
+     * `true` when a `swarm(task <id>):` marker for this taskId is present
+     * in git history at function exit — whether this call produced it
+     * (`reason: 'success'`) or whether an earlier call did
+     * (`reason: 'idempotent-skip'`).
+     *
+     * Phase 17 (B.M9): pre-Phase-17 the `'already-committed'` reason
+     * returned `committed: false`, self-contradicting ("not committed
+     * because already committed"). Architect LLMs interpreted the
+     * `false` as a failure and retried, producing log noise. The fixed
+     * semantic: `committed` answers "is the marker in git for this
+     * taskId now?" — yes for both the fresh-write and the idempotent
+     * skip paths.
+     */
+    committed: boolean;
+    reason: 'no-git' | 'commit-failed' | 'success' | 'idempotent-skip';
+    sha?: string;
+    error?: string;
+}
+export declare function formatTaskCommitMessage(taskId: string, description?: string): string;
+export declare function commitTaskCompletion(directory: string, taskId: string, description?: string, scopePaths?: string[]): Promise<CommitTaskCompletionResult>;
+/**
+ * DI seam — production code calls through `_internals.<name>` so tests
+ * substitute deterministic doubles without `mock.module`'s cross-file
+ * leak (AGENTS.md invariant 7). Restore in `afterEach`.
+ */
+export declare const _internals: {
+    isGitRepo: (cwd: string) => boolean;
+    /**
+     * Stage exactly the declared scope paths for this task. The trailing
+     * `:(exclude).swarm` + `:(exclude).swarm/**` pathspecs are belt-and-
+     * suspenders against AGENTS.md #4 even when the architect's scope
+     * declaration accidentally points into `.swarm/`. We do NOT rely on
+     * the user's `.gitignore`: a single misconfigured project would
+     * otherwise commit prompts, ledgers, telemetry, and evidence into
+     * git history every time Rule 2 fires.
+     *
+     * Missing pathspecs (declared scope points to a non-existent file) are
+     * left to surface as a `commit-failed` reason — better than silent
+     * staging skip, since it tells the user their scope declaration is
+     * stale. Rule 2's non-fatal contract means the plan-write still wins.
+     */
+    stageScopedPaths: (cwd: string, paths: string[]) => void;
+    /**
+     * `--allow-empty` variant of commit. We don't expose this in
+     * `src/git/branch.ts` because it's specific to the task-completion
+     * marker semantics — a normal commit should fail on empty trees to
+     * surface bugs. Here we explicitly want the marker.
+     *
+     * Phase 8: `--no-verify` skips `pre-commit`, `commit-msg`, and
+     * `pre-commit-msg` hooks. Rule 2's commits are protocol markers, not
+     * user-authored content — running Biome/typecheck/lint on every task
+     * completion would add minutes of wall-clock per task and, worse,
+     * could block the marker entirely on a repo with a strict pre-commit
+     * gate. Plan ledger remains authoritative; the commit is the audit
+     * trail, not the gate.
+     */
+    commitAllowEmpty: (cwd: string, message: string) => void;
+    gitHeadSha: (cwd: string) => string;
+    /**
+     * Returns true when a `swarm(task <id>):` marker subject for this
+     * taskId already exists anywhere in git history. Used by the
+     * idempotency guard above so repeat completion calls don't mint
+     * duplicate markers.
+     *
+     * Implementation: `git log --grep=<pattern> -F` is NOT used (it
+     * fixed-string-matches the whole subject); instead we anchor the
+     * regex with `--extended-regexp` and bound the scan with `-n 1` so a
+     * single match suffices. Returns false on any git failure — the
+     * caller treats that as "unknown" and proceeds.
+     */
+    /**
+     * Phase 11 (B5): async sleep used by `commitTaskCompletion`'s
+     * retry loop. Routed through `_internals` so tests can substitute
+     * a no-op stub and not actually wait during fast-path unit tests.
+     */
+    sleep: (ms: number) => Promise<void>;
+    hasExistingTaskCommit: (cwd: string, taskId: string) => boolean;
+};

package/dist/turbo/epic/upstream-commits.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Upstream-commit predicate — Rule 3 of the greenfield-smart redesign.
+ *
+ * Given a project directory, returns a fast `(taskId) => boolean` predicate
+ * that answers "has this task been committed?" The lane planner consults
+ * this when evaluating cross-batch dependencies: a downstream task is
+ * parallel-eligible only when every `depends:` upstream that lives in a
+ * prior phase batch is already in git HEAD's history.
+ *
+ * Why this matters: without it, the planner treats any dep not in the
+ * current task batch as implicitly satisfied (the existing behavior in
+ * `src/turbo/lean/planner.ts:381-390`). That's fine when the prior batch
+ * actually finished cleanly, but it doesn't distinguish "marked complete"
+ * from "marked complete *and* the work is in version control". Rule 3
+ * insists on the stronger condition so parallel coders can't inherit an
+ * uncommitted upstream worktree.
+ *
+ * Source format: `commitTaskCompletion` writes commit subjects shaped like
+ * `swarm(task <id>): <description>` (see `./task-commit.ts:formatTaskCommitMessage`).
+ * This module parses the `<id>` from those subjects.
+ *
+ * Boundedness (AGENTS.md #3): subprocess timeout matches the rest of git
+ * helpers (30s); `--max-count` caps the log scan; failures degrade to a
+ * permissive predicate so the planner does not regress when git is broken.
+ */
+export interface BuildUpstreamCommitsOptions {
+    /** Override the log scan window. Default: 10,000. */
+    maxCommits?: number;
+}
+/**
+ * Eagerly read git log once and return a fast `(taskId) => boolean`
+ * predicate the lane planner uses for cross-batch upstream-commit checks.
+ *
+ * Single evidence source: a `swarm(task <id>):` commit subject in git
+ * log, produced by Rule 2's `commitTaskCompletion`.
+ *
+ * History note: an earlier revision OR'd in a plan-ledger fallback (any
+ * task with `status: completed` in `.swarm/plan.json` was treated as
+ * committed) to guard against a hypothetical deadlock where `commit-
+ * TaskCompletion` failed silently. Phase 5 of the 2026-06-03 corrective
+ * plan made Rule 2 reliable on every completion path by centralizing
+ * the invocation in `plan/manager.updateTaskStatus` — so the guard's
+ * premise no longer holds, and keeping the fallback would defeat Rule 3's
+ * own purpose (distinguishing "marked complete" from "in git history").
+ * Removed in Phase 6.
+ *
+ * Failure mode:
+ *  - Git log read fails (no git, spawn error, timeout) → predicate
+ *    returns `true` for everything (permissive). The lane planner falls
+ *    back to its legacy "cross-batch dep implicitly satisfied" behavior,
+ *    which is the pre-Rule-3 semantics. Better legacy than wedged in a
+ *    broken environment.
+ */
+export declare function buildIsUpstreamCommitted(directory: string, options?: BuildUpstreamCommitsOptions): (taskId: string) => boolean;
+/**
+ * Phase 12 (B10) — same predicate construction as `buildIsUpstreamCommitted`
+ * but exposes whether the git-log read failed. Callers that need to FAIL
+ * CLOSED on a broken git environment (e.g. the Phase 10 activation gate,
+ * where the predicate is the only safety signal) use `gitFailed` to pick
+ * a stricter policy; callers that can tolerate "I don't know" fall-open
+ * (e.g. Rule 3 at the lane planner, where wave ordering is the backstop)
+ * continue using `buildIsUpstreamCommitted` directly.
+ *
+ * The two-tier API exists because the original permissive degradation
+ * was correct for Rule 3 (no regression vs pre-Rule-3 semantics) but
+ * inverted the safety polarity for Phase 10 (which has no Path-B
+ * fallback after the commit-count floor was retired).
+ */
+export interface UpstreamCommittedEvidence {
+    predicate: (taskId: string) => boolean;
+    /** True when the git-log read threw — predicate is the permissive fallback. */
+    gitFailed: boolean;
+}
+export declare function buildIsUpstreamCommittedWithStatus(directory: string, options?: BuildUpstreamCommitsOptions): UpstreamCommittedEvidence;
+/**
+ * DI seam — production code routes the git-log read through `_internals`
+ * so tests can substitute deterministic doubles without `mock.module`
+ * (AGENTS.md invariant 7).
+ */
+export declare const _internals: {
+    readGitLogSubjects: (cwd: string, max: number) => string;
+};

package/dist/turbo/epic/wave-planner.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Epic Mode Wave Planner.
+ *
+ * The wave planner partitions a phase's pending tasks into ordered *waves*.
+ * A wave is a set of tasks that:
+ *   - have all their dependencies satisfied by tasks in completed waves, AND
+ *   - have mutually disjoint declared scopes (no two tasks in the same wave
+ *     touch a shared file or parent/child path).
+ *
+ * Architectural contrast with the lane planner:
+ *   - Lane planner: greedy fill into a fixed number of independent serial
+ *     chains. Branching DAGs (e.g. `A → B → {C, D, E}`) collapse into a
+ *     single chain because the cross-lane-dep rule forbids C/D/E from
+ *     living in a different lane than A/B.
+ *   - Wave planner: emits a sequence of concurrent groups. The same DAG
+ *     becomes `wave 1: [A], wave 2: [B], wave 3: [C, D, E]`. Within a wave
+ *     the architect dispatches one Task per taskId — all in one message —
+ *     and the next wave starts only when the prior one is done.
+ *
+ * The two planners share `runPartitionPreflight` from `partition-common.ts`
+ * so classification (global/protected/no-scope/normal), scope resolution,
+ * and topological sort are identical. Divergence is intentional and lives
+ * only in the assignment loop below.
+ */
+import type { LeanTurboConfig } from '../../config/schema';
+import { type PlanPhase } from '../lean/partition-common';
+import type { LeanTurboDegradedTask } from '../lean/state';
+/**
+ * A single wave in the Epic plan. Tasks in a wave run concurrently; the next
+ * wave starts only after all tasks in this wave complete.
+ */
+export interface EpicWave {
+    /** 1-indexed wave number (display + ordering). */
+    waveId: number;
+    /** Tasks in this wave. Architect dispatches one Task per id, all in one message. */
+    taskIds: string[];
+    /**
+     * Union of declared scope files across the wave. Informational — Epic
+     * Mode does NOT acquire file locks (architect-driven dispatch goes
+     * directly through `Task`, bypassing the lean runner's lock path).
+     * Used for evidence/divergence reporting.
+     */
+    files: string[];
+}
+/**
+ * The complete wave plan produced by `planEpicWaves`.
+ */
+export interface EpicWavePlan {
+    /** The phase number this plan covers. */
+    phase: number;
+    /** Unique identifier for this wave plan. */
+    planId: string;
+    /** Ordered list of waves. Empty when every task degraded or serialized. */
+    waves: EpicWave[];
+    /** Tasks that were serialized (cycles, no-scope, invalid-scope, protected with serialize policy). */
+    serializedTasks: string[];
+    /** Tasks that were degraded (global files, protected paths, Rule-3 leftovers). */
+    degradedTasks: LeanTurboDegradedTask[];
+    /** Human-readable summary when all tasks ended up degraded. */
+    degradationSummary?: string;
+    /** Total number of pending tasks the planner saw (before assignment). */
+    totalPendingTasks: number;
+    /** Sum of `waves[*].taskIds.length` — tasks that will actually run concurrently in a wave. */
+    totalConcurrentTasks: number;
+}
+/**
+ * Partition phase tasks into ordered concurrent waves.
+ *
+ * @param directory - Project root directory
+ * @param phaseNumber - Phase number to plan
+ * @param plan - The full plan object (from `.swarm/plan.json`)
+ * @param config - Lean Turbo configuration (reused for risk/conflict policy)
+ * @param scopes - Optional pre-loaded scopes map (taskId -> file paths)
+ * @param isUpstreamCommitted - Optional Rule-3 predicate (greenfield-smart).
+ *        When supplied, a cross-batch dependency (a `depends:` upstream NOT
+ *        in this planning call's task set) is treated as satisfied only if
+ *        the predicate returns `true`. Without it, legacy semantics apply
+ *        (cross-batch deps implicitly satisfied).
+ * @returns Complete wave plan with ordered concurrent groups.
+ */
+export declare function planEpicWaves(directory: string, phaseNumber: number, plan: {
+    phases: PlanPhase[];
+}, config: LeanTurboConfig, scopes?: Record<string, string[]>, isUpstreamCommitted?: (taskId: string) => boolean): EpicWavePlan;

package/dist/turbo/lean/partition-common.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Shared partition primitives for Lean Turbo's lane planner AND Epic Mode's
+ * wave planner. Both planners run the same three preflight steps:
+ *
+ *   1. Resolve declared scopes (or files_touched fallback) per pending task.
+ *   2. Classify each task by file risk (global / protected / no-scope / normal).
+ *   3. Topologically sort with cycle detection so a downstream task can never
+ *      be released before its upstream.
+ *
+ * They diverge only at the assignment step:
+ *   - Lane planner: greedy fill into a fixed number of serial chains.
+ *   - Wave planner: emit ordered concurrent groups whose membership is gated
+ *     by inter-task scope disjointness.
+ *
+ * Owning the preflight in one place guarantees both planners produce
+ * identical classifications and sort orders for the same inputs.
+ */
+import type { LeanTurboConfig } from '../../config/schema';
+import { type TaskRiskAssessment } from './risk';
+/**
+ * A single task within a plan phase. Matches `.swarm/plan.json`.
+ */
+export interface PlanTask {
+    id: string;
+    description: string;
+    status: 'pending' | 'in_progress' | 'completed' | 'blocked';
+    depends?: string[];
+    files_touched?: string[];
+}
+/**
+ * A phase within a plan, containing multiple tasks.
+ */
+export interface PlanPhase {
+    id: number;
+    name: string;
+    tasks: PlanTask[];
+}
+export type ClassifiedTask = {
+    task: PlanTask;
+    files: string[];
+    hasDeclaredScope: boolean;
+    category: TaskRiskAssessment['category'];
+    conflictReason?: string;
+};
+export interface PartitionPreflight {
+    /** Topologically sorted, lexicographically tie-broken. */
+    sortedTasks: ClassifiedTask[];
+    /** taskId -> ClassifiedTask for O(1) lookup. */
+    taskMap: Map<string, ClassifiedTask>;
+    /** Tasks whose deps form a cycle. Callers must fail-closed: serialize them. */
+    tasksInCycle: Set<string>;
+}
+/**
+ * Validate and normalize a task's declared scope.
+ *
+ * Symlink containment is NOT enforced here — the lock layer resolves symlinks
+ * at acquisition time. This lets architects declare scopes with symlinks for
+ * convenience without compromising actual file-write safety.
+ *
+ * @returns Tuple of [validFiles, invalidCount]
+ */
+export declare function getValidatedFiles(files: string[], directory: string): [string[], number];
+/**
+ * Run the shared preflight: resolve scopes, classify by risk, topo-sort with
+ * cycle detection.
+ *
+ * The same `(directory, pendingTasks, config, scopes)` produces the same
+ * `PartitionPreflight` from both planners.
+ */
+export declare function runPartitionPreflight(directory: string, pendingTasks: PlanTask[], config: LeanTurboConfig, scopes?: Record<string, string[]>): PartitionPreflight;
+/**
+ * Build the predicate that a task's dependencies are all satisfied.
+ *
+ * Rule 3 (greenfield-smart): when `isUpstreamCommitted` is supplied, a
+ * cross-batch dependency (a `depends:` upstream NOT in the current planning
+ * call's task set — typically completed in a prior phase) is treated as
+ * satisfied **only** if the predicate returns `true`. Without the predicate
+ * the legacy semantics apply: cross-batch deps are implicitly satisfied.
+ */
+export declare function makeDependencySatisfactionChecker(taskMap: Map<string, ClassifiedTask>, assignedTasks: Set<string>, isUpstreamCommitted?: (taskId: string) => boolean): (task: ClassifiedTask) => boolean;
+/**
+ * Return the next group of tasks ready for assignment: not yet assigned and
+ * all dependencies satisfied. Lexicographically sorted for determinism.
+ */
+export declare function getReadyTasks(sortedTasks: ClassifiedTask[], assignedTasks: Set<string>, isSatisfied: (task: ClassifiedTask) => boolean): ClassifiedTask[];

package/dist/turbo/lean/planner.d.ts

@@ -48,27 +48,10 @@
  * before conflict detection. This ensures consistent behavior across platforms.
  */
 import type { LeanTurboConfig } from '../../config/schema';
+import { type PlanPhase } from './partition-common';
 import type { LeanTurboCounters, LeanTurboDegradedTask, LeanTurboLane } from './state';
 export { GLOBAL_FILES_LIST, isGlobalFile, isPathSafe, isProtectedPath, normalizePath, PROTECTED_PATTERNS_LIST, pathsConflict, readTaskScopes, } from './conflicts';
-/**
- * A single task within a plan phase.
- * Matches the structure stored in .swarm/plan.json.
- */
-export interface PlanTask {
-    id: string;
-    description: string;
-    status: 'pending' | 'in_progress' | 'completed' | 'blocked';
-    depends?: string[];
-    files_touched?: string[];
-}
-/**
- * A phase within a plan, containing multiple tasks.
- */
-export interface PlanPhase {
-    id: number;
-    name: string;
-    tasks: PlanTask[];
-}
+export type { PlanPhase, PlanTask } from './partition-common';
 /**
  * The complete lane plan produced by `planLeanTurboLanes`.
  * Describes how phase tasks are partitioned into parallel lanes.
@@ -108,8 +91,17 @@ export interface LeanTurboLanePlan {
  * @param plan - The full plan object (from .swarm/plan.json)
  * @param config - Lean Turbo configuration
  * @param scopes - Optional pre-loaded scopes map (taskId -> file paths)
+ * @param isUpstreamCommitted - Optional Rule-3 predicate (greenfield-smart
+ *        redesign). When supplied, a cross-batch dependency (a `depends:`
+ *        upstream not present in this planning call's task set — typically
+ *        completed in a prior phase) is treated as satisfied **only** if
+ *        the predicate returns `true`. Production callers build this from
+ *        `buildIsUpstreamCommitted(directory)` so the check resolves to
+ *        "is there a `swarm(task <id>)` commit in HEAD". When undefined
+ *        the planner falls back to its legacy behavior (cross-batch deps
+ *        are implicitly satisfied) for backward compatibility.
  * @returns Complete lane plan with lanes, degraded tasks, and counters
  */
 export declare function planLeanTurboLanes(directory: string, phaseNumber: number, plan: {
     phases: PlanPhase[];
-}, config: LeanTurboConfig, scopes?: Record<string, string[]>): LeanTurboLanePlan;
+}, config: LeanTurboConfig, scopes?: Record<string, string[]>, isUpstreamCommitted?: (taskId: string) => boolean): LeanTurboLanePlan;

package/dist/utils/index.d.ts

@@ -1,4 +1,4 @@
 export { CLIError, ConfigError, HookError, SwarmError, ToolError, } from './errors';
-export { error, log, warn } from './logger';
+export { criticalWarn, error, log, warn } from './logger';
 export { deepMerge, MAX_MERGE_DEPTH } from './merge';
 export { escapeRegex, simpleGlobToRegex } from './regex';

package/dist/utils/logger.d.ts

@@ -1,6 +1,24 @@
 declare function isDebug(): boolean;
 export declare function log(message: string, data?: unknown): void;
 export declare function warn(message: string, data?: unknown): void;
+/**
+ * Phase 15 (B34): ALWAYS-EMITTED warning. Use this — not `warn()` — for
+ * signals the operator MUST see during a live benchmark or production
+ * run: Rule 2 commit failures, Phase 10 predecessor-evidence anomalies,
+ * Phase 13 git-log-degraded states, Phase 14 lane-planning-blocked
+ * correlations against `epic-promotions.jsonl`, phantom-dep typos.
+ *
+ * Rationale: `warn()` is gated behind `OPENCODE_SWARM_DEBUG=1`. Until
+ * Phase 15 every diagnostic signal Phases 0-14 added was silenced
+ * outside debug runs — including the audit-trail correlation log that
+ * makes B22 wedges detectable. That defeats the whole point of those
+ * signals.
+ *
+ * `criticalWarn` writes to stderr (so it survives stdout redirection
+ * for grading scripts) with a `CRITICAL-WARN` tag distinct from
+ * regular `WARN` so log scrapers can filter for must-act-on lines.
+ */
+export declare function criticalWarn(message: string, data?: unknown): void;
 export declare function error(message: string, data?: unknown): void;
 /**
  * DI seam for testability. Contains all test-mocked exports.
@@ -10,6 +28,7 @@ export declare const _internals: {
     isDebug: typeof isDebug;
     log: typeof log;
     warn: typeof warn;
+    criticalWarn: typeof criticalWarn;
     error: typeof error;
 };
 export {};

package/package.json

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