aiden-runtime 4.0.2 → 4.1.1

package/dist/core/v4/skillMining/extractorPrompt.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/skillMining/extractorPrompt.ts — Phase v4.1-skill-mining
+ *
+ * Optional LLM refinement pass on top of `proposalBuilder.draft()`.
+ * The skeleton SKILL.md the builder produces is already a valid
+ * v4 skill; the refiner only polishes prose. Two hard rules:
+ *
+ *   1. Structural fields are sacred — name, description, version,
+ *      metadata.aiden.* must round-trip unchanged. We re-parse the
+ *      refined output and discard it if any required field drifts.
+ *
+ *   2. Never write attribution tokens or "portions adapted from..." /
+ *      "original copyright" strings. The permanent attribution
+ *      sweep validates this; if a refined output contains any
+ *      forbidden token, we fall back to the skeleton.
+ *
+ * If the auxiliary client is unavailable, the call times out, or
+ * the refined output fails validation, the function returns the
+ * skeleton unchanged. Mining works fully offline — refinement is
+ * best-effort polish.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refine = refine;
+const skillSpec_1 = require("../skillSpec");
+const BANNED_TOKENS = [
+    'portions adapted from',
+    'original copyright',
+    'derived from',
+    'based on the',
+    'adapted from',
+];
+const FORBIDDEN_TOKENS_RE = new RegExp(`\\b(${BANNED_TOKENS.join('|')})\\b`, 'i');
+const REFINER_SYSTEM_PROMPT = `
+You polish auto-generated skill markdown for a local-first AI agent.
+
+Your job is to improve the WORDING ONLY of an already-valid SKILL.md
+file. The frontmatter (everything between the leading "---" markers)
+must round-trip BYTE-FOR-BYTE unchanged. The "# <name>" heading must
+stay first in the body. The numbered "## Steps" list must remain
+numbered and in the same order; you may rephrase step descriptions
+but must NOT add or remove steps.
+
+Hard rules:
+- Output the COMPLETE SKILL.md, not a diff.
+- Do not add boilerplate, citations, or attribution to any other
+  agent or codebase. The skill is 100% the user's own.
+- Do not introduce mock/fake values into commands.
+- Keep total length under 6000 characters.
+`.trim();
+/**
+ * Refine `skeleton` via the auxiliary client. Always returns a
+ * valid SKILL.md string — either the refined output (if it passes
+ * round-trip + no-attribution validation) or the original skeleton.
+ */
+async function refine(skeleton, opts = {}) {
+    const client = opts.client;
+    if (!client || client.isUnavailable()) {
+        return skeleton;
+    }
+    // Parse the skeleton up front to lock the canonical frontmatter
+    // shape we'll require the refined output to match.
+    let skeletonParsed;
+    try {
+        skeletonParsed = (0, skillSpec_1.parseSkillContent)(skeleton);
+    }
+    catch {
+        // If the skeleton itself is invalid, refining can only make it
+        // worse; bubble the skeleton out and let the caller decide.
+        return skeleton;
+    }
+    const prompt = `${REFINER_SYSTEM_PROMPT}\n\n` +
+        `INPUT SKILL.md:\n\`\`\`\n${skeleton}\n\`\`\`\n\n` +
+        `Output the refined SKILL.md only — no commentary, no code fences.`;
+    let refined;
+    try {
+        const result = await client.call({
+            purpose: 'skill_describe',
+            prompt,
+            maxTokens: opts.maxTokens ?? 1500,
+            timeoutMs: opts.timeoutMs ?? 20000,
+        });
+        refined = (result.content ?? '').trim();
+    }
+    catch {
+        return skeleton;
+    }
+    if (refined.length === 0)
+        return skeleton;
+    // Strip a wrapping ```...``` if the model returned one.
+    refined = refined.replace(/^```(?:markdown|md)?\s*\n/, '').replace(/\n```\s*$/, '');
+    // Validation 1 — attribution sweep. Refined output must not
+    // contain any forbidden token. The permanent sweep would catch
+    // this at ship time; we catch it earlier so a single noisy
+    // refinement doesn't pollute the candidate queue.
+    if (FORBIDDEN_TOKENS_RE.test(refined))
+        return skeleton;
+    // Validation 2 — round-trip through parseSkillContent and verify
+    // the canonical fields match the skeleton.
+    let refinedParsed;
+    try {
+        refinedParsed = (0, skillSpec_1.parseSkillContent)(refined);
+    }
+    catch {
+        return skeleton;
+    }
+    if (refinedParsed.frontmatter.name !== skeletonParsed.frontmatter.name ||
+        refinedParsed.frontmatter.version !== skeletonParsed.frontmatter.version) {
+        return skeleton;
+    }
+    return refined;
+}

package/dist/core/v4/skillMining/proposalBuilder.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/skillMining/proposalBuilder.ts — Phase v4.1-skill-mining
+ *
+ * Pure-function skeleton SKILL.md generator from a successful tool-
+ * call trace. Used by skillMiner BEFORE optional LLM refinement —
+ * the skeleton must already be a valid v4 skill (parseSkillContent
+ * round-trips), so that mining works offline when the auxiliary
+ * client is unavailable.
+ *
+ * Invariants:
+ *   - emits required fields `name`, `description`, `version`
+ *   - emits `metadata.aiden` with the mining provenance fields
+ *   - body is numbered tool-call steps in markdown
+ *   - never writes attribution strings — the banned-token regex
+ *     strips them at extraction time and the permanent attribution
+ *     sweep validates the result
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveName = deriveName;
+exports.deriveDescription = deriveDescription;
+exports.draft = draft;
+const STOP_WORDS = new Set([
+    'the', 'a', 'an', 'to', 'for', 'of', 'on', 'at', 'in', 'by', 'and', 'or', 'but', 'with',
+    'from', 'please', 'can', 'you', 'will', 'do', 'does', 'my', 'our', 'this', 'that', 'these',
+    'is', 'are', 'be', 'was', 'were', 'it', 'its', 'as', 'if', 'then', 'else', 'some', 'any',
+    'me', 'i', 'your', 'their', 'his', 'her', 'him',
+]);
+/**
+ * Derive a kebab-case skill-name from the first user message.
+ * Conservative — keeps only [a-z0-9-], collapses runs, max 40 chars.
+ * Falls back to `learned-skill-<short-fingerprint>` if extraction
+ * yields nothing usable.
+ */
+function deriveName(firstUserPrompt, fingerprint) {
+    const lowered = firstUserPrompt.toLowerCase();
+    // Pull out non-stopword tokens, max 5 of them.
+    const tokens = lowered
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length >= 3 && !STOP_WORDS.has(t))
+        .slice(0, 5);
+    let stem = tokens.join('-');
+    // Strict alphanum-and-dash, collapse multiple dashes, trim leading/trailing.
+    stem = stem.replace(/[^a-z0-9-]/g, '').replace(/-+/g, '-').replace(/^-|-$/g, '');
+    if (stem.length === 0) {
+        return `learned-skill-${fingerprint.slice(0, 8)}`;
+    }
+    return stem.slice(0, 40);
+}
+/**
+ * Build the description line — single sentence summarising what the
+ * trace did. Keep it under 200 chars (the skill loader caps the
+ * displayed description in /skills list).
+ */
+function deriveDescription(trace) {
+    if (trace.length === 0)
+        return 'Learned workflow.';
+    const tools = trace.map((e) => e.name).filter(Boolean);
+    const distinct = Array.from(new Set(tools));
+    if (distinct.length === 1) {
+        return `Learned workflow: ${distinct[0]} (${tools.length}x).`;
+    }
+    const head = distinct.slice(0, 4).join(' → ');
+    const more = distinct.length > 4 ? ` (+${distinct.length - 4} more)` : '';
+    return `Learned workflow: ${head}${more}.`;
+}
+/**
+ * Render the body as numbered tool-call steps. Args are JSON-stringified
+ * and clipped at 120 chars per step so a chatty trace doesn't bloat
+ * SKILL.md to multi-MB.
+ */
+function renderBody(trace) {
+    if (trace.length === 0) {
+        return '## Steps\n\n_(empty trace)_\n';
+    }
+    const out = ['## Steps', ''];
+    trace.forEach((entry, i) => {
+        const idx = i + 1;
+        const argSummary = (() => {
+            if (entry.args == null || typeof entry.args !== 'object')
+                return '';
+            try {
+                const json = JSON.stringify(entry.args);
+                if (json.length <= 120)
+                    return `  \\\`${json}\\\``;
+                return `  \\\`${json.slice(0, 117)}…\\\``;
+            }
+            catch {
+                return '';
+            }
+        })();
+        out.push(`${idx}. **${entry.name}**${argSummary}`);
+    });
+    out.push('');
+    out.push('## Notes', '');
+    out.push('Mined from a successful turn — review the steps above before relying on it.');
+    out.push('');
+    return out.join('\n');
+}
+/**
+ * Build a full SKILL.md (frontmatter + body) ready for parseSkillContent.
+ * The output is deterministic for a given (trace, context) input —
+ * smokes assert this for stable round-trip behaviour.
+ */
+function draft(trace, ctx) {
+    const name = ctx.nameOverride?.trim() || deriveName(ctx.firstUserPrompt, ctx.traceFingerprint);
+    const description = deriveDescription(trace);
+    const version = '0.1.0';
+    const createdAt = new Date().toISOString();
+    // YAML frontmatter — keep field order stable so smokes can pin
+    // shape without depending on YAML library output ordering.
+    const frontmatter = [
+        '---',
+        `name: ${name}`,
+        `description: ${JSON.stringify(description)}`,
+        `version: ${version}`,
+        'category: learned',
+        'metadata:',
+        '  aiden:',
+        '    learned: true',
+        `    sourceSessionId: ${JSON.stringify(ctx.sourceSessionId)}`,
+        `    sourceTurnIdx: ${ctx.sourceTurnIdx}`,
+        `    createdAt: ${JSON.stringify(createdAt)}`,
+        `    traceFingerprint: ${JSON.stringify(ctx.traceFingerprint)}`,
+        `    candidateConfidence: ${ctx.candidateConfidence.toFixed(3)}`,
+        '---',
+        '',
+        `# ${name}`,
+        '',
+        description,
+        '',
+    ].join('\n');
+    return frontmatter + renderBody(trace);
+}

package/dist/core/v4/skillMining/skillMiner.js

@@ -0,0 +1,191 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/skillMining/skillMiner.ts — Phase v4.1-skill-mining
+ *
+ * Orchestrator for the skill-mining post-turn observation. Sits next
+ * to `moat/skillTeacher.ts:observeTurn` in the agent loop hook
+ * (`core/v4/aidenAgent.ts:440-468`); the two are complementary.
+ * SkillTeacher proposes inline (immediate accept/reject); SkillMiner
+ * stages a candidate for `/skills review` so the user can audit
+ * before any disk-mutation lands in the live skills directory.
+ *
+ * Programmatic gates (in order — first failure short-circuits):
+ *   1. trace length < 3                        → skip
+ *   2. any tool errored                        → skip
+ *   3. finishReason !== 'stop'                 → skip
+ *   4. session candidate count >= SESSION_SKILL_LIMIT → skip
+ *   5. user opt-out phrase in conversation     → skip (reuse OPT_OUT_RE)
+ *   6. fingerprint matches pending candidate   → skip (dedup)
+ *   7. fingerprint matches rejected list       → skip (dedup)
+ *
+ * Pass-through pipeline:
+ *   - compute confidence score from programmatic features
+ *   - draft skeleton via proposalBuilder
+ *   - refine via extractorPrompt (best-effort; falls back to
+ *     skeleton)
+ *   - validate via parseSkillContent round-trip
+ *   - append to candidateStore
+ *   - return ObservationResult so chatSession can notify
+ *
+ * MCP serve mode: caller (aidenAgent) MUST gate on
+ * !isMcpServeMode() before invoking observeTurn — the mining
+ * subsystem itself doesn't write to stdout but a candidate
+ * notification would, and serve mode owns stdout for JSON-RPC.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillMiner = exports.SESSION_SKILL_LIMIT = void 0;
+exports.computeConfidence = computeConfidence;
+const node_crypto_1 = require("node:crypto");
+const skillSpec_1 = require("../skillSpec");
+const candidateStore_1 = require("./candidateStore");
+const traceFingerprint_1 = require("./traceFingerprint");
+const proposalBuilder_1 = require("./proposalBuilder");
+const extractorPrompt_1 = require("./extractorPrompt");
+/** Per-session candidate cap — port from v3's `SESSION_SKILL_LIMIT`. */
+exports.SESSION_SKILL_LIMIT = 2;
+/** Minimum trace length to consider mining at all. */
+const MIN_TRACE_LENGTH = 3;
+/**
+ * Opt-out phrases that suppress mining for the current turn. Match
+ * the SkillTeacher pattern at `moat/skillTeacher.ts:110` so a user
+ * who silences SkillTeacher also silences mining.
+ */
+const OPT_OUT_RE = /\b(stop|don['']?t|no|never)\s+(suggest|propose|create|save|learn|remember)\w*\b/i;
+/**
+ * Compute a 0..1 confidence score from programmatic trace features.
+ * Used to sort `/skills review` so the most promising candidates
+ * surface first.
+ *
+ * Components:
+ *   - lengthScore : trace length sweet spot is 5..15 (peaks at 10)
+ *   - errorRate   : already gated to 0 (no errors in trace) but the
+ *                   feature is computed for forward-compat with
+ *                   future "soft" mining that admits some errors
+ *   - distinctSet : more distinct tools = more reusable workflow
+ *   - distinctTools: simple toolset diversity
+ */
+function computeConfidence(trace) {
+    if (trace.length === 0)
+        return 0;
+    // Length score — peaks at 10, falls off at extremes.
+    const len = trace.length;
+    const lengthScore = len < 3 ? 0 :
+        len <= 10 ? len / 10 :
+            len <= 15 ? 1 - (len - 10) * 0.04 :
+                Math.max(0.4, 1 - (len - 10) * 0.05);
+    // Error rate (0 = best, 1 = worst).
+    const errors = trace.filter((e) => e.error != null).length;
+    const errorRate = errors / trace.length;
+    // Distinct tool diversity.
+    const distinctTools = new Set(trace.map((e) => e.name)).size;
+    const diversityScore = Math.min(1, distinctTools / 4);
+    // Distinct toolsets diversity (some traces tag entries).
+    const distinctSets = new Set(trace.map((e) => e.toolset ?? '').filter(Boolean)).size;
+    const setBonus = Math.min(0.2, distinctSets * 0.1);
+    // Weighted average — length and diversity dominate, error penalty
+    // proportional to rate.
+    const raw = 0.55 * lengthScore + 0.35 * diversityScore + setBonus - errorRate;
+    return Math.max(0, Math.min(1, Number(raw.toFixed(3))));
+}
+/** Single-trace orchestrator. Stateless except for the per-session counter. */
+class SkillMiner {
+    constructor(opts = {}) {
+        this.perSessionCount = new Map();
+        this.store = opts.store ?? new candidateStore_1.CandidateStore();
+        this.auxiliaryClient = opts.auxiliaryClient;
+        this.sessionCap = opts.sessionCap ?? exports.SESSION_SKILL_LIMIT;
+        this.skeletonOnly = opts.skeletonOnly ?? false;
+    }
+    /** Test/reset hook. */
+    _resetForTests() {
+        this.perSessionCount.clear();
+    }
+    /** Returns the count of pending candidates already attributed to a session. */
+    countForSession(sessionId) {
+        return this.perSessionCount.get(sessionId) ?? 0;
+    }
+    async observeTurn(obs) {
+        // Gate 1 — short trace.
+        if (!obs.trace || obs.trace.length < MIN_TRACE_LENGTH) {
+            return { status: 'short-trace' };
+        }
+        // Gate 2 — any tool errored.
+        if (obs.trace.some((e) => e.error != null)) {
+            return { status: 'tool-error' };
+        }
+        // Gate 3 — turn was aborted.
+        if (obs.finishReason !== 'stop') {
+            return { status: 'abort' };
+        }
+        // Gate 4 — session cap.
+        if (this.countForSession(obs.sessionId) >= this.sessionCap) {
+            return { status: 'session-cap' };
+        }
+        // Gate 5 — user opt-out anywhere in this turn's conversation.
+        for (const msg of obs.history) {
+            if (msg.role === 'user' && typeof msg.content === 'string' && OPT_OUT_RE.test(msg.content)) {
+                return { status: 'opt-out' };
+            }
+        }
+        // Fingerprint + dedup.
+        const fpEntries = obs.trace.map((e) => ({ name: e.name, args: e.args }));
+        const fingerprint = (0, traceFingerprint_1.traceFingerprint)(fpEntries);
+        const pending = await this.store.list();
+        if (pending.some((c) => c.fingerprint === fingerprint)) {
+            return { status: 'dedup-pending' };
+        }
+        const rejected = await this.store.loadRejected();
+        if (rejected.has(fingerprint)) {
+            return { status: 'dedup-rejected' };
+        }
+        // Compute confidence + first user prompt for skeleton seeding.
+        const confidence = computeConfidence(obs.trace);
+        const firstUserPrompt = (() => {
+            for (const m of obs.history) {
+                if (m.role === 'user' && typeof m.content === 'string' && m.content.trim().length > 0) {
+                    return m.content.trim();
+                }
+            }
+            return '';
+        })();
+        const ctx = {
+            firstUserPrompt,
+            sourceSessionId: obs.sessionId,
+            sourceTurnIdx: obs.sourceTurnIdx,
+            traceFingerprint: fingerprint,
+            candidateConfidence: confidence,
+        };
+        let skill = (0, proposalBuilder_1.draft)(obs.trace, ctx);
+        if (!this.skeletonOnly) {
+            skill = await (0, extractorPrompt_1.refine)(skill, { client: this.auxiliaryClient });
+        }
+        // Final validation — must round-trip through parseSkillContent
+        // (the canonical loader parser). If it doesn't, drop the
+        // candidate rather than poison the queue.
+        try {
+            (0, skillSpec_1.parseSkillContent)(skill);
+        }
+        catch {
+            return { status: 'invalid-skill', confidence };
+        }
+        const candidate = {
+            id: (0, node_crypto_1.randomUUID)(),
+            fingerprint,
+            sourceSessionId: obs.sessionId,
+            sourceTurnIdx: obs.sourceTurnIdx,
+            createdAt: new Date().toISOString(),
+            candidateConfidence: confidence,
+            skillContent: skill,
+        };
+        await this.store.append(candidate);
+        this.perSessionCount.set(obs.sessionId, this.countForSession(obs.sessionId) + 1);
+        return { status: 'queued', candidate, confidence };
+    }
+}
+exports.SkillMiner = SkillMiner;

package/dist/core/v4/skillMining/traceFingerprint.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/skillMining/traceFingerprint.ts — Phase v4.1-skill-mining
+ *
+ * Deterministic content-addressing for tool-call traces.
+ *
+ * The fingerprint is the sha256 hex of the normalized
+ * (toolName, sorted-arg-keys) sequence joined by `|`.
+ *
+ * Properties (verified by smoke):
+ *   - identical traces produce identical hashes
+ *   - traces that differ only in arg *values* (same arg keys)
+ *     produce identical hashes — this is the desired behavior:
+ *     "search github for X" and "search github for Y" should
+ *     dedup to one candidate
+ *   - traces with different tool sequences or arg keys produce
+ *     different hashes
+ *   - deterministic across runs (no salt, no time)
+ *
+ * The candidateStore + skillMiner use this to dedup proposals;
+ * the rejected list also tracks fingerprints so a user-rejected
+ * workflow doesn't get re-proposed on the next run.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceFingerprint = traceFingerprint;
+const node_crypto_1 = require("node:crypto");
+/** Normalize a single trace entry to its fingerprint contribution. */
+function normalizeEntry(entry) {
+    const name = String(entry.name ?? '').trim().toLowerCase();
+    let argKeys = [];
+    if (entry.args && typeof entry.args === 'object' && !Array.isArray(entry.args)) {
+        argKeys = Object.keys(entry.args).sort();
+    }
+    return `${name}(${argKeys.join(',')})`;
+}
+/**
+ * Fingerprint a trace. Returns a 64-char lowercase sha256 hex.
+ * Empty trace is a valid input (returns the hash of the empty
+ * normalized string) — callers should reject empty traces before
+ * fingerprinting to keep the pending queue free of useless entries.
+ */
+function traceFingerprint(trace) {
+    const normalized = trace.map(normalizeEntry).join('|');
+    return (0, node_crypto_1.createHash)('sha256').update(normalized, 'utf8').digest('hex');
+}

package/dist/core/v4/subagent/budget.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/subagent/budget.ts — Phase v4.1-subagent
+ *
+ * Per-subagent timeouts and iteration caps. Two budgets layered:
+ *
+ *   - `perSubagentTimeoutMs` — hard wall-clock cap on a single
+ *     subagent. Fired via AbortController; AidenAgent's provider
+ *     adapter receives the abort and the in-flight HTTP call is
+ *     cancelled (the v3 lesson — flag-only cancellation leaks
+ *     tokens, AbortController plumbed through is the v4 fix).
+ *
+ *   - `wallClockCapMs` — outer cap on the whole fanout. Defaults
+ *     to 5× the per-subagent timeout because parallel subagents
+ *     should finish faster than 5× one-at-a-time, but variance
+ *     (provider rate limits, retry backoff) can extend the tail.
+ *
+ *   - `maxIterations` — fresh per subagent. v3 starved nested
+ *     spawns by dividing a global budget; v4 hands each subagent a
+ *     full fresh budget and relies on the wall-clock cap for the
+ *     outer bound.
+ *
+ * Read at fanout start. Each subagent gets its own AbortSignal
+ * derived from the timeout; abort propagates from parent down via
+ * `parentAbort.aborted`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_FANOUT_N = exports.MAX_FANOUT_N = exports.WALL_CLOCK_CAP_MULT = exports.DEFAULT_SUBAGENT_MAX_ITERATIONS = exports.DEFAULT_SUBAGENT_TIMEOUT_MS = void 0;
+exports.resolveBudget = resolveBudget;
+exports.validateN = validateN;
+/** Default per-subagent timeout (ms). Override via env
+ *  `AIDEN_SUBAGENT_TIMEOUT_MS` or `timeoutMs` argument on the tool. */
+exports.DEFAULT_SUBAGENT_TIMEOUT_MS = 90000;
+/** Default per-subagent iteration cap. Fresh per subagent. */
+exports.DEFAULT_SUBAGENT_MAX_ITERATIONS = 20;
+/** Wall-clock cap multiplier — outer cap = `perSubagentTimeoutMs * MULT`. */
+exports.WALL_CLOCK_CAP_MULT = 5;
+/** Max N — hard refuse beyond. */
+exports.MAX_FANOUT_N = 5;
+/** Default N when the caller doesn't specify. */
+exports.DEFAULT_FANOUT_N = 3;
+/** Resolve the live budget. Tool-call argument > env > module default. */
+function resolveBudget(opts = {}) {
+    const env = opts.env ?? process.env;
+    const envTimeoutRaw = env.AIDEN_SUBAGENT_TIMEOUT_MS;
+    const envTimeout = envTimeoutRaw && /^\d+$/.test(envTimeoutRaw)
+        ? Number.parseInt(envTimeoutRaw, 10)
+        : null;
+    const perSubagentTimeoutMs = opts.timeoutMs ?? envTimeout ?? exports.DEFAULT_SUBAGENT_TIMEOUT_MS;
+    return {
+        perSubagentTimeoutMs,
+        wallClockCapMs: perSubagentTimeoutMs * exports.WALL_CLOCK_CAP_MULT,
+        maxIterations: exports.DEFAULT_SUBAGENT_MAX_ITERATIONS,
+    };
+}
+/** Validate the requested N — throws with a clear message when out of
+ *  bounds. Caller surfaces the error as a tool-result error string. */
+function validateN(n) {
+    if (!Number.isFinite(n) || !Number.isInteger(n)) {
+        throw new Error(`subagent_fanout: n must be an integer, got ${n}`);
+    }
+    if (n < 1) {
+        throw new Error(`subagent_fanout: n must be >= 1, got ${n}`);
+    }
+    if (n > exports.MAX_FANOUT_N) {
+        throw new Error(`subagent_fanout: n=${n} exceeds hard cap ${exports.MAX_FANOUT_N}. ` +
+            `Higher concurrency hits provider RPM limits and increases tail latency variance.`);
+    }
+    return n;
+}

package/dist/core/v4/subagent/diagnostics.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/subagent/diagnostics.ts — Phase v4.1-subagent
+ *
+ * Build fingerprint + counts surfaced by `aiden subagent status` and
+ * the per-fanout result envelope. The fingerprint follows the same
+ * convention every Aiden phase since v4.1-3.2 has used: a constant
+ * string the user can grep for to verify the running build matches
+ * the phase they expected. Bump on every shipped phase. Format:
+ * `v4.1-subagent[+suffix]`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AIDEN_SUBAGENT_BUILD = void 0;
+/** Build fingerprint — bump per phase. Surfaced in `aiden subagent
+ *  status` and the post-fanout summary line. */
+exports.AIDEN_SUBAGENT_BUILD = 'v4.1-subagent.2';