agentic-qe 3.10.4 → 3.10.6

package/dist/cli/commands/hooks-handlers/hooks-dream-learning.js

@@ -266,6 +266,61 @@ export async function persistTaskOutcome(opts) {
         db.pragma('busy_timeout = 60000');
     }
     catch { /* hook-side patient timeout (ADR-001 / patch 260) */ }
+    // Fresh-project fix (found by ADR-101 E2E): captured_experiences is created
+    // by the experience-capture middleware, not the unified schema — on a fresh
+    // .agentic-qe the whole Stream B transaction silently failed against the
+    // missing table. Same canonical DDL as experience-replay.ts ensureSchema.
+    // Fail-soft: an unexpected legacy shape must not kill the learning txn —
+    // the inserts below will surface real problems.
+    try {
+        db.exec(`
+    CREATE TABLE IF NOT EXISTS captured_experiences (
+      id TEXT PRIMARY KEY,
+      task TEXT NOT NULL,
+      agent TEXT NOT NULL,
+      domain TEXT NOT NULL DEFAULT '',
+      success INTEGER NOT NULL DEFAULT 0,
+      quality REAL NOT NULL DEFAULT 0.5,
+      duration_ms INTEGER NOT NULL DEFAULT 0,
+      model_tier INTEGER,
+      routing_json TEXT,
+      steps_json TEXT,
+      result_json TEXT,
+      error TEXT,
+      started_at TEXT NOT NULL DEFAULT (datetime('now')),
+      completed_at TEXT NOT NULL DEFAULT (datetime('now')),
+      source TEXT DEFAULT 'middleware',
+      application_count INTEGER DEFAULT 0,
+      avg_token_savings REAL DEFAULT 0,
+      embedding BLOB,
+      embedding_dimension INTEGER,
+      tags TEXT,
+      last_applied_at TEXT
+    );
+    CREATE TABLE IF NOT EXISTS experience_applications (
+      id TEXT PRIMARY KEY,
+      experience_id TEXT NOT NULL,
+      task TEXT NOT NULL,
+      success INTEGER NOT NULL,
+      tokens_saved INTEGER DEFAULT 0,
+      feedback TEXT,
+      applied_at TEXT DEFAULT (datetime('now')),
+      FOREIGN KEY (experience_id) REFERENCES captured_experiences(id) ON DELETE CASCADE
+    );
+    CREATE INDEX IF NOT EXISTS idx_exp_apps_experience ON experience_applications(experience_id);
+  `);
+    }
+    catch { /* legacy shape — inserts below report real failures */ }
+    // ADR-101 hotfix (v3.10.5 publish gate): qe_trajectories created by older
+    // versions (and minimal test fixtures) lacks metadata_json — naming it in
+    // the INSERT threw and aborted the whole transaction. Migrate in place.
+    try {
+        const trajCols = db.prepare(`PRAGMA table_info(qe_trajectories)`).all();
+        if (trajCols.length > 0 && !trajCols.some((c) => c.name === 'metadata_json')) {
+            db.exec(`ALTER TABLE qe_trajectories ADD COLUMN metadata_json TEXT`);
+        }
+    }
+    catch { /* fail-soft */ }
     const experienceId = `exp-${Date.now()}-${randomUUID().slice(0, 8)}`;
     const taskField = `${opts.agent}:${opts.taskId}`;
     const durationMs = opts.durationMs ?? 0;
@@ -394,11 +449,19 @@ export async function persistTaskOutcome(opts) {
             console.error(chalk.dim(`[hooks] post-task bridge: ${bridgeErr instanceof Error ? bridgeErr.message : 'unknown'}`));
         }
         // 5. Single-step qe_trajectories row
+        // ADR-101: nesting provenance lands in the metadata_json blob (stage 1 —
+        // no dedicated columns / schema migration)
         const trajId = `traj-${Date.now()}-${randomUUID().slice(0, 8)}`;
+        const provenanceJson = opts.parentAgentId !== undefined || opts.depth !== undefined
+            ? JSON.stringify({
+                ...(opts.parentAgentId !== undefined ? { parentAgentId: opts.parentAgentId } : {}),
+                ...(opts.depth !== undefined ? { depth: opts.depth } : {}),
+            })
+            : null;
         db.prepare(`
-      INSERT INTO qe_trajectories (id, task, agent, domain, started_at, ended_at, success, steps_json)
-      VALUES (?, ?, ?, ?, datetime('now'), datetime('now'), ?, ?)
-    `).run(trajId, taskField, opts.agent, opts.domain ?? 'general', opts.success ? 1 : 0, JSON.stringify([{ step: 1, task: opts.taskId, success: opts.success }]));
+      INSERT INTO qe_trajectories (id, task, agent, domain, started_at, ended_at, success, steps_json, metadata_json)
+      VALUES (?, ?, ?, ?, datetime('now'), datetime('now'), ?, ?, ?)
+    `).run(trajId, taskField, opts.agent, opts.domain ?? 'general', opts.success ? 1 : 0, JSON.stringify([{ step: 1, task: opts.taskId, success: opts.success }]), provenanceJson);
         // 6. Multi-step stitch — siblings sharing the same suffix taskId in the
         // last hour. Only fires when ≥2 unconsolidated siblings exist.
         try {

package/dist/cli/commands/hooks-handlers/nesting-provenance.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Agentic QE v3 - Nested-Subagent Provenance Validation (ADR-101)
+ *
+ * Parses and validates the `--parent-agent-id` / `--depth` flags on
+ * `aqe hooks post-task`. Anthropic announced nested subagent support
+ * (depth=5) on 2026-06-09; recording which agent spawned a task and at
+ * what depth lets ReasoningBank segment patterns per hierarchy level —
+ * useful today for flat depth-1 spawns, and ready for deep chains the
+ * day the upstream `Task` denylist lifts.
+ */
+/** Defensive bound — well above Anthropic's announced depth=5 cap */
+export declare const MAX_NESTING_DEPTH = 32;
+export interface NestingProvenance {
+    parentAgentId?: string;
+    depth?: number;
+}
+export interface NestingProvenanceResult extends NestingProvenance {
+    /** Set when validation failed; the caller should reject the invocation */
+    error?: string;
+}
+/**
+ * Validate raw flag values. Both flags are optional and independent;
+ * depth=0 is a valid value (top-level) and must survive as 0, not be
+ * coerced to undefined.
+ */
+export declare function parseNestingProvenance(parentAgentIdRaw?: string, depthRaw?: string | number): NestingProvenanceResult;
+//# sourceMappingURL=nesting-provenance.d.ts.map

package/dist/cli/commands/hooks-handlers/nesting-provenance.js

@@ -0,0 +1,46 @@
+/**
+ * Agentic QE v3 - Nested-Subagent Provenance Validation (ADR-101)
+ *
+ * Parses and validates the `--parent-agent-id` / `--depth` flags on
+ * `aqe hooks post-task`. Anthropic announced nested subagent support
+ * (depth=5) on 2026-06-09; recording which agent spawned a task and at
+ * what depth lets ReasoningBank segment patterns per hierarchy level —
+ * useful today for flat depth-1 spawns, and ready for deep chains the
+ * day the upstream `Task` denylist lifts.
+ */
+/** Agent identifiers: alphanum start, then alphanum / _ . : - , max 128 chars */
+const AGENT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
+/** Defensive bound — well above Anthropic's announced depth=5 cap */
+export const MAX_NESTING_DEPTH = 32;
+/**
+ * Validate raw flag values. Both flags are optional and independent;
+ * depth=0 is a valid value (top-level) and must survive as 0, not be
+ * coerced to undefined.
+ */
+export function parseNestingProvenance(parentAgentIdRaw, depthRaw) {
+    const result = {};
+    if (parentAgentIdRaw !== undefined) {
+        if (!AGENT_ID_RE.test(parentAgentIdRaw)) {
+            return {
+                error: `Invalid --parent-agent-id "${parentAgentIdRaw}": must start with a letter or digit ` +
+                    `and contain only letters, digits, "_", ".", ":", "-" (max 128 chars)`,
+            };
+        }
+        result.parentAgentId = parentAgentIdRaw;
+    }
+    if (depthRaw !== undefined) {
+        const depth = typeof depthRaw === 'number' ? depthRaw : Number(depthRaw);
+        if (!Number.isInteger(depth)) {
+            return { error: `Invalid --depth "${depthRaw}": must be an integer` };
+        }
+        if (depth < 0) {
+            return { error: `Invalid --depth ${depth}: must be >= 0` };
+        }
+        if (depth > MAX_NESTING_DEPTH) {
+            return { error: `Invalid --depth ${depth}: must be <= ${MAX_NESTING_DEPTH}` };
+        }
+        result.depth = depth;
+    }
+    return result;
+}
+//# sourceMappingURL=nesting-provenance.js.map

package/dist/cli/commands/hooks-handlers/task-hooks.js

@@ -14,6 +14,7 @@ import { applyHookBusyTimeout, getHooksSystem, createHybridBackendWithTimeout, i
 import { ensureRoutingOutcomesAdr095Columns } from '../../../routing/routing-outcomes-migration.js';
 import { deriveTaskType } from '../../../learning/agent-routing.js';
 import { detectQEDomains } from '../../../learning/qe-patterns.js';
+import { parseNestingProvenance } from './nesting-provenance.js';
 // ============================================================================
 // Constants — task-bridge / routing-quality / q-learning
 // ============================================================================
@@ -311,10 +312,24 @@ export function registerTaskHooks(hooks) {
         .option('--agent <name>', 'Agent that executed the task')
         .option('--duration <ms>', 'Task duration in milliseconds')
         .option('-d, --description <desc>', 'Task description — fallback Q-state source when pre-task bridge is absent (issue #499)')
+        .option('--parent-agent-id <id>', 'Agent that spawned this task (ADR-101 nesting provenance)')
+        .option('--depth <n>', 'Nesting depth of this task, 0 = top-level (ADR-101)')
         .option('--json', 'Output as JSON')
         .action(async (options) => {
         try {
             const success = options.success === 'true' || options.success === true;
+            // ADR-101: validate nesting provenance before any persistence
+            const provenance = parseNestingProvenance(options.parentAgentId, options.depth);
+            if (provenance.error) {
+                if (options.json) {
+                    console.log(JSON.stringify({ success: false, error: provenance.error }));
+                }
+                else {
+                    console.error(chalk.red(`  ✗ ${provenance.error}`));
+                }
+                process.exitCode = 1;
+                return;
+            }
             // Initialize hooks system and record learning outcome
             // BUG FIX: Must call getHooksSystem() FIRST to initialize, not check state.initialized
             let patternsLearned = 0;
@@ -344,11 +359,15 @@ export function registerTaskHooks(hooks) {
                     const effectiveTaskId = options.taskId || `hook-${Date.now()}`;
                     const agent = options.agent || 'unknown';
                     const durationMs = options.duration ? parseInt(options.duration, 10) : 0;
+                    // ADR-101: provenance rides in the feedback string so the
+                    // learning loop can segment patterns per hierarchy level
+                    const provenanceSuffix = (provenance.parentAgentId ? `, Parent: ${provenance.parentAgentId}` : '') +
+                        (provenance.depth !== undefined ? `, Depth: ${provenance.depth}` : '');
                     await reasoningBank.recordOutcome({
                         patternId: `task:${agent}:${effectiveTaskId}`,
                         success,
                         metrics: { executionTimeMs: durationMs },
-                        feedback: `Agent: ${agent}, Task: ${effectiveTaskId}`,
+                        feedback: `Agent: ${agent}, Task: ${effectiveTaskId}${provenanceSuffix}`,
                     });
                     // Stream B: full experience pipeline (captured_experiences,
                     // experience_applications + per-pattern fan-out, qe_trajectories
@@ -359,6 +378,8 @@ export function registerTaskHooks(hooks) {
                         agent,
                         durationMs,
                         success,
+                        parentAgentId: provenance.parentAgentId,
+                        depth: provenance.depth,
                     });
                     // Issue #460: when --agent arrives empty (Claude Code does not
                     // expose $TOOL_RESULT_agent_id in PostToolUse context), `agent`

package/dist/cli/commands/hooks-handlers/tool-loop-guardrail.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Agentic QE v3 - Tool-Loop Circuit Breaker (ADR-100)
+ *
+ * Detects consecutive failures of the same Bash command across hook
+ * invocations and breaks runaway retry loops: WARN at 3, BLOCK at 5.
+ * Advisory by default (the block is a strongly-worded recommendation in
+ * the hook output); `AQE_STRICT_TOOL_LOOP=1` upgrades the block to a
+ * PreToolUse deny.
+ *
+ * Mirrors the closed → open → half-open semantics of
+ * `src/coordination/circuit-breaker/domain-circuit-breaker.ts` (ADR-064),
+ * but persists state in a small JSON sidecar instead of process memory:
+ * every hook call is a fresh CLI process, so in-process state cannot see
+ * the previous invocation, and opening memory.db from pre-command would
+ * add DB-init latency to every Bash command. The sidecar is ephemeral
+ * guardrail state — safe to delete at any time, not a data store.
+ */
+export type ToolLoopVerdict = 'allow' | 'warn' | 'block';
+export interface ToolLoopCheck {
+    verdict: ToolLoopVerdict;
+    consecutiveFailures: number;
+    /** True when an open breaker is being given a probe attempt (half-open) */
+    halfOpen: boolean;
+    /** Human-readable guidance for warn/block verdicts */
+    hint?: string;
+}
+export interface ToolLoopGuardrailOptions {
+    /** Path of the JSON state sidecar */
+    statePath: string;
+    /** Consecutive failures before warning (default 3) */
+    warnThreshold?: number;
+    /** Consecutive failures before blocking (default 5) */
+    blockThreshold?: number;
+    /** An open breaker allows one probe attempt after this long (default 2 min) */
+    halfOpenAfterMs?: number;
+    /** Entries idle longer than this are pruned (default 30 min) */
+    staleAfterMs?: number;
+}
+export declare class ToolLoopGuardrail {
+    private readonly statePath;
+    private readonly warnThreshold;
+    private readonly blockThreshold;
+    private readonly halfOpenAfterMs;
+    private readonly staleAfterMs;
+    constructor(options: ToolLoopGuardrailOptions);
+    /**
+     * Normalize a command into a breaker key: whitespace-collapsed and
+     * length-capped so cosmetic differences don't split the failure count.
+     */
+    static signature(command: string): string;
+    /**
+     * Consult the breaker before a command runs (pre-command hook).
+     * Fail-open: any state-read problem yields 'allow'.
+     */
+    check(command: string, now?: number): ToolLoopCheck;
+    /**
+     * Record a command outcome (post-command hook). Success resets the
+     * breaker for that command; failure increments it. Fail-open on errors.
+     */
+    record(command: string, success: boolean, now?: number): void;
+    /** Whether strict mode upgrades the advisory block to a hook deny. */
+    static isStrict(env?: NodeJS.ProcessEnv): boolean;
+    private readState;
+    private writeState;
+}
+/**
+ * Guardrail bound to the project's `.agentic-qe/` directory — the shared
+ * instance used by the pre-command/post-command hooks.
+ */
+export declare function createProjectToolLoopGuardrail(projectRoot: string): ToolLoopGuardrail;
+//# sourceMappingURL=tool-loop-guardrail.d.ts.map

package/dist/cli/commands/hooks-handlers/tool-loop-guardrail.js

@@ -0,0 +1,142 @@
+/**
+ * Agentic QE v3 - Tool-Loop Circuit Breaker (ADR-100)
+ *
+ * Detects consecutive failures of the same Bash command across hook
+ * invocations and breaks runaway retry loops: WARN at 3, BLOCK at 5.
+ * Advisory by default (the block is a strongly-worded recommendation in
+ * the hook output); `AQE_STRICT_TOOL_LOOP=1` upgrades the block to a
+ * PreToolUse deny.
+ *
+ * Mirrors the closed → open → half-open semantics of
+ * `src/coordination/circuit-breaker/domain-circuit-breaker.ts` (ADR-064),
+ * but persists state in a small JSON sidecar instead of process memory:
+ * every hook call is a fresh CLI process, so in-process state cannot see
+ * the previous invocation, and opening memory.db from pre-command would
+ * add DB-init latency to every Bash command. The sidecar is ephemeral
+ * guardrail state — safe to delete at any time, not a data store.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+export class ToolLoopGuardrail {
+    statePath;
+    warnThreshold;
+    blockThreshold;
+    halfOpenAfterMs;
+    staleAfterMs;
+    constructor(options) {
+        this.statePath = options.statePath;
+        this.warnThreshold = options.warnThreshold ?? 3;
+        this.blockThreshold = options.blockThreshold ?? 5;
+        this.halfOpenAfterMs = options.halfOpenAfterMs ?? 120_000;
+        this.staleAfterMs = options.staleAfterMs ?? 30 * 60_000;
+    }
+    /**
+     * Normalize a command into a breaker key: whitespace-collapsed and
+     * length-capped so cosmetic differences don't split the failure count.
+     */
+    static signature(command) {
+        return command.trim().replace(/\s+/g, ' ').slice(0, 200);
+    }
+    /**
+     * Consult the breaker before a command runs (pre-command hook).
+     * Fail-open: any state-read problem yields 'allow'.
+     */
+    check(command, now = Date.now()) {
+        const sig = ToolLoopGuardrail.signature(command);
+        if (!sig) {
+            return { verdict: 'allow', consecutiveFailures: 0, halfOpen: false };
+        }
+        const entry = this.readState()[sig];
+        if (!entry || entry.consecutiveFailures < this.warnThreshold) {
+            return { verdict: 'allow', consecutiveFailures: entry?.consecutiveFailures ?? 0, halfOpen: false };
+        }
+        const failures = entry.consecutiveFailures;
+        if (failures >= this.blockThreshold) {
+            // Open breaker: allow a single probe once the half-open window elapses
+            if (now - entry.lastFailureAt >= this.halfOpenAfterMs) {
+                return {
+                    verdict: 'warn',
+                    consecutiveFailures: failures,
+                    halfOpen: true,
+                    hint: `This command has failed ${failures}x consecutively; allowing one probe attempt. ` +
+                        `If it fails again it will be flagged immediately.`,
+                };
+            }
+            return {
+                verdict: 'block',
+                consecutiveFailures: failures,
+                halfOpen: false,
+                hint: `The same command failed ${failures}x consecutively. Re-running it unchanged is ` +
+                    `unlikely to succeed — inspect the error output, change the approach, or fix the ` +
+                    `underlying problem first. (A successful run resets this breaker.)`,
+            };
+        }
+        return {
+            verdict: 'warn',
+            consecutiveFailures: failures,
+            halfOpen: false,
+            hint: `This command has failed ${failures}x consecutively — consider changing approach before retrying.`,
+        };
+    }
+    /**
+     * Record a command outcome (post-command hook). Success resets the
+     * breaker for that command; failure increments it. Fail-open on errors.
+     */
+    record(command, success, now = Date.now()) {
+        const sig = ToolLoopGuardrail.signature(command);
+        if (!sig)
+            return;
+        try {
+            const state = this.readState();
+            if (success) {
+                if (state[sig]) {
+                    delete state[sig];
+                    this.writeState(state, now);
+                }
+                return;
+            }
+            const entry = state[sig] ?? { consecutiveFailures: 0, lastFailureAt: now };
+            entry.consecutiveFailures += 1;
+            entry.lastFailureAt = now;
+            state[sig] = entry;
+            this.writeState(state, now);
+        }
+        catch {
+            /* fail-open: guardrail must never break the hook */
+        }
+    }
+    /** Whether strict mode upgrades the advisory block to a hook deny. */
+    static isStrict(env = process.env) {
+        return env.AQE_STRICT_TOOL_LOOP === '1' || env.AQE_STRICT_TOOL_LOOP === 'true';
+    }
+    readState() {
+        try {
+            const raw = fs.readFileSync(this.statePath, 'utf8');
+            const parsed = JSON.parse(raw);
+            return typeof parsed === 'object' && parsed !== null ? parsed : {};
+        }
+        catch {
+            return {}; // missing or corrupt sidecar → clean slate
+        }
+    }
+    writeState(state, now) {
+        // Prune stale entries so the sidecar stays small
+        for (const [key, entry] of Object.entries(state)) {
+            if (now - entry.lastFailureAt > this.staleAfterMs) {
+                delete state[key];
+            }
+        }
+        fs.mkdirSync(path.dirname(this.statePath), { recursive: true });
+        fs.writeFileSync(this.statePath, JSON.stringify(state));
+    }
+}
+/**
+ * Guardrail bound to the project's `.agentic-qe/` directory — the shared
+ * instance used by the pre-command/post-command hooks.
+ */
+export function createProjectToolLoopGuardrail(projectRoot) {
+    return new ToolLoopGuardrail({
+        statePath: path.join(projectRoot, '.agentic-qe', 'tool-loop-state.json'),
+    });
+}
+//# sourceMappingURL=tool-loop-guardrail.js.map

package/dist/cli/index.js

@@ -120,6 +120,18 @@ async function autoInitialize() {
     context.persistentScheduler = createPersistentScheduler();
     context.queen = createQueenCoordinator(context.kernel, context.router, protocolExecutor, undefined);
     await context.queen.initialize();
+    // Bridge the CLI-initialized components into the MCP handlers' fleet state.
+    // The memory/agent/task/team/pipeline handlers are shared between the MCP
+    // server and the CLI and are guarded by isFleetInitialized(); without this
+    // bridge every CLI invocation failed with "Fleet not initialized" even
+    // after a successful auto-init (MCP-CLI parity).
+    const { adoptExternalFleet } = await import('../mcp/handlers/core-handlers.js');
+    adoptExternalFleet({
+        kernel: context.kernel,
+        queen: context.queen,
+        router: context.router,
+        workflowOrchestrator: context.workflowOrchestrator,
+    });
     context.initialized = true;
 }
 async function ensureInitializedStrict() {
@@ -241,6 +253,11 @@ registerLazyCommand(program, {
     description: 'Security scanning and URL validation',
     factory: () => import('./commands/security.js').then(m => m.createSecurityCommand(context, cleanupAndExit, ensureInitialized)),
 });
+registerLazyCommand(program, {
+    name: 'arena',
+    description: 'Competitive test-strategy tournaments (ADR-104)',
+    factory: () => import('./commands/arena.js').then(m => m.createArenaCommand(context, cleanupAndExit, ensureInitialized)),
+});
 registerLazyCommand(program, {
     name: 'code',
     description: 'Code intelligence analysis',