opencode-swarm 7.174.0 → 7.176.0

package/dist/observability/startup-contract.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The startup and first-use latency contract (issue #2670).
+ *
+ * Stage model — every interval the issue names, measured and emitted
+ * SEPARATELY as single-line `STARTUP-CONTRACT <json>` rows on stdout:
+ *
+ *   import         performance.now() at the end of src/index.ts module
+ *                  evaluation (ms since performance.timeOrigin, i.e.
+ *                  process start). The fresh-process harness child's own
+ *                  external import timer additionally includes its
+ *                  node:perf_hooks import and preload; the two values are
+ *                  intentionally not expected to be identical.
+ *   server         server() entry -> resolution (the plugin wrapper in
+ *                  src/index.ts).
+ *   first_turn     time from server resolution until the FIRST
+ *                  experimental.chat.messages.transform invocation
+ *                  settles (success or rejection), once per process.
+ *   first_tool     time from server resolution until the FIRST tool
+ *                  execute settles (success or rejection), once per
+ *                  process, labeled with the tool name.
+ *   readiness      queue_settled: the wrapper-owned post-resolution queue
+ *                  has fully drained (every scheduled task settled),
+ *                  measured from drain scheduling. Optional work NEVER
+ *                  gates manifest delivery (AGENTS.md invariant 1).
+ *   optional_task  per-task outcome rows: task name, `completed|failed`,
+ *                  duration from drain start; failed rows carry a bounded
+ *                  error string (<=200 chars, no stack, single line).
+ *
+ * Emission is gated behind OPENCODE_SWARM_DEBUG=1 exactly like
+ * src/utils/logger.ts — ZERO contract rows appear with the env var unset
+ * (no chat-visible noise, invariant 10; asserted by the frozen acceptance
+ * checks' debug-off probe and the unit suite).
+ *
+ * All collectors are in-memory only: no filesystem writes, no awaits added
+ * to any init path, no new module-load side effects beyond one
+ * performance.now() capture (invariant 1). Per-boot state resets on every
+ * server() entry so repeated boots in one process (tests) stay coherent;
+ * the import mark is captured once per process.
+ *
+ * The advisory counter is a STARTUP-window counter: the window opens at
+ * server entry and closes at queue settle (or at server resolution when no
+ * queue is scheduled) and never re-opens — late-session advisories never
+ * contribute to `queue_settled.advisories`.
+ */
+type PostResolutionTaskLike = () => void | Promise<void>;
+interface StartupContractState {
+    importMarkMs: number | null;
+    serverStartMark: number | null;
+    serverResolvedMark: number | null;
+    serverMs: number | null;
+    queueScheduledAt: number | null;
+    queuePending: number;
+    queueTasks: number;
+    queueCompleted: number;
+    queueFailed: number;
+    queueSettled: boolean;
+    queueSettledMs: number | null;
+    advisoryCount: number;
+    advisoryWindowOpen: boolean;
+    firstTurnDone: boolean;
+    firstToolDone: boolean;
+    firstToolName: string | null;
+    firstTurnMs: number | null;
+    firstToolMs: number | null;
+}
+/** Capture the import-stage mark. Called once at src/index.ts module scope. */
+export declare function markStartupImportComplete(): void;
+/**
+ * Begin the server-interval and open the startup advisory window. Resets
+ * per-boot state (the import mark persists). Called at server() entry.
+ */
+export declare function beginStartupServerInterval(): void;
+/** Resolve the server interval and emit the init row. Called just before the wrapper returns its hooks. */
+export declare function endStartupServerInterval(): void;
+/**
+ * Record that optional tasks were scheduled onto the post-resolution queue:
+ * captures the settle-interval origin. Task and pending counts are owned by
+ * the wrapper (one increment per wrapped task, one decrement per settle), so
+ * late-appended tasks are accounted correctly.
+ */
+export declare function noteQueueScheduled(): void;
+/**
+ * Wrap one post-resolution task so its settle outcome is recorded. Settle
+ * tracking is try/finally-structured: a synchronous throw and an async
+ * rejection both record and re-raise, preserving the drain loop's existing
+ * non-fatal catch semantics (src/index.ts). Tasks appended to the array
+ * after a settle still get outcome rows (bounded late-task behavior).
+ */
+export declare function wrapPostResolutionTask(task: PostResolutionTaskLike): PostResolutionTaskLike;
+/**
+ * Observe the FIRST invocation of a host-facing handler (chat transform or
+ * tool execute) without changing it: returns the handler's own result /
+ * promise untouched and attaches a detached observation that records the
+ * first-use interval when the invocation SETTLES (success or rejection —
+ * an errored first call is still a first use). No extra awaits on the
+ * observed path, no writes to any argument, no rebinding.
+ */
+export declare function withStartupFirstUseTracking<Args extends unknown[], Result>(stage: 'first_turn' | 'first_tool', label: string | undefined, handler: (...args: Args) => Result): (...args: Args) => Result;
+/**
+ * Tool-execute specialization of the first-use observation with a FIXED
+ * two-parameter signature: the plugin's ToolDefinition.execute contract is
+ * `(args, ctx) => ...`, and the registration-convention tests assert
+ * `execute.length >= 2` on tool definitions. The wrapper still returns the
+ * wrapped execute's own result untouched and records the interval when the
+ * invocation settles (success or rejection).
+ */
+export declare function withStartupFirstToolTracking<Args, Result>(name: string, execute: (args: Args, ctx: unknown) => Result): (args: Args, ctx: unknown) => Result;
+/**
+ * Count a startup-window advisory (readiness warning). Called from
+ * warning-buffer's addDeferredWarning; the window opens at server entry
+ * and closes at queue settle (never re-opens), so late-session advisories
+ * never contribute.
+ */
+export declare function noteStartupAdvisory(): void;
+/**
+ * The collected contract state, as a structured report.
+ *
+ * @internal Unit-test seam and future surfaces; not a public API.
+ */
+export declare function buildStartupContractReport(): StartupContractState;
+/**
+ * DI seam for testability (repo convention; see src/utils/logger.ts).
+ * Internal calls route through `_internals` so tests can inject a
+ * deterministic performance clock and capture emissions without
+ * mock.module.
+ */
+export declare const _internals: {
+    performance: {
+        now: () => number;
+    };
+    isDebugEnabled: () => boolean;
+    emitLine: (line: string) => void;
+};
+export {};

package/dist/pr-review/types.d.ts

@@ -155,6 +155,14 @@ export type PrReviewEvent = {
     semanticEnvelopeDigest: string;
     outcome: 'CLEAN' | 'FINDINGS' | 'INCOMPLETE';
     existingReceiptDigest?: string | undefined;
+    /**
+     * Provenance marker on the reducer event. Currently no consumer reads
+     * this field — the durable provenance record is the receipt-side
+     * `submittedBy` / `submittedByParentSessionId` (see
+     * `PrReviewResultReceiptSchema`). Kept for ledger parity with the
+     * receipt.
+     */
+    submittedBy?: 'workflow_parent' | undefined;
 } | {
     type: 'circuit_advance_requested';
     nowMs: number;

package/dist/tools/dispatch-lanes.d.ts

@@ -364,6 +364,7 @@ export declare const _internals: {
 };
 export declare const _test_exports: {
     validatePrReviewMicroDispatch: typeof validatePrReviewMicroDispatch;
+    resolveCollectExpectedWorkflowIdentity: typeof resolveCollectExpectedWorkflowIdentity;
     applyCommonPrompt: typeof applyCommonPrompt;
     applyExplorerFormatSuffix: typeof applyExplorerFormatSuffix;
     applyPrWorkflowPromptContract: typeof applyPrWorkflowPromptContract;
@@ -526,6 +527,34 @@ type LaneDiagnostics = Map<string, Set<string>>;
  */
 declare function assembleCollectionDiagnostics(hostTimeouts: ReadonlySet<string>, settleFailureLogs: LaneDiagnostics, collectionResourceFailures: LaneDiagnostics): string[];
 declare function addLaneDiagnostic(diagnostics: LaneDiagnostics, laneLabel: string, message: string): void;
+/**
+ * Issue #2585 live-proof defect (found by AC11 case-01 against the real host,
+ * present byte-identically on main 3ea01cbc7): the collect-time discovery
+ * validation built its `expected` WITHOUT the workflow identity triple, so
+ * `validateExactStructuredReceiptCoverage` rejected EVERY child-submitted
+ * structured receipt with `missing live workflow instance/revision/base
+ * identity` — deterministic, prompt-insensitive, unrepairable from the
+ * orchestrator — and every base dimension settled as a contract failure
+ * (NO_COVERAGE → forced INCOMPLETE). The dispatch-side record carries the
+ * instance (jobId binding) and revision (workflowGeneration); the live gate
+ * state of the dispatching parent carries the merge-base. Derive the triple
+ * from those two authoritative sources instead of leaving it undefined.
+ *
+ * Pure: exported through `_test_exports` for the regression test. Returns
+ * undefined whenever any leg is missing — callers then keep the validator's
+ * explicit missing-identity rejection (today's behavior) rather than guessing.
+ */
+/** Minimal structural slice of the PR_REVIEW gate state the identity needs. */
+interface PrReviewCollectParentStateSlice {
+    mode?: string;
+    workflowInstanceId?: string;
+    prReviewBaseSha?: string;
+}
+export declare function resolveCollectExpectedWorkflowIdentity(record: BackgroundDelegationRecord, parentState: PrReviewCollectParentStateSlice | null): {
+    workflowInstanceId: string;
+    workflowRevision: number;
+    baseSha: string;
+} | undefined;
 declare function consumePrReviewReceiptAppendFailureLog(loggedFailures: Set<string>, parentSessionId: string, correlationId: string): boolean;
 declare function startAsyncLanePrompt(args: {
     session: SessionOps;

package/dist/workflow/coder-settlement.d.ts

@@ -114,6 +114,13 @@ export interface CoderSettlementWalState {
     ownedInProcess: boolean;
     /** A different, still-alive host process owns the dispatch. Never force-releasable from here. */
     ownedByLiveForeignPid: boolean;
+    /**
+     * Generation fence the dispatch declared on its WAL (issue #2665): the
+     * workflow generation the owning transition expected to CAS against.
+     * Retained through recovery status so a stale-generation receipt is
+     * visible without re-reading the WAL bytes.
+     */
+    expectedGeneration?: number;
 }
 /**
  * Bounded inventory of durable coder-settlement WALs for diagnostics and

package/dist/workflow/recovery-invocation.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Static recovery-invocation guidance (issue #2665).
+ *
+ * One shell-correct form per supported shell for the recovery entry points,
+ * plus the category glossary and the deterministic-repair boundary text the
+ * operator runbook publishes. Everything here is a module constant: this
+ * module MUST NOT read environment variables or the host platform, or any
+ * environment signal to choose an invocation string — the contract is
+ * documented per shell, never sniffed (issue #2665 AC3: "without introducing
+ * a new heuristic path detector"; the anti-detection source scan lives in
+ * tests/unit/workflow/task-recovery-status.test.ts).
+ */
+/** The compact operator runbook that carries the full guidance. */
+export declare const RECOVERY_RUNBOOK_DOC_PATH = "docs/troubleshooting/recovery-runbook.md";
+export interface RecoveryInvocationForm {
+    /** Shell or entry surface the form is correct for. */
+    surface: 'host' | 'powershell' | 'git-bash' | 'cli';
+    /** Shell-correct invocation string (placeholders in angle brackets). */
+    invocation: string;
+    /** One-line explanation, including the known friction where relevant. */
+    note: string;
+}
+/**
+ * Shell-correct invocations for `/swarm recover <task_id>`.
+ *
+ * The Git Bash form doubles the leading slash of the `/swarm ...` message
+ * argument: MSYS path conversion rewrites a single leading-slash argument to
+ * a path under the Git install root (`C:/Program Files/Git/swarm ...`) before
+ * the host ever sees it. Setting `MSYS_NO_PATHCONV=1` for the whole
+ * invocation is NOT shell-correct because `--dir /c/...` arguments then stop
+ * converting too.
+ */
+export declare const RECOVERY_INVOCATIONS: readonly RecoveryInvocationForm[];
+/** One-line per-shell quick forms for operator-facing output surfaces. */
+export declare function renderRecoveryInvocationQuickForms(docPath?: string): string;

package/dist/workflow/stage-a-repair.d.ts

@@ -1,3 +1,4 @@
+import { type TaskRecoveryStatus } from './task-recovery-status.js';
 export type StageARepairOutcome = {
     taskId: string;
     outcome: 'repaired';
@@ -26,6 +27,22 @@ export type PreCheckGreennessResult = {
     green: false;
     reason: 'no_pre_check_bundles' | 'pre_check_failed_or_stale';
 };
+export interface StageAScanResult {
+    /** One entry per enumerated task, classified in the shared #2665 vocabulary. */
+    results: TaskRecoveryStatus[];
+    truncated: boolean;
+}
+/**
+ * Read-only wedge scan (issue #2665): classifies every enumerated task via
+ * the shared recovery vocabulary WITHOUT emitting transitions, writing
+ * evidence, or appending events. Tasks whose evidence cannot be read are
+ * skipped (their failure surfaces through the repair path's per-task error
+ * outcomes and the diagnose evidence checks). `repairAllowed` is true only
+ * for the `live_wedge` category with green post-settlement pre-check proof.
+ */
+export declare function scanWedgedStageA(directory: string, options?: {
+    taskIds?: string[];
+}): Promise<StageAScanResult>;
 /**
  * Repair path for tasks already wedged at `coder_delegated`
  * (TASK_WORKFLOW_STAGE_A_REQUIRED post-reset wedge). For each flat task

package/dist/workflow/task-recovery-status.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Task recovery status classification (issue #2665).
+ *
+ * Pure classification over facts the durable receipts already carry: the
+ * coder-settlement WAL inventory (`CoderSettlementWalState`), the per-task
+ * evidence workflow snapshot, and (for the wedge class) the Stage A scan.
+ * This module never reads the filesystem, never writes state, and never
+ * repairs anything — it is the "task/generation-specific missing explanation"
+ * that connects status and repair to the same transition receipts
+ * (`transitionId` + `generation`), per the issue's scope quote: add the
+ * explanation, not another recovery engine.
+ */
+import type { TaskEvidence, TaskWorkflowSnapshot } from '../gate-evidence.js';
+import type { CoderSettlementWalState } from './coder-settlement.js';
+export type TaskRecoveryCategory = 'healthy' | 'missing' | 'stale' | 'ambiguous' | 'corrupt' | 'live_wedge';
+export interface TaskRecoveryStatus {
+    taskId: string;
+    category: TaskRecoveryCategory;
+    /** Workflow generation from the durable evidence snapshot, when one exists. */
+    generation?: number;
+    /** Owning transition id from the settlement WAL / evidence chain tip. */
+    transitionId?: string;
+    /** Deterministic repair allowed without an operator assertion? */
+    repairAllowed: boolean;
+    /** An external (process/provider) effect may still be in flight or unresolved. */
+    uncertainExternalEffect: boolean;
+    explanation: string;
+    /** Host-command-path form; per-shell forms live in recovery-invocation.ts. */
+    suggestedNextCommand: string;
+}
+/**
+ * Classify one settlement-WAL entry against the task's workflow snapshot.
+ *
+ * Category mapping (issue #2665 AC1 vocabulary):
+ * - `unreadable` → corrupt (facts corrupt; recovery refuses, never rewrites)
+ * - owned in this process / by a live foreign pid → ambiguous (external
+ *   effect stays uncertain; never force a foreign owner)
+ * - `DISPATCHED`/`PREPARED` with a dead owner → stale (deterministic repair)
+ * - terminal → healthy
+ *
+ * When the WAL records an `expectedGeneration` that disagrees with the
+ * workflow snapshot's generation, the stale explanation names the generation
+ * conflict explicitly — the settle path's CAS already refuses stale and
+ * foreign receipts; this makes that refusal visible in status.
+ */
+export declare function classifySettlementWalState(entry: CoderSettlementWalState, workflow: TaskWorkflowSnapshot | null): TaskRecoveryStatus;
+/**
+ * Classify a task's evidence-workflow state for recovery purposes. The
+ * `live_wedge` class is the "live-shaped task wedge" of issue #2665 AC2:
+ * the workflow sits at `coder_delegated` with no pre_check gate proof —
+ * deterministically repairable by the Stage A repair (which never re-runs
+ * the coder and never edits evidence speculatively) when green
+ * post-settlement pre-check proof exists.
+ */
+export declare function classifyEvidenceRecoveryTask(taskId: string, evidence: TaskEvidence | null, greenPreCheck: boolean | null): TaskRecoveryStatus;
+/**
+ * One diagnose-detail line per non-healthy task. Healthy tasks are rendered
+ * by their COUNT only (never a per-task line) so no category token can
+ * attach to a healthy task id (plan-critic B1).
+ */
+export declare function renderTaskRecoveryLine(status: TaskRecoveryStatus): string;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "7.174.0",
+	"version": "7.176.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",
@@ -111,6 +111,8 @@
 		"package:smoke": "node scripts/package-smoke.mjs",
 		"prepare": "bun run build",
 		"repro:704": "node scripts/repro-704.mjs",
+		"repro:2669": "node scripts/repro-2669.mjs",
+		"repro:2670": "node scripts/repro-2670.mjs",
 		"repro:1144": "bun scripts/repro-1144.mjs",
 		"repro:1873": "bun build scripts/repro-1873-entry.ts --outdir dist-build-test/repro-1873 --target node --format esm && node scripts/repro-1873.mjs",
 		"repro:2487": "bun build scripts/repro-2487-parity-entry.ts --outdir dist-build-test/repro-2487 --target node --format esm && node scripts/repro-2487-parity.mjs",