@winspan/claude-forge 8.54.4 → 9.12.0

package/dist/core/insights/agent-health.js

@@ -0,0 +1,296 @@
+/**
+ * Agent 体检 — per-agent health aggregation (decision 234f1ad4, Phase 1).
+ *
+ * Pure read-side aggregator + suggestion rules. Combines:
+ *   - delegation / success-rate / duration  ← aggregateAgentSpawns (events,
+ *     read-time Pre/Post pairing; success_rate口径标 INDIRECT，跨 session 边缘有误差)
+ *   - skill usefulness by agent             ← aggregateSkillUsefulnessByAgent
+ *     (reason-prefix proxy key, NOT agent_id — agent_id empirically all-NULL)
+ *   - KB usefulness by agent                ← aggregateKbUsefulnessByAgent
+ *   - (agent, skill) closed-loop status     ← derived recommendation_health
+ *   - main-thread violations                ← tool_intercepts (by session; these
+ *     are orchestration discipline, NOT agent template defects — shown separately)
+ *
+ * 不变量 (cross-Phase): this module is READ-ONLY. It NEVER mutates agent
+ * templates; it only produces health objects + readable suggestion strings.
+ * The daemon does not call this — only the web endpoint and `cf agent retro`.
+ */
+// ── Tunable thresholds + rules (top-of-file constants, per spec) ────────────
+/**
+ * Reason-prefix (proxy agent key from skill_invocations.reason) → agent template
+ * name (the `src/daemon/templates/agents/*.md` source-of-truth basename). The
+ * reason prefix is what agents hardcode in `--reason "coder/<phase>"`, but the
+ * trigger-table / template name differs for several agents.
+ */
+export const REASON_PREFIX_TO_AGENT = {
+    coder: 'coder',
+    verify: 'verify-agent',
+    decision: 'decision-maker',
+    safetynet: 'safety-net-implementer',
+    planner: 'planner',
+    harness: 'harness-debug-full',
+};
+/** Map a reason prefix to its canonical agent template name (identity fallback). */
+export function agentForReasonPrefix(prefix) {
+    return REASON_PREFIX_TO_AGENT[prefix] ?? prefix;
+}
+/**
+ * recommendation_health classification thresholds (decision 234f1ad4 Q7).
+ * `dead`: pulls >= DEAD_MIN_PULLS && actionable_rate < DEAD_ACTIONABLE_RATE
+ *   (STRICT helped-only rate). The coder × distilled-executing-plans pair
+ *   (70 pull / actionable≈1.5%) is the live `dead` sample.
+ */
+export const DEAD_MIN_PULLS = 20;
+export const DEAD_ACTIONABLE_RATE = 0.1; // < 10%
+/** `live`: enough pulls AND actionable_rate at/above this healthy floor. */
+export const LIVE_ACTIONABLE_RATE = 0.5; // >= 50%
+/** `unrated`: pulls >= threshold but rated-ratio below this (can't judge). */
+export const UNRATED_MIN_PULLS = DEAD_MIN_PULLS;
+export const UNRATED_RATED_RATIO = 0.3; // < 30% of pulls rated → unrated
+/** Min total_rated before a (agent,skill) pair is allowed to产 a suggestion. */
+export const SUGGESTION_MIN_RATED = 10;
+/** A skill is "weak" for an agent when actionable_rate < this (with enough evidence). */
+export const WEAK_ACTIONABLE_RATE = 0.25;
+/** Min delegations before per-agent success-rate / drift signals are trusted. */
+export const MIN_DELEGATIONS_FOR_SIGNAL = 3;
+/**
+ * Muted (agent, skill) pairs — operator can silence noisy suggestions here.
+ * Format: `"<agent>::<skill_id>"`. Empty by default; spec R1 anti-noise.
+ */
+export const MUTED_SUGGESTIONS = new Set();
+const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * Classify a (agent, skill) pairing into a closed-loop health bucket.
+ * `triggerReferenced` = whether the agent template trigger table references the
+ * skill (used to distinguish `unused`: referenced but zero pulls).
+ */
+export function classifyRecommendationHealth(pair, triggerReferenced) {
+    if (triggerReferenced && pair.pulls === 0)
+        return 'unused';
+    // `dead` is STRICTLY gated on pulls >= DEAD_MIN_PULLS (decision 234f1ad4 Q7):
+    // a low-pull pair with 0% actionable is just under-sampled, NOT a dead推荐.
+    if (pair.pulls >= DEAD_MIN_PULLS && pair.actionable_rate < DEAD_ACTIONABLE_RATE)
+        return 'dead';
+    const ratedRatio = pair.pulls > 0 ? pair.total_rated / pair.pulls : 0;
+    if (pair.pulls >= UNRATED_MIN_PULLS && ratedRatio < UNRATED_RATED_RATIO)
+        return 'unrated';
+    if (pair.pulls >= DEAD_MIN_PULLS && pair.actionable_rate >= LIVE_ACTIONABLE_RATE)
+        return 'live';
+    // Below the dead/live pull threshold: classify as live only when it clears the
+    // healthy floor with enough rated evidence; otherwise unrated (under-sampled).
+    if (pair.total_rated >= SUGGESTION_MIN_RATED && pair.actionable_rate >= LIVE_ACTIONABLE_RATE)
+        return 'live';
+    return 'unrated';
+}
+/**
+ * Compute per-agent health objects + suggestions over the window.
+ * Pure: takes a storage handle, returns plain data (no side effects).
+ */
+export function computeAgentHealth(storage, opts) {
+    const sinceIso = new Date(opts.since).toISOString();
+    const untilIso = opts.until !== undefined ? new Date(opts.until).toISOString() : undefined;
+    const spawns = storage.aggregateAgentSpawns({
+        since: sinceIso,
+        until: untilIso,
+        recentLimit: 8,
+        // decision dd79010a: scope delegation/success/duration to the project too
+        // (skill/kb usefulness below were already project-scoped via opts.projectPath).
+        projectPath: opts.projectPath,
+    });
+    const skillByAgent = storage.aggregateSkillUsefulnessByAgent({
+        since: opts.since,
+        until: opts.until,
+        projectPath: opts.projectPath,
+    });
+    const kbByAgent = storage.aggregateKbUsefulnessByAgent({
+        since: opts.since,
+        until: opts.until,
+        project_path: opts.projectPath,
+    });
+    // Bug-fix (insights project filter parity, 2026-06-15): when a SPECIFIC
+    // project is requested, the triggerRefs-driven `unused` synthesis below MUST
+    // be suppressed. `triggerRefs` is a global agent-template ⇄ skill metadata map
+    // (project-independent), so injecting its zero-pull `unused` pairs — and
+    // unioning its agent names into `agentNames` (see further down) — would
+    // manufacture agents that have NO project-scoped activity. That made
+    // /api/insights/agent-health?project=<bogus> return 1 agent (verify-agent,
+    // delegations=0, one `unused` skill) while /agent-stats?project=<bogus>
+    // correctly returned 0. Strict equality on the project-scoped aggregations
+    // (events / skill / kb usefulness, all `project_path = ?`) already excludes
+    // NULL/other-project rows; the only remaining leak was this global template
+    // synthesis. So: only honour triggerRefs (unused detection + name union) in
+    // the all-projects view (no project filter). agent-stats has no triggerRefs
+    // path at all, which is why it never leaked — this brings the two to parity.
+    const projectScoped = opts.projectPath !== undefined && opts.projectPath !== '';
+    const effectiveTriggerRefs = projectScoped ? undefined : opts.triggerRefs;
+    // Index usefulness by canonical agent name.
+    const skillsByAgentName = new Map();
+    for (const row of skillByAgent) {
+        if (row.agent === '<unknown>')
+            continue;
+        const agentName = agentForReasonPrefix(row.agent);
+        const refs = effectiveTriggerRefs?.get(agentName);
+        const triggerReferenced = refs ? refs.has(row.skill_id) : false;
+        const rec = {
+            skill_id: row.skill_id,
+            pulls: row.pulls,
+            helped: row.helped,
+            partial: row.partial,
+            not_actionable: row.not_actionable,
+            total_rated: row.total_rated,
+            pending: row.pending,
+            actionable_rate: row.actionable_rate,
+            recommendation_health: classifyRecommendationHealth(row, triggerReferenced),
+        };
+        const arr = skillsByAgentName.get(agentName) ?? [];
+        arr.push(rec);
+        skillsByAgentName.set(agentName, arr);
+    }
+    // Add `unused` pairs: trigger-referenced skills with zero pulls in window.
+    // Suppressed under a specific project scope (see projectScoped note above).
+    if (effectiveTriggerRefs) {
+        for (const [agentName, refSkills] of effectiveTriggerRefs) {
+            const existing = skillsByAgentName.get(agentName) ?? [];
+            const seen = new Set(existing.map((s) => s.skill_id));
+            for (const skillId of refSkills) {
+                if (seen.has(skillId))
+                    continue;
+                existing.push({
+                    skill_id: skillId,
+                    pulls: 0,
+                    helped: 0,
+                    partial: 0,
+                    not_actionable: 0,
+                    total_rated: 0,
+                    pending: 0,
+                    actionable_rate: 0,
+                    recommendation_health: 'unused',
+                });
+            }
+            skillsByAgentName.set(agentName, existing);
+        }
+    }
+    const kbByAgentName = new Map();
+    for (const row of kbByAgent) {
+        if (row.agent === '<unknown>')
+            continue;
+        const agentName = agentForReasonPrefix(row.agent);
+        kbByAgentName.set(agentName, {
+            pulls: row.pulls,
+            total_rated: row.total_rated,
+            helped: row.helped,
+            actionable_rate: row.actionable_rate,
+        });
+    }
+    // Union of agent names from spawns + usefulness + trigger refs.
+    const agentNames = new Set();
+    for (const s of spawns)
+        agentNames.add(s.agent);
+    for (const k of skillsByAgentName.keys())
+        agentNames.add(k);
+    for (const k of kbByAgentName.keys())
+        agentNames.add(k);
+    if (effectiveTriggerRefs)
+        for (const k of effectiveTriggerRefs.keys())
+            agentNames.add(k);
+    const spawnByName = new Map(spawns.map((s) => [s.agent, s]));
+    const isBuiltin = opts.isBuiltin ?? (() => false);
+    const agents = [];
+    for (const name of agentNames) {
+        const spawn = spawnByName.get(name);
+        const delegations = spawn?.delegations ?? 0;
+        const success = spawn?.success ?? 0;
+        const partial = spawn?.partial ?? 0;
+        const failed = spawn?.failed ?? 0;
+        const unrated = spawn?.unrated ?? 0;
+        const rated = success + partial + failed;
+        const hasSignal = delegations >= MIN_DELEGATIONS_FOR_SIGNAL && rated > 0;
+        const success_rate = hasSignal ? Math.round((success / rated) * 1000) / 1000 : null;
+        const success_rate_basis = hasSignal ? 'indirect' : 'insufficient_data';
+        const recommended = (skillsByAgentName.get(name) ?? []).sort((a, b) => a.actionable_rate - b.actionable_rate || b.pulls - a.pulls);
+        const weak_skills = recommended
+            .filter((r) => r.total_rated >= SUGGESTION_MIN_RATED && r.actionable_rate < WEAK_ACTIONABLE_RATE)
+            .map((r) => ({
+            skill_id: r.skill_id,
+            actionable_rate: r.actionable_rate,
+            total_rated: r.total_rated,
+            pulls: r.pulls,
+        }));
+        const suggestions = buildSuggestions(name, recommended, weak_skills);
+        agents.push({
+            agent: name,
+            source: isBuiltin(name) ? 'builtin' : 'project',
+            delegations,
+            success,
+            partial,
+            failed,
+            unrated,
+            success_rate,
+            success_rate_basis,
+            avg_duration_ms: spawn?.avg_duration_ms ?? null,
+            last_ts: spawn?.last_ts ?? 0,
+            weak_skills,
+            recommended_skills: recommended,
+            kb_usage: kbByAgentName.get(name) ?? null,
+            suggestions,
+        });
+    }
+    agents.sort((a, b) => b.delegations - a.delegations || a.agent.localeCompare(b.agent));
+    return {
+        generated_at: new Date().toISOString(),
+        since: sinceIso,
+        until: untilIso ?? null,
+        agents,
+        main_thread_violations: computeMainThreadViolations(storage, sinceIso, untilIso),
+    };
+}
+/**
+ * Build readable improvement suggestions for an agent (decision 234f1ad4).
+ * High-threshold (SUGGESTION_MIN_RATED) + mutable mute list to avoid noise (R1).
+ */
+function buildSuggestions(agent, recommended, weakSkills) {
+    const out = [];
+    for (const w of weakSkills) {
+        if (MUTED_SUGGESTIONS.has(`${agent}::${w.skill_id}`))
+            continue;
+        const rec = recommended.find((r) => r.skill_id === w.skill_id);
+        const ratePct = (w.actionable_rate * 100).toFixed(1);
+        if (rec && rec.recommendation_health === 'dead') {
+            out.push(`${agent} 推荐 ${w.skill_id}：${w.pulls} pull / ${rec.helped} helped / ${rec.partial} partial（actionable_rate ${ratePct}%，样本 ${w.total_rated}≥阈值）→ 死推荐，建议换 skill 或精简该 pull 步措辞。`);
+        }
+        else {
+            out.push(`${agent} 推荐 ${w.skill_id}：actionable_rate ${ratePct}%（样本 ${w.total_rated}≥阈值）→ 弱推荐，建议复核该 pull 步。`);
+        }
+    }
+    return out;
+}
+/**
+ * Aggregate main-thread (orchestration discipline) violations from
+ * tool_intercepts in window. These are NOT agent template defects — surfaced
+ * separately with an explicit note (decision实测: 违规 != agent 缺陷).
+ */
+function computeMainThreadViolations(storage, sinceIso, untilIso) {
+    const note = '主线程编排纪律（edit/write-multi-file-hard 等），非 agent 模板缺陷——与 agent 自身信号分开展示。';
+    try {
+        // tool_intercepts.timestamp is ISO TEXT (NOT INTEGER ms) — compare ISO直接.
+        const db = storage.db;
+        const conditions = ['decision = ?', 'timestamp >= ?'];
+        const params = ['deny', sinceIso];
+        if (untilIso !== undefined) {
+            conditions.push('timestamp < ?');
+            params.push(untilIso);
+        }
+        const rows = db
+            .prepare(`SELECT rule_id, COUNT(*) AS count FROM tool_intercepts
+         WHERE ${conditions.join(' AND ')}
+         GROUP BY rule_id ORDER BY count DESC`)
+            .all(...params);
+        const total = rows.reduce((s, r) => s + r.count, 0);
+        return { total, by_rule: rows, note };
+    }
+    catch {
+        return { total: 0, by_rule: [], note };
+    }
+}
+export { DAY_MS };
+//# sourceMappingURL=agent-health.js.map

package/dist/core/insights/agent-health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-health.js","sourceRoot":"","sources":["../../../src/core/insights/agent-health.ts"],"names":[],"mappings":"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"}

package/dist/core/insights/agent-patch-apply.d.ts

@@ -0,0 +1,45 @@
+/**
+ * agent-patch-apply.ts — pure-JS unified-diff applier for agent-template
+ * adoption (decision 568a8c53, user Open-Q1).
+ *
+ * Why NOT `git apply`: the daemon runs under launchd with cwd=`/` (no working
+ * tree), so `git apply` fails there (same landmine documented in
+ * skills-distill.ts:559). The web adopt path needs a working tree-INDEPENDENT
+ * application that resolves the patch against the in-memory template text.
+ *
+ * Scope: this is a deliberately small, strict context-matching applier — NOT a
+ * full GNU patch / git-apply re-implementation. It handles the unified-diff
+ * shape the `agent-retro-distiller` emits:
+ *   - one or more `@@ ... @@` hunks
+ *   - context lines (leading space), additions (`+`), removals (`-`)
+ *   - optional `--- a/...` / `+++ b/...` file headers (ignored)
+ *
+ * It is ATOMIC: if any hunk fails to match its context against the current text
+ * it throws `PatchApplyError` and returns NOTHING (no partial write). Callers
+ * map the throw to HTTP 422. Pure: no IO.
+ */
+export declare class PatchApplyError extends Error {
+    /** Index (1-based) of the hunk that failed, when known. */
+    readonly hunkIndex: number | null;
+    constructor(message: string, hunkIndex?: number | null);
+}
+/**
+ * Apply a unified-diff `patch` to `source` text, returning the new text.
+ *
+ * Atomic + strict: every hunk's context (+removed) side must match exactly once
+ * in the current text, else throw (no partial application). The trailing newline
+ * convention of `source` is preserved.
+ *
+ * Pure: no IO, no template writes.
+ */
+export declare function applyUnifiedDiff(source: string, patch: string): string;
+/**
+ * Mechanically set the `version:` line inside the leading YAML frontmatter to
+ * `targetVersion`. The anchor-guard forbids the distiller from touching the
+ * version line; adoption bumps it here, deterministically. Returns the new text.
+ *
+ * Throws if no frontmatter `version:` line is found (the template invariant
+ * requires one). Pure.
+ */
+export declare function setFrontmatterVersion(template: string, targetVersion: number): string;
+//# sourceMappingURL=agent-patch-apply.d.ts.map

package/dist/core/insights/agent-patch-apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-patch-apply.d.ts","sourceRoot":"","sources":["../../../src/core/insights/agent-patch-apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;gBACtB,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,MAAM,GAAG,IAAW;CAK7D;AAuGD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAmBtE;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAQrF"}

package/dist/core/insights/agent-patch-apply.js

@@ -0,0 +1,165 @@
+/**
+ * agent-patch-apply.ts — pure-JS unified-diff applier for agent-template
+ * adoption (decision 568a8c53, user Open-Q1).
+ *
+ * Why NOT `git apply`: the daemon runs under launchd with cwd=`/` (no working
+ * tree), so `git apply` fails there (same landmine documented in
+ * skills-distill.ts:559). The web adopt path needs a working tree-INDEPENDENT
+ * application that resolves the patch against the in-memory template text.
+ *
+ * Scope: this is a deliberately small, strict context-matching applier — NOT a
+ * full GNU patch / git-apply re-implementation. It handles the unified-diff
+ * shape the `agent-retro-distiller` emits:
+ *   - one or more `@@ ... @@` hunks
+ *   - context lines (leading space), additions (`+`), removals (`-`)
+ *   - optional `--- a/...` / `+++ b/...` file headers (ignored)
+ *
+ * It is ATOMIC: if any hunk fails to match its context against the current text
+ * it throws `PatchApplyError` and returns NOTHING (no partial write). Callers
+ * map the throw to HTTP 422. Pure: no IO.
+ */
+export class PatchApplyError extends Error {
+    /** Index (1-based) of the hunk that failed, when known. */
+    hunkIndex;
+    constructor(message, hunkIndex = null) {
+        super(`[agent-patch-apply] ${message}`);
+        this.name = 'PatchApplyError';
+        this.hunkIndex = hunkIndex;
+    }
+}
+/** Split a unified diff into hunks, dropping file headers + `@@` markers. */
+function parseHunks(patch) {
+    const rawLines = patch.split('\n');
+    const hunks = [];
+    let current = null;
+    for (const line of rawLines) {
+        if (line.startsWith('--- ') || line.startsWith('+++ ')) {
+            // file header — ignored
+            continue;
+        }
+        if (line.startsWith('@@')) {
+            current = { lines: [] };
+            hunks.push(current);
+            continue;
+        }
+        if (current === null) {
+            // Lines before the first @@ that are not file headers: tolerate blank /
+            // stray lines (the distiller sometimes prefixes a fenced block).
+            if (line.trim() === '')
+                continue;
+            // A non-empty body line outside any hunk → malformed.
+            // Be lenient about a leading "diff --git" style line.
+            if (line.startsWith('diff ') || line.startsWith('index '))
+                continue;
+            continue;
+        }
+        current.lines.push(line);
+    }
+    return hunks;
+}
+/**
+ * The "old" (context + removed) side and "new" (context + added) side of a hunk,
+ * as arrays of full-line strings (markers stripped).
+ */
+function hunkSides(hunk) {
+    const oldLines = [];
+    const newLines = [];
+    for (const l of hunk.lines) {
+        if (l.startsWith('+')) {
+            newLines.push(l.slice(1));
+        }
+        else if (l.startsWith('-')) {
+            oldLines.push(l.slice(1));
+        }
+        else if (l.startsWith(' ')) {
+            oldLines.push(l.slice(1));
+            newLines.push(l.slice(1));
+        }
+        else if (l === '') {
+            // An empty line in the hunk body == a context blank line.
+            oldLines.push('');
+            newLines.push('');
+        }
+        else if (l === '\') {
+            // ignore the GNU no-newline marker
+        }
+        else {
+            // Unknown marker — treat as context to be conservative.
+            oldLines.push(l);
+            newLines.push(l);
+        }
+    }
+    return { oldLines, newLines };
+}
+/** Find the single index where `needle` matches `hay` exactly. */
+function findMatch(hay, needle, hunkIndex) {
+    if (needle.length === 0) {
+        // Pure-insertion hunk with no context — cannot anchor reliably. Reject.
+        throw new PatchApplyError(`hunk ${hunkIndex} has no context/removed lines to anchor against`, hunkIndex);
+    }
+    let found = -1;
+    for (let i = 0; i + needle.length <= hay.length; i++) {
+        let ok = true;
+        for (let j = 0; j < needle.length; j++) {
+            if (hay[i + j] !== needle[j]) {
+                ok = false;
+                break;
+            }
+        }
+        if (ok) {
+            if (found !== -1) {
+                throw new PatchApplyError(`hunk ${hunkIndex} context is ambiguous (matches at multiple locations)`, hunkIndex);
+            }
+            found = i;
+        }
+    }
+    if (found === -1) {
+        throw new PatchApplyError(`hunk ${hunkIndex} context did not match the current template`, hunkIndex);
+    }
+    return found;
+}
+/**
+ * Apply a unified-diff `patch` to `source` text, returning the new text.
+ *
+ * Atomic + strict: every hunk's context (+removed) side must match exactly once
+ * in the current text, else throw (no partial application). The trailing newline
+ * convention of `source` is preserved.
+ *
+ * Pure: no IO, no template writes.
+ */
+export function applyUnifiedDiff(source, patch) {
+    const hunks = parseHunks(patch);
+    if (hunks.length === 0) {
+        throw new PatchApplyError('patch contains no hunks');
+    }
+    const hadTrailingNewline = source.endsWith('\n');
+    // Work on lines WITHOUT the trailing empty element a trailing \n produces.
+    let lines = source.split('\n');
+    if (hadTrailingNewline)
+        lines = lines.slice(0, -1);
+    hunks.forEach((hunk, idx) => {
+        const hunkIndex = idx + 1;
+        const { oldLines, newLines } = hunkSides(hunk);
+        const at = findMatch(lines, oldLines, hunkIndex);
+        lines = [...lines.slice(0, at), ...newLines, ...lines.slice(at + oldLines.length)];
+    });
+    return hadTrailingNewline ? lines.join('\n') + '\n' : lines.join('\n');
+}
+/**
+ * Mechanically set the `version:` line inside the leading YAML frontmatter to
+ * `targetVersion`. The anchor-guard forbids the distiller from touching the
+ * version line; adoption bumps it here, deterministically. Returns the new text.
+ *
+ * Throws if no frontmatter `version:` line is found (the template invariant
+ * requires one). Pure.
+ */
+export function setFrontmatterVersion(template, targetVersion) {
+    const fenceEnd = template.indexOf('\n---', 4);
+    const head = fenceEnd > 0 ? template.slice(0, fenceEnd) : template;
+    if (!/^version:\s*[0-9]+\s*$/m.test(head)) {
+        throw new PatchApplyError('template has no frontmatter `version:` line to bump');
+    }
+    const headBumped = head.replace(/^version:\s*[0-9]+\s*$/m, `version: ${targetVersion}`);
+    return fenceEnd > 0 ? headBumped + template.slice(fenceEnd) : headBumped;
+}
+//# sourceMappingURL=agent-patch-apply.js.map

package/dist/core/insights/agent-patch-apply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-patch-apply.js","sourceRoot":"","sources":["../../../src/core/insights/agent-patch-apply.ts"],"names":[],"mappings":"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"}

package/dist/core/insights/agent-suggest.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Agent suggestion ranker — the deterministic decision-end mirror of C1's
+ * `rankSkills` (decision c20c2d1f, C2).
+ *
+ * Given a task description's top skill matches plus read-only historical signals
+ * (agent×skill usefulness, agent health) and an optional coverage tier, produce a
+ * ranked, REASONED agent recommendation. Pure + deterministic — NO LLM, NO
+ * embedding, no DB access (the caller wires the storage signals). The LLM
+ * (decision-maker) treats the candidate set as input and makes the final call,
+ * exactly like C1's "ranker ranks, LLM picks 0-1".
+ *
+ * Four layered signals (spec §"skill→agent mapping"):
+ *   Signal 1 (primary)  — historical (agent×skill) actionable_rate via reason-prefix
+ *                         proxy key (agent_id is empirically all-NULL).
+ *   Signal 2 (tie-break) — agent health success_rate / delegations.
+ *   Signal 3 (cold-start)— a small nature→agent prior table when Signal 1 is
+ *                         under-sampled (the relocated governance §5 judgments,
+ *                         keyed on task NATURE not coverage).
+ *   Signal 4 (backstop)  — coverage demotion: coder→safety-net-implementer for a
+ *                         <50% module, applied only when a module tier is given.
+ *
+ * 不变量: READ-ONLY data transformer. Never mutates inputs, never touches the
+ * filesystem or DB, never spawns. The daemon never calls this.
+ */
+import { REASON_PREFIX_TO_AGENT } from './agent-health.js';
+import type { CoverageTier } from './coverage-tiers.js';
+/**
+ * The spawnable IMPLEMENTATION agent pool — the recommendation universe.
+ * Excludes pipeline roles (verify / decision) which are not "the agent to spawn
+ * for the work". Order is stable for deterministic alphabetical tie-breaks.
+ */
+export declare const IMPL_AGENT_POOL: readonly ["coder", "harness-debug-full", "planner", "safety-net-implementer"];
+export type ImplAgent = (typeof IMPL_AGENT_POOL)[number];
+/**
+ * Signal-3 cold-start prior — task NATURE → agent, relocated from the
+ * decision-maker.md Step 3 prose selection guide. Each nature carries the
+ * keywords that signal it (matched against the task tokens) and the agent it
+ * implies. NOT keyed on coverage — coverage enters only via Signal 4.
+ *
+ * Priority: when multiple natures match, the one with the most keyword hits wins;
+ * ties break by the array order below (most specific first). This is the
+ * irreducible floor that makes C2 ≈ the old guide before Signal-1 data accrues.
+ */
+export interface NaturePrior {
+    nature: string;
+    agent: ImplAgent;
+    keywords: string[];
+}
+export declare const NATURE_PRIOR_TABLE: readonly NaturePrior[];
+/** One skill match from rankSkills (C1). */
+export interface SkillMatchInput {
+    id: string;
+    score: number;
+}
+/** One (agent×skill) usefulness row from aggregateSkillUsefulnessByAgent. */
+export interface AgentSkillAffinityInput {
+    /** Reason-prefix proxy agent key (coder / safetynet / verify / ...). */
+    agent: string;
+    skill_id: string;
+    total_rated: number;
+    actionable_rate: number;
+}
+/** One agent-health row (subset of computeAgentHealth's AgentHealth). */
+export interface AgentHealthInput {
+    /** Canonical agent template name (already mapped from reason prefix). */
+    agent: string;
+    success_rate: number | null;
+    delegations: number;
+}
+export interface SuggestAgentsInput {
+    taskDesc: string;
+    /** Top skill matches for the task (from rankSkills). */
+    skillMatches: SkillMatchInput[];
+    /** (agent×skill) usefulness rows (from aggregateSkillUsefulnessByAgent). */
+    skillByAgent: AgentSkillAffinityInput[];
+    /** Per-agent health rows (from computeAgentHealth). */
+    agentHealth: AgentHealthInput[];
+    /** Resolved coverage tier for --module (Signal 4); omit → backstop skipped. */
+    moduleCoverageTier?: CoverageTier;
+    /** Module path (for the coverage_note text only). */
+    modulePath?: string;
+}
+export interface AgentCandidate {
+    agent: string;
+    score: number;
+    reasons: string[];
+    /** Set when Signal-4 demoted this candidate (e.g. "coder"). */
+    demoted_from?: string;
+    /** Confidence label driven by Signal-1 evidence sufficiency. */
+    confidence: 'data-backed' | 'nature-prior';
+}
+export interface AgentSuggestResult {
+    task: string;
+    candidates: AgentCandidate[];
+    coverage_note: string;
+}
+/**
+ * Compute the Signal-3 nature prior for a task: the best-matching nature→agent
+ * and the keyword hit count. Deterministic: most keyword hits wins, ties by
+ * NATURE_PRIOR_TABLE order. Returns the default new-feature agent with 0 hits
+ * when nothing matches.
+ */
+export declare function computeNaturePrior(taskDesc: string): {
+    agent: ImplAgent;
+    nature: string;
+    hits: number;
+};
+/**
+ * Apply the Signal-4 coverage backstop to a single candidate (pure). Demotes a
+ * `coder` recommendation to `safety-net-implementer` when the module tier is
+ * `low` (<50% lines). One-way safety filter — never promotes, never touches
+ * non-coder agents. Returns a (possibly) new candidate; never mutates input.
+ */
+export declare function applyCoverageBackstop(candidate: AgentCandidate, tier: CoverageTier | undefined, modulePath?: string): AgentCandidate;
+/**
+ * Rank implementation agents for a task. Pure + deterministic.
+ *
+ * Scoring口径 (per spec): for each agent in IMPL_AGENT_POOL,
+ *   score = Σ over skillMatches of (skillMatch.score × affinity) where
+ *     affinity = (agent,skill) actionable_rate when total_rated ≥ SUGGESTION_MIN_RATED
+ *                (Signal 1, data-backed),
+ *     else +1 for the agent picked by the nature prior (Signal 3, cold-start).
+ * Tie-break: success_rate desc → delegations desc → agent name asc (Signal 2 +
+ * determinism). Coverage backstop (Signal 4) is post-applied per candidate.
+ */
+export declare function suggestAgents(input: SuggestAgentsInput): AgentSuggestResult;
+export { REASON_PREFIX_TO_AGENT };
+//# sourceMappingURL=agent-suggest.d.ts.map