opencode-swarm 6.30.1 → 6.31.0

package/dist/commands/index.d.ts

@@ -1,8 +1,9 @@
-import type { AgentDefinition } from '../agents';
+import type { AgentDefinition } from '../agents/index.js';
 export { handleAgentsCommand } from './agents';
 export { handleAnalyzeCommand } from './analyze';
 export { handleArchiveCommand } from './archive';
 export { handleBenchmarkCommand } from './benchmark';
+export { handleCheckpointCommand } from './checkpoint';
 export { handleClarifyCommand } from './clarify';
 export { handleConfigCommand } from './config';
 export { handleCurateCommand } from './curate';
@@ -17,6 +18,8 @@ export { handleKnowledgeListCommand, handleKnowledgeMigrateCommand, handleKnowle
 export { handlePlanCommand } from './plan';
 export { handlePreflightCommand } from './preflight';
 export { handlePromoteCommand } from './promote';
+export type { CommandContext, CommandEntry, RegisteredCommand, } from './registry.js';
+export { COMMAND_REGISTRY, resolveCommand, VALID_COMMANDS, } from './registry.js';
 export { handleResetCommand } from './reset';
 export { handleRetrieveCommand } from './retrieve';
 export { handleRollbackCommand } from './rollback';

package/dist/commands/registry.d.ts

@@ -0,0 +1,160 @@
+import type { AgentDefinition } from '../agents/index.js';
+export type CommandContext = {
+    directory: string;
+    args: string[];
+    sessionID: string;
+    agents: Record<string, AgentDefinition>;
+};
+export type CommandResult = Promise<string>;
+export type CommandEntry = {
+    handler: (ctx: CommandContext) => CommandResult;
+    /** Human-readable description shown in /swarm help and CLI --help */
+    description: string;
+    /** If true, this command is only accessible as a sub-key of a parent command */
+    subcommandOf?: string;
+};
+export declare const COMMAND_REGISTRY: {
+    readonly status: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Show current swarm state";
+    };
+    readonly plan: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Show plan (optionally filter by phase number)";
+    };
+    readonly agents: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "List registered agents";
+    };
+    readonly history: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Show completed phases summary";
+    };
+    readonly config: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Show current resolved configuration";
+    };
+    readonly 'config doctor': {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Run config doctor checks";
+        readonly subcommandOf: "config";
+    };
+    readonly diagnose: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Run health check on swarm state";
+    };
+    readonly preflight: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Run preflight automation checks";
+    };
+    readonly 'sync-plan': {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Ensure plan.json and plan.md are synced";
+    };
+    readonly benchmark: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Show performance metrics [--cumulative] [--ci-gate]";
+    };
+    readonly export: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Export plan and context as JSON";
+    };
+    readonly evidence: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Show evidence bundles [taskId]";
+    };
+    readonly 'evidence summary': {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Generate evidence summary with completion ratio and blockers";
+        readonly subcommandOf: "evidence";
+    };
+    readonly archive: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Archive old evidence bundles [--dry-run]";
+    };
+    readonly curate: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Run knowledge curation and hive promotion review";
+    };
+    readonly 'dark-matter': {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Detect hidden file couplings via co-change NPMI analysis";
+    };
+    readonly simulate: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Dry-run impact analysis of proposed changes [--target <glob>]";
+    };
+    readonly analyze: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Analyze spec.md vs plan.md for requirement coverage gaps";
+    };
+    readonly clarify: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Clarify and refine an existing feature specification";
+    };
+    readonly specify: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Generate or import a feature specification [description]";
+    };
+    readonly promote: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Manually promote lesson to hive knowledge";
+    };
+    readonly reset: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Clear swarm state files [--confirm]";
+    };
+    readonly rollback: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Restore swarm state to a checkpoint <phase>";
+    };
+    readonly retrieve: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Retrieve full output from a summary <id>";
+    };
+    readonly handoff: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Prepare state for clean model switch (new session)";
+    };
+    readonly turbo: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Toggle Turbo Mode for the active session [on|off]";
+    };
+    readonly 'write-retro': {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Write a retrospective evidence bundle for a completed phase <json>";
+    };
+    readonly 'knowledge migrate': {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Migrate knowledge entries to the current format";
+        readonly subcommandOf: "knowledge";
+    };
+    readonly 'knowledge quarantine': {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Move a knowledge entry to quarantine <id> [reason]";
+        readonly subcommandOf: "knowledge";
+    };
+    readonly 'knowledge restore': {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Restore a quarantined knowledge entry <id>";
+        readonly subcommandOf: "knowledge";
+    };
+    readonly knowledge: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "List knowledge entries";
+    };
+    readonly checkpoint: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Manage project checkpoints [save|restore|delete|list] <label>";
+    };
+};
+export type RegisteredCommand = keyof typeof COMMAND_REGISTRY;
+export declare const VALID_COMMANDS: RegisteredCommand[];
+/**
+ * Resolves compound commands like "evidence summary" and "config doctor".
+ * Tries a two-token compound key first, then falls back to a single-token key.
+ */
+export declare function resolveCommand(tokens: string[]): {
+    entry: CommandEntry;
+    remainingArgs: string[];
+} | null;

package/dist/config/schema.d.ts

@@ -324,6 +324,17 @@ export declare const GuardrailsConfigSchema: z.ZodObject<{
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type GuardrailsConfig = z.infer<typeof GuardrailsConfigSchema>;
+export declare const WatchdogConfigSchema: z.ZodObject<{
+    scope_guard: z.ZodDefault<z.ZodBoolean>;
+    skip_in_turbo: z.ZodDefault<z.ZodBoolean>;
+    delegation_ledger: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type WatchdogConfig = z.infer<typeof WatchdogConfigSchema>;
+export declare const SelfReviewConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    skip_in_turbo: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type SelfReviewConfig = z.infer<typeof SelfReviewConfigSchema>;
 /**
  * Resolves guardrails configuration for a specific agent.
  *
@@ -430,6 +441,7 @@ export declare const SlopDetectorConfigSchema: z.ZodObject<{
     classThreshold: z.ZodDefault<z.ZodNumber>;
     commentStripThreshold: z.ZodDefault<z.ZodNumber>;
     diffLineThreshold: z.ZodDefault<z.ZodNumber>;
+    importHygieneThreshold: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 export type SlopDetectorConfig = z.infer<typeof SlopDetectorConfigSchema>;
 export declare const IncrementalVerifyConfigSchema: z.ZodObject<{
@@ -580,6 +592,15 @@ export declare const PluginConfigSchema: z.ZodObject<{
             idle_timeout_minutes: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>>;
     }, z.core.$strip>>;
+    watchdog: z.ZodOptional<z.ZodObject<{
+        scope_guard: z.ZodDefault<z.ZodBoolean>;
+        skip_in_turbo: z.ZodDefault<z.ZodBoolean>;
+        delegation_ledger: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    self_review: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        skip_in_turbo: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
     tool_filter: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         overrides: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
@@ -722,6 +743,7 @@ export declare const PluginConfigSchema: z.ZodObject<{
         classThreshold: z.ZodDefault<z.ZodNumber>;
         commentStripThreshold: z.ZodDefault<z.ZodNumber>;
         diffLineThreshold: z.ZodDefault<z.ZodNumber>;
+        importHygieneThreshold: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
     incremental_verify: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;

package/dist/hooks/curator-drift-advisory.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hooks/curator-drift.d.ts

@@ -19,7 +19,7 @@ export declare function writeDriftReport(directory: string, report: DriftReport)
  * On any error: emits 'curator.error' event and returns a safe default result.
  * NEVER throws — drift failures must not block phase_complete.
  */
-export declare function runCriticDriftCheck(directory: string, phase: number, curatorResult: CuratorPhaseResult, config: CuratorConfig): Promise<CriticDriftResult>;
+export declare function runCriticDriftCheck(directory: string, phase: number, curatorResult: CuratorPhaseResult, config: CuratorConfig, injectAdvisory?: (message: string) => void): Promise<CriticDriftResult>;
 /**
  * Build a truncated summary suitable for architect context injection.
  * Format: "<drift_report>Phase N: {alignment} ({drift_score}) — {key finding}. {correction if any}.</drift_report>"

package/dist/hooks/delegation-ledger.d.ts

@@ -0,0 +1,37 @@
+/**
+ * DELEGATION LEDGER (v6.31 Task 3.2)
+ *
+ * tool.execute.after hook that maintains a per-session in-memory ledger of tool calls
+ * made during a delegation. When the architect session receives a message (resume),
+ * injects a compact DELEGATION SUMMARY via pendingAdvisoryMessages.
+ *
+ * No file I/O — fully in-memory.
+ */
+export interface LedgerEntry {
+    agent: string;
+    tool: string;
+    file?: string;
+    duration_ms: number;
+    success: boolean;
+    timestamp: number;
+}
+export interface DelegationLedgerConfig {
+    enabled: boolean;
+}
+/**
+ * Creates the delegation ledger hook pair (toolAfter + summary injection).
+ */
+export declare function createDelegationLedgerHook(config: Partial<DelegationLedgerConfig>, _directory: string, // reserved for future use
+injectAdvisory: (sessionId: string, message: string) => void): {
+    toolAfter: (input: {
+        tool: string;
+        sessionID: string;
+        callID: string;
+        args?: Record<string, unknown>;
+    }, output: {
+        title: string;
+        output: string;
+        metadata: unknown;
+    }) => Promise<void>;
+    onArchitectResume: (sessionId: string) => void;
+};

package/dist/hooks/delegation-ledger.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * delegation-ledger.test.ts
+ *
+ * Tests for delegation-ledger hook (Task 3.2):
+ * 1. toolAfter records entries in ledgerBySession
+ * 2. onArchitectResume generates DELEGATION SUMMARY when non-architect tool calls exist
+ * 3. onArchitectResume is no-op when no entries exist
+ * 4. Success is false when output starts with 'Error:'
+ * 5. Success is true for normal output
+ */
+export {};

package/dist/hooks/scope-guard-throw-behavior.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Smoke test: documents the confirmed behavior that tool.execute.before hook
+ * throws propagate as tool rejection, not session crash.
+ *
+ * VERIFIED from src/hooks/guardrails.ts existing patterns:
+ *   - Loop circuit breaker (count >= 5): throw new Error('CIRCUIT BREAKER...')
+ *   - Full test suite block: throw new Error('BLOCKED: Full test suite...')
+ *   - Plan state violation: throw new Error('PLAN STATE VIOLATION...')
+ * All throw in toolBefore, and the plugin propagates as tool rejection.
+ *
+ * SAFE MECHANISM for scope-guard.ts:
+ *   throw new Error(`SCOPE VIOLATION: [agent] attempted to modify [file] not in task [id] scope`)
+ * This is the CORRECT blocking pattern. DO NOT use return-value signals.
+ */
+export {};

package/dist/hooks/scope-guard.adversarial.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hooks/scope-guard.d.ts

@@ -0,0 +1,43 @@
+/**
+ * SCOPE GUARD (v6.31 Task 3.1)
+ *
+ * CONFIRMED THROW MECHANISM: throwing in tool.execute.before propagates as tool rejection,
+ * NOT as session crash. Verified from guardrails.ts multiple existing throw sites.
+ * Safe blocking pattern: throw new Error(`SCOPE VIOLATION: ...`)
+ *
+ * Fires BEFORE write/edit tools execute. When a non-architect agent attempts to
+ * modify a file outside the declared task scope, blocks the call and injects an advisory.
+ */
+/**
+ * Configuration for scope guard behavior.
+ */
+export interface ScopeGuardConfig {
+    /** Whether scope guard is enabled (default: true) */
+    enabled: boolean;
+    /** Whether to skip in turbo mode (default: false — NOT skippable by design) */
+    skip_in_turbo: boolean;
+}
+/**
+ * Creates the scope-guard hook that blocks out-of-scope writes.
+ * @param config - ScopeGuardConfig (enabled, skip_in_turbo)
+ * @param _directory - The workspace directory (reserved for future use)
+ * @param injectAdvisory - Optional callback to push advisory to architect session
+ */
+export declare function createScopeGuardHook(config: Partial<ScopeGuardConfig>, _directory: string, injectAdvisory?: (sessionId: string, message: string) => void): {
+    toolBefore: (input: {
+        tool: string;
+        sessionID: string;
+        callID: string;
+    }, output: {
+        args: unknown;
+    }) => Promise<void>;
+};
+/**
+ * Check if a file path is within declared scope entries.
+ * Handles exact match and directory containment.
+ *
+ * @param filePath - The file path to check
+ * @param scopeEntries - Array of declared scope entries (files or directories)
+ * @returns true if the file is within scope, false otherwise
+ */
+export declare function isFileInScope(filePath: string, scopeEntries: string[]): boolean;

package/dist/hooks/scope-guard.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * scope-guard.test.ts
+ *
+ * Tests for scope-guard hook (Task 3.1):
+ * 1. Returns early (no throw) when guard is disabled (config.enabled = false)
+ * 2. Returns early when tool is not in WRITE_TOOLS set (e.g., 'read')
+ * 3. Returns early when session is the architect (agentName = 'Architect')
+ * 4. Returns early when declaredCoderScope is null (no scope declared)
+ * 5. Throws 'SCOPE VIOLATION' when non-architect writes file outside declared scope
+ * 6. Does NOT throw when non-architect writes file INSIDE declared scope
+ * 7. Sanitizes path with \r\n to prevent log injection (SEC-1 fix)
+ * 8. isFileInScope correctly handles exact match and directory containment
+ */
+export {};

package/dist/hooks/self-review.d.ts

@@ -0,0 +1,14 @@
+export interface SelfReviewConfig {
+    enabled: boolean;
+    skip_in_turbo: boolean;
+}
+export declare function createSelfReviewHook(config: Partial<SelfReviewConfig>, injectAdvisory: (sessionId: string, message: string) => void): {
+    toolAfter: (input: {
+        tool: string;
+        sessionID: string;
+        callID: string;
+    }, output: {
+        args?: Record<string, unknown>;
+        output?: unknown;
+    }) => Promise<void>;
+};

package/dist/hooks/self-review.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * self-review.test.ts
+ *
+ * Tests for self-review hook (Task 4.1):
+ * 1. Advisory injected when architect calls update_task_status with status=in_progress
+ * 2. NOT injected when status=completed (not in_progress)
+ * 3. NOT injected when calling session is not architect
+ * 4. Turbo-skip: NOT injected when session.turboMode=true and skip_in_turbo=true
+ * 5. Disabled: NOT injected when enabled=false
+ * 6. Advisory text contains self-review focus items
+ * 7. injectAdvisory errors are caught (non-blocking)
+ * 8. No advisory for other tools (not update_task_status)
+ */
+export {};

package/dist/hooks/slop-detector.adversarial.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hooks/watchdog.integration.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * WATCHDOG INTEGRATION TEST (v6.31 Task 3.5)
+ *
+ * Integration test covering coordinated watchdog behaviour across:
+ * - scope-guard (3.1): toolBefore hook blocks out-of-scope writes by throwing
+ * - delegation-ledger (3.2): toolAfter hook records tool calls, onArchitectResume generates DELEGATION SUMMARY
+ * - loop-detector enhancement (3.3): at count=3, structured escalation message includes loop pattern + accomplishment + alternative suggestion
+ */
+export {};