aiden-runtime 4.5.0 → 4.6.0

package/dist/cli/v4/commands/spawnPause.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/commands/spawnPause.ts — v4.6 Phase 3A.
+ *
+ * `/spawn-pause on|off|status [reason...]` — operator kill-switch
+ * for sub-agent spawning. Backed by a file marker at
+ * `$aidenHome/spawn.paused` (see `core/v4/subagent/spawnPause.ts`)
+ * so REPL + daemon + MCP server all coordinate via the same state.
+ *
+ *   /spawn-pause on                  — pause, no reason
+ *   /spawn-pause on runaway-fanout   — pause, reason="runaway-fanout"
+ *   /spawn-pause on deploy window    — pause, reason="deploy window"
+ *   /spawn-pause off                 — resume
+ *   /spawn-pause status              — current state + reason + duration
+ *
+ * Unlike `/planner-guard`, `/sandbox`, etc., this command does NOT
+ * route through `runtimeToggles` — pause state is file-marker-
+ * backed (cross-process visibility) with first-class
+ * reason/pausedAt/pausedBy metadata that the boolean toggle surface
+ * can't carry. Mirrors plannerGuard.ts's command shape; diverges
+ * from `_runtimeToggleHelpers` because the storage backend is
+ * different.
+ *
+ * Hard contract: in-flight children are NEVER cancelled by this
+ * command. Pause affects only NEW spawns. Operators who want to
+ * stop in-flight runs use `aiden runs interrupt <runId>` (the
+ * existing per-run cancellation surface from v4.5 Phase 6).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnPause = void 0;
+const spawnPause_1 = require("../../../core/v4/subagent/spawnPause");
+/** Format a duration in ms as a compact `Xs` / `Xm` / `Xh` string. */
+function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    if (ms < 60000)
+        return `${Math.round(ms / 1000)}s`;
+    if (ms < 3600000)
+        return `${Math.round(ms / 60000)}m`;
+    return `${Math.round(ms / 3600000)}h`;
+}
+exports.spawnPause = {
+    name: 'spawn-pause',
+    description: 'Pause/resume sub-agent spawning (in-flight children continue).',
+    category: 'system',
+    icon: '⏸',
+    handler: async (ctx) => {
+        const action = (ctx.args[0] ?? 'status').toLowerCase();
+        const reasonArg = ctx.args.slice(1).join(' ').trim() || null;
+        let state;
+        try {
+            state = (0, spawnPause_1.getSpawnPause)();
+        }
+        catch (e) {
+            ctx.display.printError('spawn-pause: not initialized — REPL boot did not wire the singleton.', e instanceof Error ? e.message : String(e));
+            return {};
+        }
+        if (action === 'on' || action === 'enable' || action === 'true' || action === '1') {
+            state.pause({ reason: reasonArg, pausedBy: 'repl' });
+            const s = state.status();
+            const reasonLine = s.reason ? `   reason: ${s.reason}\n` : '';
+            ctx.display.write(`spawn-pause: ON\n${reasonLine}`);
+            ctx.display.dim('  in-flight children continue. New spawn_sub_agent / subagent_fanout calls will reject.');
+            return {};
+        }
+        if (action === 'off' || action === 'disable' || action === 'false' || action === '0' || action === 'resume') {
+            state.resume();
+            ctx.display.write('spawn-pause: OFF (resumed)\n');
+            return {};
+        }
+        if (action === 'status' || action === '') {
+            const s = state.status();
+            if (!s.paused) {
+                ctx.display.write('spawn-pause: OFF\n');
+                return {};
+            }
+            const reasonLine = s.reason ? `   reason:    ${s.reason}\n` : '';
+            const durationLine = s.durationMs !== undefined ? `   duration:  ${formatDuration(s.durationMs)}\n` : '';
+            const pausedAtLine = s.pausedAt ? `   pausedAt:  ${new Date(s.pausedAt).toISOString()}\n` : '';
+            const pausedByLine = s.pausedBy ? `   pausedBy:  ${s.pausedBy}\n` : '';
+            ctx.display.write(`spawn-pause: ON\n${reasonLine}${durationLine}${pausedAtLine}${pausedByLine}`);
+            return {};
+        }
+        ctx.display.printError('Usage: /spawn-pause on [reason...] | off | status');
+        return {};
+    },
+};

package/dist/cli/v4/daemonAgentBuilder.js

@@ -87,7 +87,10 @@ function buildDaemonAgentBuilder(deps) {
         };
         const agent = new aidenAgent_1.AidenAgent({
             provider: adapter,
-            tools: deps.toolRegistry.getSchemas(),
+            // v4.6 Phase 1 — 'daemon' context filter excludes REPL-only
+            // tools (`spawn_sub_agent` per Q6). Tools without an explicit
+            // `contexts` field stay visible to both REPL and daemon.
+            tools: deps.toolRegistry.getSchemas(undefined, 'daemon'),
             toolExecutor: deps.toolExecutor,
             maxTurns,
             auxiliaryClient: deps.auxiliaryClient,

package/dist/cli/v4/defaultSoul.js

@@ -30,7 +30,7 @@ exports.PREVIOUS_BUNDLED_SOULS = exports.DEFAULT_SOUL_MD = exports.BUNDLED_SOUL_
 // <act_dont_ask>. ensureSoulMdSeeded compares this against the user's
 // on-disk SOUL.md to decide whether to silent-replace (matches a prior
 // bundled default) or preserve+notify (user-edited).
-exports.BUNDLED_SOUL_VERSION = 'v4.5.0';
+exports.BUNDLED_SOUL_VERSION = 'v4.6.0';
 exports.DEFAULT_SOUL_MD = `You are Aiden — a local-first AI agent built by Shiva Deore at Taracod.
 
 Identity:

package/dist/core/v4/aidenAgent.js

@@ -40,6 +40,39 @@
  * `urlProvenance.ts`, `intentPreArm.ts`. Those modules predate this rewrite
  * and stay as-is.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AidenAgent = void 0;
 // v4.1.6 spike — Task Completion Engine (TCE) per-turn loop detector
@@ -60,6 +93,12 @@ const failureClassifier_1 = require("./failureClassifier");
 // guidance. Implicitly gated by TCE being enabled (surface only
 // reachable when TurnState is enabled — default ON as of Phase 6).
 const recoveryReport_1 = require("./recoveryReport");
+// v4.6 Phase 3b — self-improvement loop. Durable cross-session
+// failure ledger + recovery report writes. Loaded lazily inside the
+// per-call branch so a missing singleton (test agents without a
+// daemon DB) never blocks the agent loop.
+const signatureBuilder_1 = require("./selfimprovement/signatureBuilder");
+const recoveryStore_1 = require("./selfimprovement/recoveryStore");
 // v4.2 Phase 4 — checkpoint / restore. Lets the recovery controller
 // roll conversation messages + TurnState internals back to before a
 // looping tool started failing, so the model retries from a clean
@@ -84,6 +123,14 @@ class AidenAgent {
     constructor(opts) {
         this.skillMinerTurnIdx = 0;
         // ── Cross-call state ─────────────────────────────────────────────────
+        /**
+         * v4.6 Phase 1 — current per-turn AbortSignal, exposed to tools that need
+         * to construct child signal chains (specifically `spawn_sub_agent`). Set
+         * at the top of `runTurnLoop` from `runOptions.signal`, cleared before
+         * the loop returns. Read via `getCurrentSignal()`. Per-agent-instance —
+         * not shared across agents; a child agent has its own `_currentSignal`.
+         */
+        this._currentSignal = undefined;
         /** Cached system prompt — invalidated by setPersonalityOverlay/markMemoryDirty/explicit. */
         this.cachedSystemPrompt = null;
         this.compressionEvents = 0;
@@ -263,6 +310,17 @@ class AidenAgent {
     getEmptyResponseMetrics() {
         return { ...this.emptyResponseMetrics };
     }
+    /**
+     * v4.6 Phase 1 — return the AbortSignal currently associated with this
+     * agent's active `runTurnLoop`, or `undefined` if the agent is between
+     * turns. Used by the `spawn_sub_agent` tool to construct a child signal
+     * chain that cascades parent aborts to the child (Flag 1 pattern: tool
+     * captures the parent agent reference at construction time and reads
+     * the current signal from the instance at dispatch time).
+     */
+    getCurrentSignal() {
+        return this._currentSignal;
+    }
     // ── Main entry: runConversation ──────────────────────────────────────
     async runConversation(history, options = {}) {
         // 1. Refresh memory snapshot if the dirty bit was set since last turn.
@@ -512,6 +570,23 @@ class AidenAgent {
     async narrowTools(userMsg, history) {
         if (!this.plannerGuard)
             return this.tools;
+        // v4.6 Phase 2M — runtime toggle gates the keyword-based narrower.
+        // Default OFF: smart models (GPT-5.5, Claude Sonnet 4.5+, Opus)
+        // pick tools fine from the full catalog every turn, matching the
+        // reference multi-agent system's pattern. Opt in via env
+        // (AIDEN_PLANNER_GUARD=1) or `/planner-guard on` for small local
+        // models that need help. The toggle is read on each call so a
+        // mid-conversation flip takes effect on the next turn without
+        // restarting the agent.
+        //
+        // Lazy `require` to avoid a hard import dependency in the agent
+        // core — pure unit tests of AidenAgent that don't initialise the
+        // runtime toggles singleton keep working (the lazy getter returns
+        // an env-only fallback resolver per runtimeToggles.ts:213).
+        const { getRuntimeToggles } = await Promise.resolve().then(() => __importStar(require('./runtimeToggles')));
+        if (!getRuntimeToggles().isEnabled('planner_guard')) {
+            return this.tools;
+        }
         const decision = await this.plannerGuard.decide(userMsg, history);
         this.onPlannerGuardDecision?.(decision);
         const allowed = new Set(decision.selectedTools);
@@ -528,8 +603,24 @@ class AidenAgent {
      * `runConversation` enriches with post-loop scan output.
      */
     async runTurnLoop(initialMessages, tools, trackers, runOptions) {
+        // v4.6 Phase 1 — expose the per-turn signal to tools via
+        // `getCurrentSignal()`. Set at loop entry; cleared before the return
+        // below. Tools that need the parent's signal (e.g. `spawn_sub_agent`
+        // building a child cancellation chain) capture the agent reference at
+        // construction time and read this field at dispatch time. If the loop
+        // throws, the stale value persists until the next call's set —
+        // acceptable because the only consumer is in-flight tool dispatch,
+        // which can only run while the loop is mid-execution.
+        this._currentSignal = runOptions.signal;
         const messages = [...initialMessages];
         const toolCallTrace = [];
+        // v4.6 Phase 3b — per-turn signature tracker for failure → success
+        // transitions. Each entry records the signatureId + failure count
+        // observed so far for a given signature THIS turn. When a verifier
+        // later reports `ok` for a tool call whose signature has prior
+        // failures, we record a recovery report. Keyed by signature string
+        // (the canonical `tool:category[:hash]` form).
+        const turnFailureTracker = new Map();
         // Internal trace mirror that retains tool-call arguments — Honesty's
         // shape doesn't include args, but SkillTeacher needs them. Both live
         // off the same entry index.
@@ -564,6 +655,16 @@ class AidenAgent {
         const failureClassifier = (0, failureClassifier_1.buildDefaultClassifier)();
         let toolLoopCard = undefined;
         while (true) {
+            // v4.6 prep — between-iteration cooperative-cancellation check.
+            // When the caller passed an AbortSignal that has aborted, exit
+            // immediately with `finishReason: 'interrupted'`. Delta accumulation
+            // on abort is deferred — finalContent stays '' in this prep dispatch
+            // (see docs/v4.6/phase-1-design.md §11.0).
+            if (runOptions.signal?.aborted) {
+                finishReason = 'interrupted';
+                finalContent = '';
+                break;
+            }
             // v4.1.6 spike — decrement cooldown counters once per iteration
             // so cooled-down tools eventually return to the schemas. No-op
             // when TCE is disabled.
@@ -604,6 +705,17 @@ class AidenAgent {
             }
             catch (err) {
                 const error = err instanceof Error ? err : new Error(String(err));
+                // v4.6 prep — external abort takes priority over fallback. An
+                // AbortError surfaced from the adapter when input.signal aborted
+                // is NOT a transient transport failure; surface it immediately
+                // as `finishReason: 'interrupted'` so the calling spawn primitive
+                // can route correctly. Detect via either the live signal flag or
+                // the error name (covers both pre-fetch and mid-flight aborts).
+                if (runOptions.signal?.aborted || error.name === 'AbortError') {
+                    finishReason = 'interrupted';
+                    finalContent = '';
+                    break;
+                }
                 if (this.fallback && !fallbackActivated) {
                     const next = await this.fallback.activate(error, turnCount);
                     if (next) {
@@ -721,6 +833,16 @@ class AidenAgent {
             // then continues the outer iteration loop from a clean baseline.
             let rollbackDecision = null;
             for (const call of output.toolCalls) {
+                // v4.6 prep — pre-tool-call cooperative-cancellation check.
+                // If the caller aborted between the model emitting tool calls
+                // and us dispatching them, skip the remaining calls in this
+                // batch. We set finishReason here; the outer-while break is
+                // handled after the for-of exits.
+                if (runOptions.signal?.aborted) {
+                    finishReason = 'interrupted';
+                    finalContent = '';
+                    break;
+                }
                 this.onToolCall?.(call, 'before');
                 // v4.2 Phase 4 — mark any active checkpoints as containing a
                 // mutating call BEFORE dispatch. Done pre-dispatch (not post)
@@ -773,6 +895,74 @@ class AidenAgent {
                             // Defensive — a buggy classifier never breaks the loop.
                             classification = null;
                         }
+                        // v4.6 Phase 3b — write-through to the durable failure
+                        // ledger. Best-effort: a null/missing store (test agents
+                        // without a daemon DB wired) silently no-ops. The
+                        // signature builder is pure + cheap.
+                        if (classification) {
+                            try {
+                                const store = (0, recoveryStore_1.getRecoveryStore)();
+                                if (store) {
+                                    const sig = (0, signatureBuilder_1.buildFailureSignature)({
+                                        toolName: call.name,
+                                        category: classification.category,
+                                        args: call.arguments,
+                                    });
+                                    const signatureId = store.recordFailureOccurrence({
+                                        signature: sig.signature,
+                                        toolName: call.name,
+                                        category: classification.category,
+                                        argsHash: sig.argsHash,
+                                    });
+                                    if (signatureId > 0) {
+                                        const existing = turnFailureTracker.get(sig.signature);
+                                        turnFailureTracker.set(sig.signature, {
+                                            signatureId,
+                                            failedAttempts: (existing?.failedAttempts ?? 0) + 1,
+                                        });
+                                    }
+                                }
+                            }
+                            catch {
+                                // Defensive — persistence failure must never break the loop.
+                            }
+                        }
+                    }
+                    else if (verification && verification.ok) {
+                        // v4.6 Phase 3b — failure → success transition detection.
+                        // We don't know the failure CATEGORY for this successful
+                        // call (the verifier said ok, so classify() wasn't run),
+                        // but the per-turn tracker remembers every signature seen
+                        // failing this turn. Walk the tracker; if any entry's
+                        // signature starts with `<call.name>:`, this tool now
+                        // succeeded — record a recovery and drop the entry so
+                        // subsequent successes don't double-count.
+                        try {
+                            const store = (0, recoveryStore_1.getRecoveryStore)();
+                            if (store) {
+                                const matching = [];
+                                for (const sig of turnFailureTracker.keys()) {
+                                    if (sig.startsWith(`${call.name}:`))
+                                        matching.push(sig);
+                                }
+                                for (const sig of matching) {
+                                    const entry = turnFailureTracker.get(sig);
+                                    if (!entry)
+                                        continue;
+                                    store.recordRecovery({
+                                        signatureId: entry.signatureId,
+                                        sessionId: this.sessionId,
+                                        failedAttempts: entry.failedAttempts,
+                                        successfulStrategy: 'in_turn_retry',
+                                        notes: `${call.name} succeeded after ${entry.failedAttempts} prior failure(s) this turn`,
+                                    });
+                                    turnFailureTracker.delete(sig);
+                                }
+                            }
+                        }
+                        catch {
+                            // Defensive — recovery persistence failure must never break the loop.
+                        }
                     }
                 }
                 toolCallTrace.push({
@@ -852,6 +1042,14 @@ class AidenAgent {
                     break;
                 }
             }
+            // v4.6 prep — if the per-tool-call abort check fired inside the
+            // for-of above, finishReason is now 'interrupted'. Break the outer
+            // while immediately so we don't run another provider call. Done
+            // here (post-for-of) rather than inside the for-of because the
+            // inner `break` only exits the inner loop.
+            if (finishReason === 'interrupted') {
+                break;
+            }
             // v4.2 Phase 4 — apply rollback if the controller asked for it.
             // Truncate messages to the captured snapshot length, restore
             // TurnState internals, then push a corrective system message
@@ -938,6 +1136,11 @@ class AidenAgent {
             messages.push(...turnToolMessages);
             // Loop continues — provider gets the tool results next iteration.
         }
+        // v4.6 Phase 1 — clear the per-turn signal exposure before returning.
+        // No-throw guarantee: if any prior code in this loop threw, the next
+        // call's `this._currentSignal = runOptions.signal` at the top will
+        // overwrite the stale value before any tool can read it.
+        this._currentSignal = undefined;
         return {
             finalContent,
             messages,
@@ -973,7 +1176,9 @@ class AidenAgent {
         }
         catch { /* defensive */ }
         if (!wantStream) {
-            return this.provider.call({ messages, tools });
+            // v4.6 prep — forward the abort signal into the provider call so
+            // an in-flight HTTP request can be cancelled mid-flight.
+            return this.provider.call({ messages, tools, signal: runOptions.signal });
         }
         let firstDeltaFired = false;
         let finalOutput = null;
@@ -981,6 +1186,9 @@ class AidenAgent {
             messages,
             tools,
             stream: true,
+            // v4.6 prep — also forward to streaming adapters; mid-stream
+            // aborts cancel the underlying SSE read via the same signal.
+            signal: runOptions.signal,
         });
         for await (const evt of stream) {
             if (evt.type === 'delta') {
@@ -1007,6 +1215,16 @@ class AidenAgent {
             }
         }
         if (!finalOutput) {
+            // v4.6 prep — if the stream consumer exited without a `done`
+            // event because the signal was aborted mid-stream, surface a
+            // synthetic AbortError so the outer catch routes it as
+            // 'interrupted' rather than the misleading "closed without done"
+            // generic error.
+            if (runOptions.signal?.aborted) {
+                const abortErr = new Error('Streaming provider aborted before done event');
+                abortErr.name = 'AbortError';
+                throw abortErr;
+            }
             throw new Error('Streaming provider closed without a done event');
         }
         return finalOutput;

package/dist/core/v4/daemon/bootstrap.js

@@ -125,9 +125,56 @@ function bootstrapDaemon(opts = {}) {
         const dbPath = (0, daemonConfig_2.daemonDbPath)(aidenRoot);
         const lockPath = (0, daemonConfig_2.daemonRuntimeLockPath)(aidenRoot);
         const markerPath = (0, daemonConfig_2.daemonCleanShutdownMarkerPath)(aidenRoot);
+        // v4.6 Phase 3A — wire the spawn-pause singleton against the
+        // same `aidenRoot` the REPL uses. Daemon-fired turns that
+        // invoke `subagent_fanout` will read the same marker file the
+        // REPL writes via /spawn-pause. Cross-process coordination is
+        // the whole point of the file-marker design (in-process
+        // singletons in three runtimes would each have independent
+        // pause flags, which would defeat the operator control).
+        // The init is idempotent — if the REPL already ran initSpawnPause
+        // in this same process, this call replaces the singleton with
+        // an equivalent one pointing at the same path.
+        //
+        // Defensive try/catch: a pause-init failure must NOT prevent
+        // daemon bootstrap. Worst case the singleton stays uninit and
+        // tool handlers fall through to their `safeReadPause` path
+        // (treat as "not paused"). The daemon's startup probe below
+        // is best-effort.
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { initSpawnPause } = require('../subagent/spawnPause');
+            const sp = initSpawnPause({ aidenHome: aidenRoot });
+            if (sp.isPaused()) {
+                const s = sp.status();
+                const reasonSuffix = s.reason ? ` (reason: ${s.reason})` : '';
+                log('warn', `[daemon] sub-agent spawning is PAUSED${reasonSuffix}. ` +
+                    'Daemon-fired subagent_fanout calls will reject until an operator ' +
+                    'runs /spawn-pause off in a REPL session.');
+            }
+        }
+        catch (e) {
+            log('warn', '[daemon] spawn-pause init failed (non-fatal): ' +
+                (e instanceof Error ? e.message : String(e)));
+        }
         const db = (0, connection_1.openDaemonDb)(dbPath);
         const tracker = (0, instanceTracker_1.createInstanceTracker)({ db, version: version_1.VERSION });
         tracker.start();
+        // v4.6 Phase 3b — self-improvement loop singleton. Daemon-fired
+        // turns that classify failures via TCE write through to the
+        // shared failure ledger, so operator queries from a REPL see
+        // daemon-side failure patterns too. Defensive try/catch — init
+        // failure must not block daemon bootstrap; the TCE write-through
+        // path silently no-ops when the singleton is missing.
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { initRecoveryStore } = require('../selfimprovement/recoveryStore');
+            initRecoveryStore({ db });
+        }
+        catch (e) {
+            log('warn', '[daemon] recovery-store init failed (non-fatal): ' +
+                (e instanceof Error ? e.message : String(e)));
+        }
         // Race-safe runtime lock. EEXIST + live PID → DaemonAlreadyRunningError.
         let runtimeLock;
         try {

package/dist/core/v4/daemon/db/migrations.js

@@ -252,12 +252,78 @@ CREATE INDEX IF NOT EXISTS idx_scheduled_workflows_next_fire
 CREATE INDEX IF NOT EXISTS idx_scheduled_workflows_enabled
   ON scheduled_workflows(enabled);
 `;
+// Embedded v6 schema. Source of truth lives at
+// `core/v4/daemon/db/schema/v6.sql` (matching v1-v4 convention).
+// Kept in sync via the `tests/v4/daemon/db/migrations-v6.test.ts`
+// snapshot check.
+const V6_SQL = `
+ALTER TABLE runs ADD COLUMN spawned_from_run_id     INTEGER;
+ALTER TABLE runs ADD COLUMN spawned_from_session_id TEXT;
+
+CREATE INDEX IF NOT EXISTS idx_runs_spawned_from
+  ON runs(spawned_from_run_id)
+  WHERE spawned_from_run_id IS NOT NULL;
+`;
+// Embedded v7 schema. Source of truth at
+// `core/v4/daemon/db/schema/v7.sql` (same convention). Kept in
+// sync via `tests/v4/daemon/db/migrations-v7.test.ts`.
+//
+// v4.6 Phase 3b: self-improvement loop foundation — adds two
+// tables for durable cross-session failure tracking:
+//   * `failure_signatures` — one row per (tool, category, args_hash);
+//     `occurrences` increments on every observed failure, so the
+//     operator can `SELECT … ORDER BY occurrences DESC` to find the
+//     most-stubborn failure shapes.
+//   * `recovery_reports` — one row per observed failure → success
+//     transition; carries the strategy that worked + verification +
+//     free-text notes for operator review.
+const V7_SQL = `
+CREATE TABLE IF NOT EXISTS failure_signatures (
+  id                       INTEGER PRIMARY KEY AUTOINCREMENT,
+  signature                TEXT    UNIQUE NOT NULL,
+  tool_name                TEXT    NOT NULL,
+  failure_category         TEXT    NOT NULL,
+  args_hash                TEXT,
+  first_seen_at            INTEGER NOT NULL,
+  last_seen_at             INTEGER NOT NULL,
+  occurrences              INTEGER NOT NULL DEFAULT 1,
+  recovered_count          INTEGER NOT NULL DEFAULT 0,
+  last_recovery_report_id  INTEGER
+);
+
+CREATE INDEX IF NOT EXISTS idx_failure_signatures_signature
+  ON failure_signatures(signature);
+
+CREATE INDEX IF NOT EXISTS idx_failure_signatures_tool
+  ON failure_signatures(tool_name);
+
+CREATE TABLE IF NOT EXISTS recovery_reports (
+  id                    INTEGER PRIMARY KEY AUTOINCREMENT,
+  signature_id          INTEGER NOT NULL REFERENCES failure_signatures(id),
+  run_id                INTEGER REFERENCES runs(id),
+  session_id            TEXT,
+  failed_attempts       INTEGER NOT NULL,
+  successful_strategy   TEXT    NOT NULL,
+  changed_parameters    TEXT,
+  verification          TEXT,
+  created_at            INTEGER NOT NULL,
+  notes                 TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_recovery_reports_signature
+  ON recovery_reports(signature_id);
+
+CREATE INDEX IF NOT EXISTS idx_recovery_reports_run
+  ON recovery_reports(run_id);
+`;
 const MIGRATIONS = [
     { version: 1, name: 'phase 1 — daemon foundation', sql: V1_SQL },
     { version: 2, name: 'phase 2 — file watcher observations', sql: V2_SQL },
     { version: 3, name: 'phase 3 — webhook deliveries log', sql: V3_SQL },
     { version: 4, name: 'phase 4a — email seen forensic table', sql: V4_SQL },
     { version: 5, name: 'phase 5b — scheduled workflows', sql: V5_SQL },
+    { version: 6, name: 'v4.6 phase 1 — sub-agent lineage', sql: V6_SQL },
+    { version: 7, name: 'v4.6 phase 3b — self-improvement loop', sql: V7_SQL },
 ];
 exports.LATEST_SCHEMA_VERSION = MIGRATIONS[MIGRATIONS.length - 1].version;
 function getCurrentVersion(db) {

package/dist/core/v4/daemon/runStore.js

@@ -35,12 +35,17 @@ function rowToTs(r) {
 function createRunStore(opts) {
     const db = opts.db;
     return {
-        create({ sessionId, instanceId, triggerEventId, status, startedAt }) {
+        create({ sessionId, instanceId, triggerEventId, status, startedAt, spawnedFromRunId, spawnedFromSessionId }) {
             const now = startedAt ?? Date.now();
+            // v4.6 Phase 1 — explicit 8-column INSERT including the two
+            // sub-agent lineage columns. Top-level runs pass NULL for both;
+            // sub-agent runs pass the parent run_id + session_id. Single
+            // insert path keeps the code simple at the cost of two extra
+            // bound NULLs on the common (top-level) case.
             const r = db.prepare(`INSERT INTO runs
            (trigger_event_id, session_id, instance_id, status, started_at,
-            resume_pending)
-         VALUES (?, ?, ?, ?, ?, 0)`).run(triggerEventId ?? null, sessionId, instanceId, status ?? 'queued', now);
+            resume_pending, spawned_from_run_id, spawned_from_session_id)
+         VALUES (?, ?, ?, ?, ?, 0, ?, ?)`).run(triggerEventId ?? null, sessionId, instanceId, status ?? 'queued', now, spawnedFromRunId ?? null, spawnedFromSessionId ?? null);
             return Number(r.lastInsertRowid);
         },
         setStatus(runId, status, opts2 = {}) {
@@ -95,6 +100,17 @@ function createRunStore(opts) {
                 whereParts.push('r.session_id LIKE ?');
                 params.push(`${opts2.sessionIdPrefix}%`);
             }
+            // v4.6 Phase 2Q-B — default to top-level rows only. Children
+            // (rows with non-NULL `spawned_from_run_id`) clutter the list
+            // when you really want "what user-triggered runs happened
+            // recently". The partial index `idx_runs_spawned_from` makes
+            // the negated predicate cheap (children indexed; parents NOT
+            // indexed but the predicate is `IS NULL` — table scan, but
+            // the planner uses the limit + ORDER BY started_at to cap
+            // work). `--include-children` flips the flag for flat view.
+            if (opts2.topLevelOnly !== false) {
+                whereParts.push('r.spawned_from_run_id IS NULL');
+            }
             const where = whereParts.length > 0 ? `WHERE ${whereParts.join(' AND ')}` : '';
             const sql = `
         SELECT r.* FROM runs r
@@ -106,6 +122,20 @@ function createRunStore(opts) {
             const rows = db.prepare(sql).all(...params);
             return rows.map(rowToTs);
         },
+        countChildren(parentRunId) {
+            // Single round-trip via conditional COUNT — sqlite handles
+            // this fine even with a few thousand children per parent,
+            // which we'll never see in practice (fanout caps at 5).
+            const r = db.prepare(`SELECT
+           COUNT(*) AS total,
+           SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) AS completed
+         FROM runs
+        WHERE spawned_from_run_id = ?`).get(parentRunId);
+            return {
+                total: r.total,
+                completed: r.completed ?? 0,
+            };
+        },
         listEvents(runId, limit = 200) {
             const rows = db.prepare(`SELECT ts, kind, payload FROM run_events WHERE run_id = ? ORDER BY ts ASC LIMIT ?`).all(runId, Math.max(1, Math.min(limit, 5000)));
             return rows;