@winspan/claude-forge 8.54.4 → 9.12.0

package/dist/cli/commands/agent.js

@@ -0,0 +1,690 @@
+/**
+ * `cf agent` — analysis / retro commands for agent templates (decision 234f1ad4).
+ *
+ * Distinct from the plural `cf agents` family (sync/list = template deployment):
+ * `cf agent retro` is a READ-ONLY analysis report ("Agent 体检 / 模板改进建议").
+ *
+ *   cf agent retro [--agent <name>] [--days N] [--json] [--mint]
+ *
+ * 不变量 (cross-Phase, decision 234f1ad4): READ-ONLY. The report NEVER writes
+ * agent templates — it only reads health/drift signals and prints suggestions.
+ * `--mint` (default OFF) is reserved for routing high-confidence suggestions into
+ * the existing nudge/decisions register chain; this first version is text-only.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { SQLiteStorage } from '../../core/storage/sqlite.js';
+import { FORGE_PATHS } from '../../core/constants.js';
+import { isBuiltinAgent } from '../../core/utils/cc-builtin-agents.js';
+import { computeAgentHealth, DAY_MS, SUGGESTION_MIN_RATED, } from '../../core/insights/agent-health.js';
+import { detectAgentDrift } from '../../core/insights/agent-drift.js';
+import { loadKnownSkillIds, loadTriggerRefs, resolveAgentTemplatesDir, } from '../../core/insights/agent-evolution-sources.js';
+import { suggestAgents } from '../../core/insights/agent-suggest.js';
+import { resolveCoverageTier } from '../../core/insights/coverage-tiers.js';
+import { buildDistillContext, } from '../../core/insights/agent-distill-context.js';
+import { spawnAgentRetroDistiller, parseAgentPatchEnvelope, } from '../../core/insights/agent-distill-spawn.js';
+import { scanAgentPatch } from '../../core/insights/agent-anchor-guard.js';
+import { rankSkills } from './skills.js';
+import { SkillRegistry } from '../../skills/registry.js';
+export function register(program) {
+    const cmd = program
+        .command('agent')
+        .description('Agent analysis / retro (READ-ONLY; distinct from `cf agents` deployment)');
+    cmd
+        .command('retro')
+        .description('Per-agent 体检 + 模板改进建议报告（含死推荐/悬空引用，只读不改模板）')
+        .option('--agent <name>', 'Filter to a single agent (template name, e.g. coder)')
+        .option('--days <n>', 'Trailing window in days (default 30)')
+        .option('--json', 'Output JSON instead of text')
+        .option('--mint', 'Mint high-confidence suggestions as nudges (default OFF; no-op in Phase 1)')
+        .action((opts) => {
+        const code = runRetro(opts);
+        if (code !== 0)
+            process.exit(code);
+    });
+    // `cf agent suggest <task-desc>` — deterministic agent recommendation
+    // (decision c20c2d1f, C2). The decision-end mirror of `cf skill search` (C1):
+    // ranks implementation agents by skill affinity + agent-health + nature prior,
+    // with a coverage backstop (coder→safety-net-implementer for <50% modules).
+    // Read-only; deterministic; --json for decision-maker to parse. The LLM makes
+    // the final call over these candidates.
+    cmd
+        .command('suggest <task-desc>')
+        .description('Rank implementation agents for a task (skill + health + coverage backstop; decision-maker picks final)')
+        .option('--module <path>', 'Touched module path — enables the coverage backstop (coder→safety-net for <50% modules)')
+        .option('--days <n>', 'Trailing window in days for the signals (default 30)')
+        .option('--top <n>', 'Max candidates to return (default 4 = whole impl pool)')
+        .option('--json', 'Output JSON (machine-readable; for decision-maker parsing)')
+        .action((taskDesc, opts) => {
+        const code = runSuggest(taskDesc, opts);
+        if (code !== 0)
+            process.exit(code);
+    });
+    // `cf agent distill <agent>` — Phase 3 retro-distill (decision 234f1ad4).
+    // Human-triggered ONLY. Assembles read-only health/drift/failure signals, then
+    // (non-dry-run) spawns `agent-retro-distiller` headless → parses the envelope
+    // → anchor-guard → writes a DRAFT to docs/ (NEVER auto-applies to templates).
+    // --dry-run is the only path automated tests exercise (no LLM spawn).
+    cmd
+        .command('distill <agent>')
+        .description('Draft a template improvement from real usage signals (human-reviewed; never auto-applied)')
+        .option('--days <n>', 'Signal + execution window in days (default 30)')
+        .option('--dry-run', 'Only print the signal summary + proposed changes; do NOT spawn the LLM or write files')
+        .option('--max-failures <k>', 'Max failed-execution samples to include (default 5)')
+        .option('--out <dir>', 'Draft output directory (default docs/design/<today>/agent-distill/)')
+        .option('--json', 'Output JSON (dry-run signal context)')
+        .action(async (agent, opts) => {
+        const code = await runDistill(agent, opts);
+        if (code !== 0)
+            process.exit(code);
+    });
+    // `cf agent rollback <agent> --to <N>` — human-assisted rollback (Q4).
+    // Prints the vN draft path + suggested git ops; `--write` writes the historical
+    // git blob back to the src template AND self-checks the project-level copy is
+    // byte-identical (invariant 75344363) — non-zero exit if the copies diverge.
+    cmd
+        .command('rollback <agent>')
+        .description('Human-assisted rollback to a prior template version (--write self-checks byte-identical copies)')
+        .requiredOption('--to <n>', 'Target version number to roll back to')
+        .option('--write', 'Write the historical git blob back to the src template + self-check the project copy')
+        .action((agent, opts) => {
+        const code = runRollback(agent, opts);
+        if (code !== 0)
+            process.exit(code);
+    });
+}
+/** Default candidate count = whole impl pool. */
+const SUGGEST_DEFAULT_TOP = 4;
+/** Top skill matches fed into the agent ranker (Signal 1 source). */
+const SUGGEST_SKILL_TOP = 5;
+/**
+ * Exported for tests. Returns exit code instead of calling process.exit.
+ * Wires the read-only storage signals into the pure `suggestAgents` ranker.
+ */
+export function runSuggest(taskDesc, opts, deps = {}) {
+    const log = deps.io?.log ?? ((m) => console.log(m));
+    const error = deps.io?.error ?? ((m) => console.error(m));
+    const query = (taskDesc ?? '').trim();
+    if (!query) {
+        error('Error: a task description is required, e.g. cf agent suggest "fix a null-deref in the handler" --module src/daemon/handlers');
+        return 1;
+    }
+    const days = opts.days ? parseInt(opts.days, 10) : 30;
+    if (Number.isNaN(days) || days < 1 || days > 365) {
+        error('Error: --days must be between 1 and 365');
+        return 1;
+    }
+    let top = SUGGEST_DEFAULT_TOP;
+    if (opts.top !== undefined) {
+        const parsed = parseInt(opts.top, 10);
+        if (Number.isFinite(parsed) && parsed > 0)
+            top = parsed;
+    }
+    const ownStorage = !deps.storage;
+    let storage;
+    try {
+        storage = deps.storage ?? new SQLiteStorage(FORGE_PATHS.database());
+    }
+    catch (err) {
+        error(`Error: cannot open storage: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    try {
+        const since = Date.now() - days * DAY_MS;
+        // Signal 1 source — rank the task's top skills (reuse C1's ranker), then the
+        // (agent×skill) usefulness rows that suggestAgents joins against.
+        const registry = deps.registry ?? new SkillRegistry();
+        const skills = registry.getAll().map((s) => ({
+            id: s.id,
+            name: s.name,
+            description: s.description,
+            keywords: s.keywords,
+        }));
+        const ranked = rankSkills(skills, query, SUGGEST_SKILL_TOP);
+        const skillByAgent = storage.aggregateSkillUsefulnessByAgent({ since });
+        // Signal 2 source — agent health (success_rate / delegations).
+        const health = computeAgentHealth(storage, { since });
+        // Signal 4 — resolve the coverage tier from --module (omit → backstop off).
+        const moduleCoverageTier = opts.module ? resolveCoverageTier(opts.module) : undefined;
+        const result = suggestAgents({
+            taskDesc: query,
+            skillMatches: ranked.matches.map((m) => ({ id: m.id, score: m.score })),
+            skillByAgent: skillByAgent.map((r) => ({
+                agent: r.agent,
+                skill_id: r.skill_id,
+                total_rated: r.total_rated,
+                actionable_rate: r.actionable_rate,
+            })),
+            agentHealth: health.agents.map((a) => ({
+                agent: a.agent,
+                success_rate: a.success_rate,
+                delegations: a.delegations,
+            })),
+            moduleCoverageTier,
+            modulePath: opts.module,
+        });
+        // Apply the --top cap to the candidate list.
+        result.candidates = result.candidates.slice(0, Math.max(1, top));
+        if (opts.json) {
+            log(JSON.stringify(result, null, 2));
+            return 0;
+        }
+        renderSuggestReport(log, result, days, opts.module);
+        return 0;
+    }
+    catch (err) {
+        error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    finally {
+        if (ownStorage) {
+            try {
+                storage.close();
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+function renderSuggestReport(log, result, days, modulePath) {
+    log(`# Agent 推荐: "${result.task}"`);
+    log(`> 信号窗口: 最近 ${days} 天${modulePath ? `  |  module: ${modulePath}` : ''}`);
+    log('');
+    log(`覆盖兜底: ${result.coverage_note}`);
+    log('');
+    let rank = 1;
+    for (const c of result.candidates) {
+        const demoted = c.demoted_from ? ` (demoted_from: ${c.demoted_from})` : '';
+        log(`${rank}. ${c.agent}  [score ${c.score}, ${c.confidence}]${demoted}`);
+        for (const r of c.reasons)
+            log(`     - ${r}`);
+        rank += 1;
+    }
+    log('');
+    log('Pick the top candidate unless KB precedent / invariants say otherwise (decision-maker makes the final call).');
+}
+/**
+ * Exported for tests. Returns exit code instead of calling process.exit.
+ */
+export function runRetro(opts, deps = {}) {
+    const log = deps.io?.log ?? ((m) => console.log(m));
+    const error = deps.io?.error ?? ((m) => console.error(m));
+    const days = opts.days ? parseInt(opts.days, 10) : 30;
+    if (Number.isNaN(days) || days < 1 || days > 365) {
+        error('Error: --days must be between 1 and 365');
+        return 1;
+    }
+    const ownStorage = !deps.storage;
+    let storage;
+    try {
+        storage = deps.storage ?? new SQLiteStorage(FORGE_PATHS.database());
+    }
+    catch (err) {
+        error(`Error: cannot open storage: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    try {
+        const since = Date.now() - days * DAY_MS;
+        const triggerRefs = loadTriggerRefs();
+        const knownSkillIds = loadKnownSkillIds();
+        const health = computeAgentHealth(storage, {
+            since,
+            triggerRefs: triggerRefs.byAgent,
+            isBuiltin: isBuiltinAgent,
+        });
+        const skillUsefulness = storage.aggregateSkillUsefulness({ since });
+        const pulledByAgent = new Map();
+        const delegationsByAgent = new Map();
+        for (const a of health.agents) {
+            delegationsByAgent.set(a.agent, a.delegations);
+            const pulled = new Set();
+            for (const r of a.recommended_skills)
+                if (r.pulls > 0)
+                    pulled.add(r.skill_id);
+            pulledByAgent.set(a.agent, pulled);
+        }
+        const drift = detectAgentDrift({
+            triggerRefs,
+            knownSkillIds,
+            skillUsefulness: skillUsefulness.map((s) => ({
+                skill_id: s.skill_id,
+                total_rated: s.total_rated,
+                actionable_rate: s.actionable_rate,
+            })),
+            pulledByAgent,
+            delegationsByAgent,
+        });
+        let agents = health.agents;
+        let driftFiltered = drift;
+        if (opts.agent) {
+            agents = agents.filter((a) => a.agent === opts.agent);
+            driftFiltered = drift.filter((d) => !d.agent || d.agent === opts.agent);
+            if (agents.length === 0) {
+                error(`Error: no health data for agent "${opts.agent}" in the last ${days} days`);
+                return 1;
+            }
+        }
+        if (opts.json) {
+            log(JSON.stringify({
+                generated_at: health.generated_at,
+                days,
+                agents,
+                main_thread_violations: health.main_thread_violations,
+                drift: driftFiltered,
+                minted: false,
+            }, null, 2));
+            return 0;
+        }
+        renderTextReport(log, { days, agents, drift: driftFiltered, mainThread: health.main_thread_violations });
+        return 0;
+    }
+    catch (err) {
+        error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    finally {
+        if (ownStorage) {
+            try {
+                storage.close();
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+function renderTextReport(log, data) {
+    log(`# Agent 体检报告（最近 ${data.days} 天）`);
+    log('');
+    if (data.agents.length === 0) {
+        log('（窗口内无 agent 委托数据）');
+    }
+    for (const a of data.agents) {
+        log(`## ${a.agent} [${a.source}]`);
+        const sr = a.success_rate === null ? '未评分' : `${(a.success_rate * 100).toFixed(0)}%`;
+        log(`- 委托量: ${a.delegations}  成功率: ${sr}（口径: ${a.success_rate_basis}）`);
+        log(`- outcome: success=${a.success} partial=${a.partial} failed=${a.failed} unrated=${a.unrated}`);
+        if (a.avg_duration_ms !== null)
+            log(`- 平均耗时: ${a.avg_duration_ms} ms`);
+        if (a.recommended_skills.length > 0) {
+            log('- 推荐 skill 健康:');
+            for (const r of a.recommended_skills) {
+                const flag = r.recommendation_health === 'dead' ? ' ⚠ 死推荐' : '';
+                log(`    - ${r.skill_id}: ${r.pulls} pull / actionable ${(r.actionable_rate * 100).toFixed(1)}% [${r.recommendation_health}]${flag}`);
+            }
+        }
+        if (a.suggestions.length > 0) {
+            log('- 建议:');
+            for (const s of a.suggestions)
+                log(`    - ${s}`);
+        }
+        log('');
+    }
+    // 死推荐 / 悬空引用段（双向 drift）。
+    log('## 死推荐 / 悬空引用 / 行为 drift');
+    if (data.drift.length === 0) {
+        log('（无）');
+    }
+    else {
+        for (const d of data.drift)
+            log(`- [${d.kind}] ${d.message}`);
+    }
+    log('');
+    // 主线程编排纪律（与 agent 信号分开）。
+    log('## 主线程编排纪律（非 agent 模板缺陷）');
+    log(`- 说明: ${data.mainThread.note}`);
+    log(`- 总计 deny: ${data.mainThread.total}`);
+    for (const r of data.mainThread.by_rule)
+        log(`    - ${r.rule_id}: ${r.count}`);
+}
+/** Parse a `version: N` line from a template's frontmatter (default 1). */
+export function readTemplateVersion(templateText) {
+    // version lives in the leading frontmatter block.
+    const fenceEnd = templateText.indexOf('\n---', 4);
+    const head = fenceEnd > 0 ? templateText.slice(0, fenceEnd) : templateText;
+    const m = head.match(/^version:\s*([0-9]+)\s*$/m);
+    return m ? parseInt(m[1], 10) : 1;
+}
+/**
+ * Assemble the read-only signal context shared by --dry-run preview and the
+ * real spawn path. Pure aside from the injected storage reads + template read.
+ * Throws on a missing template (caller maps to 404). Exported for web reuse.
+ */
+export function buildAgentDistillContextFor(agent, deps) {
+    const name = (agent ?? '').trim();
+    const days = deps.days ?? 30;
+    const maxFailures = deps.maxFailures ?? 5;
+    const templatesDir = deps.templatesDir ?? resolveAgentTemplatesDir();
+    const templatePath = join(templatesDir, `${name}.md`);
+    if (!existsSync(templatePath)) {
+        throw new Error(`no agent template found at ${templatePath}`);
+    }
+    const currentTemplate = readFileSync(templatePath, 'utf-8');
+    const currentVersion = readTemplateVersion(currentTemplate);
+    const storage = deps.storage;
+    const since = Date.now() - days * DAY_MS;
+    const triggerRefs = loadTriggerRefs(templatesDir);
+    const knownSkillIds = loadKnownSkillIds();
+    const healthResult = computeAgentHealth(storage, {
+        since,
+        triggerRefs: triggerRefs.byAgent,
+        isBuiltin: isBuiltinAgent,
+    });
+    const health = healthResult.agents.find((a) => a.agent === name) ?? null;
+    const skillUsefulness = storage.aggregateSkillUsefulness({ since });
+    const pulledByAgent = new Map();
+    const delegationsByAgent = new Map();
+    for (const a of healthResult.agents) {
+        delegationsByAgent.set(a.agent, a.delegations);
+        const pulled = new Set();
+        for (const r of a.recommended_skills)
+            if (r.pulls > 0)
+                pulled.add(r.skill_id);
+        pulledByAgent.set(a.agent, pulled);
+    }
+    const allDrift = detectAgentDrift({
+        triggerRefs,
+        knownSkillIds,
+        skillUsefulness: skillUsefulness.map((s) => ({
+            skill_id: s.skill_id,
+            total_rated: s.total_rated,
+            actionable_rate: s.actionable_rate,
+        })),
+        pulledByAgent,
+        delegationsByAgent,
+    });
+    const drift = allDrift.filter((d) => !d.agent || d.agent === name);
+    const spawns = storage.aggregateAgentSpawns({
+        since: new Date(since).toISOString(),
+        recentLimit: Math.max(8, maxFailures),
+    });
+    const spawnRow = spawns.find((s) => s.agent === name);
+    const failureSamples = (spawnRow?.recent ?? [])
+        .filter((r) => r.outcome === 'failed')
+        .slice(0, maxFailures)
+        .map((r) => ({ title: r.title ?? '(untitled)', session_id: r.session_id, ts: r.ts }));
+    const ratedPairs = (health?.recommended_skills ?? []).filter((r) => r.total_rated >= SUGGESTION_MIN_RATED).length;
+    const ctx = buildDistillContext({
+        agent: name,
+        currentVersion,
+        currentTemplate,
+        health,
+        drift,
+        failureSamples,
+        windowDays: days,
+        ratedPairs,
+    });
+    return { ctx, currentVersion, drift, health, failureSamples };
+}
+/**
+ * Web-callable: the --dry-run preview payload. FREE — never spawns the LLM.
+ * Throws on a missing template (route maps to 404).
+ */
+export function buildAgentDistillPreview(agent, deps) {
+    const { ctx, currentVersion, drift, health, failureSamples } = buildAgentDistillContextFor(agent, deps);
+    return {
+        agent: (agent ?? '').trim(),
+        current_version: currentVersion,
+        maturity: ctx.maturity,
+        enough_signal: ctx.enoughSignal,
+        insufficient_reason: ctx.insufficientReason,
+        proposed_change_types: ctx.proposedChangeTypes,
+        drift,
+        recommended_skills: health?.recommended_skills ?? [],
+        failure_samples: failureSamples,
+        summary: ctx.summary,
+    };
+}
+/**
+ * Exported for tests. Returns a Promise<exit code>. Human-triggered
+ * retro-distill:
+ *   - assemble read-only signals → buildDistillContext
+ *   - --dry-run: print the summary + proposed changes; NO spawn, NO file writes
+ *   - else: gate check → spawn distiller → parse envelope → anchor-guard → draft
+ * NEVER writes src/daemon/templates/agents/.
+ */
+export async function runDistill(agent, opts, deps = {}) {
+    const log = deps.io?.log ?? ((m) => console.log(m));
+    const error = deps.io?.error ?? ((m) => console.error(m));
+    const name = (agent ?? '').trim();
+    if (!name) {
+        error('Error: an agent template name is required, e.g. cf agent distill coder --dry-run');
+        return 1;
+    }
+    const days = opts.days ? parseInt(opts.days, 10) : 30;
+    if (Number.isNaN(days) || days < 1 || days > 365) {
+        error('Error: --days must be between 1 and 365');
+        return 1;
+    }
+    const maxFailures = opts.maxFailures ? parseInt(opts.maxFailures, 10) : 5;
+    if (Number.isNaN(maxFailures) || maxFailures < 0 || maxFailures > 50) {
+        error('Error: --max-failures must be between 0 and 50');
+        return 1;
+    }
+    const templatesDir = deps.templatesDir ?? resolveAgentTemplatesDir();
+    const templatePath = join(templatesDir, `${name}.md`);
+    if (!existsSync(templatePath)) {
+        error(`Error: no agent template found at ${templatePath}`);
+        return 1;
+    }
+    const currentTemplate = readFileSync(templatePath, 'utf-8');
+    const currentVersion = readTemplateVersion(currentTemplate);
+    const ownStorage = !deps.storage;
+    let storage;
+    try {
+        storage = deps.storage ?? new SQLiteStorage(FORGE_PATHS.database());
+    }
+    catch (err) {
+        error(`Error: cannot open storage: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    try {
+        // Assemble the read-only signal context via the shared web-callable helper
+        // (decision 568a8c53 — mechanical extraction; CLI behaviour unchanged).
+        const { ctx, drift, health, failureSamples } = buildAgentDistillContextFor(name, {
+            storage,
+            templatesDir,
+            days,
+            maxFailures,
+        });
+        // ── --dry-run: print summary + proposed changes; no spawn, no writes. ────
+        if (opts.dryRun) {
+            if (opts.json) {
+                log(JSON.stringify({
+                    agent: name,
+                    current_version: currentVersion,
+                    maturity: ctx.maturity,
+                    enough_signal: ctx.enoughSignal,
+                    insufficient_reason: ctx.insufficientReason,
+                    proposed_change_types: ctx.proposedChangeTypes,
+                    drift,
+                    recommended_skills: health?.recommended_skills ?? [],
+                    failure_samples: failureSamples,
+                }, null, 2));
+            }
+            else {
+                log(ctx.summary);
+            }
+            return 0;
+        }
+        // ── Real spawn path — gate first (门槛 1). ────────────────────────────────
+        if (!ctx.enoughSignal) {
+            log(ctx.insufficientReason ?? '数据不足，未产改进草案。');
+            return 0; // honest degradation, NOT an error
+        }
+        const spawnFn = deps.spawn ?? ((p) => spawnAgentRetroDistiller(p));
+        let raw;
+        try {
+            raw = await spawnFn(ctx.prompt);
+        }
+        catch (err) {
+            error(`Error: distiller spawn failed: ${err instanceof Error ? err.message : String(err)}`);
+            return 1;
+        }
+        const envelope = parseAgentPatchEnvelope(raw);
+        if (envelope === null) {
+            error('Error: distiller output has no recognizable ---AGENT-PATCH--- or ---NOOP--- envelope; no draft written.');
+            return 1;
+        }
+        if (envelope.kind === 'noop') {
+            log(`distiller 判定无值得改的改动（NOOP）：${envelope.rationale}`);
+            return 0; // honest empty draft, NOT an error
+        }
+        // ── anchor-guard: reject any patch touching a protected region. ──────────
+        const violations = scanAgentPatch(envelope.patch);
+        if (violations.length > 0) {
+            error(`Error: distiller patch touches ${violations.length} protected region(s) — draft REJECTED, no file written:`);
+            for (const v of violations) {
+                error(`  - [${v.region}] patch line ${v.patchLine}: "${v.line}"`);
+            }
+            return 1; // no retry (mirrors skill distiller ProjectAnchorRejection)
+        }
+        // ── write the human-reviewed DRAFT (NEVER the template itself). ──────────
+        const today = new Date().toISOString().slice(0, 10);
+        const outBase = deps.outBaseDir ?? join(repoRootForDrafts(), 'docs', 'design');
+        const outDir = opts.out ?? join(outBase, today, 'agent-distill');
+        const targetVersion = envelope.targetVersion ?? currentVersion + 1;
+        const draftPath = join(outDir, `${name}-v${targetVersion}-draft.md`);
+        mkdirSync(outDir, { recursive: true });
+        writeFileSync(draftPath, renderDraft(name, currentVersion, targetVersion, ctx.maturity, envelope.rationale, envelope.patch), 'utf-8');
+        log(`草案已写入（人审，未落模板）：${draftPath}`);
+        log(`成熟度：${ctx.maturity}`);
+        return 0;
+    }
+    catch (err) {
+        error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    finally {
+        if (ownStorage) {
+            try {
+                storage.close();
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+/** Repo root for draft output (CLI cwd, where docs/ lives). */
+function repoRootForDrafts() {
+    return process.cwd();
+}
+/**
+ * Render the human-reviewed draft markdown (decision 234f1ad4). Exported so the
+ * web AgentDistillManager writes byte-identical drafts (decision 568a8c53).
+ */
+export function renderDraft(agent, currentVersion, targetVersion, maturity, rationale, patch) {
+    return [
+        `# Agent distill 草案: ${agent}  (v${currentVersion} → v${targetVersion})`,
+        '',
+        '> Decision: 234f1ad4',
+        `> 信号成熟度: ${maturity}`,
+        '> 这是 LLM 据真实使用信号起草的改进草案。**未自动落模板**——需人 review 批准后由 coder/人手动应用。',
+        '',
+        '## Rationale（每条改动引用的信号）',
+        '',
+        rationale,
+        '',
+        '## Patch（unified diff，仅供采纳时应用）',
+        '',
+        '```diff',
+        patch,
+        '```',
+        '',
+        '## 采纳步骤（人确认后）',
+        '',
+        `1. 人 review 本草案，确认 patch 只动可演进区。`,
+        `2. 把 patch 应用到 \`src/daemon/templates/agents/${agent}.md\`，frontmatter \`version: ${targetVersion}\`。`,
+        `3. 同步项目级副本 \`.claude/agents/${agent}.md\` 字节一致（不变量 75344363）。`,
+        `4. \`npm run build\` → \`cf agents sync\`。`,
+        `5. 跑不变量测试 \`tests/unit/daemon/agent-templates-decision-header.test.ts\` 绿。`,
+        `6. \`cf decisions outcome 234f1ad4 --result success --note "phase3 distill ${agent} v${targetVersion} adopted"\`。`,
+        '',
+    ].join('\n');
+}
+/**
+ * Exported for tests. Human-assisted rollback (decision 234f1ad4 Q4):
+ *   - default: print the vN draft path + suggested git ops (read-only).
+ *   - --write: write the historical git blob back to the src template, then
+ *     self-check the project-level copy is byte-identical (invariant 75344363).
+ *     Divergent copies → non-zero exit warning.
+ */
+export function runRollback(agent, opts, deps = {}) {
+    const log = deps.io?.log ?? ((m) => console.log(m));
+    const error = deps.io?.error ?? ((m) => console.error(m));
+    const name = (agent ?? '').trim();
+    if (!name) {
+        error('Error: an agent template name is required, e.g. cf agent rollback coder --to 1');
+        return 1;
+    }
+    const targetVersion = parseInt(opts.to, 10);
+    if (Number.isNaN(targetVersion) || targetVersion < 1) {
+        error('Error: --to must be a positive version number');
+        return 1;
+    }
+    const templatesDir = deps.templatesDir ?? resolveAgentTemplatesDir();
+    const templatePath = join(templatesDir, `${name}.md`);
+    if (!existsSync(templatePath)) {
+        error(`Error: no agent template found at ${templatePath}`);
+        return 1;
+    }
+    const currentVersion = readTemplateVersion(readFileSync(templatePath, 'utf-8'));
+    const relTemplate = `src/daemon/templates/agents/${name}.md`;
+    const installedDir = deps.installedDir ?? join(process.cwd(), '.claude', 'agents');
+    const installedPath = join(installedDir, `${name}.md`);
+    if (!opts.write) {
+        // Read-only human-assist: print guidance.
+        log(`# Agent rollback (人工辅助): ${name}  当前 version=${currentVersion} → 目标 v${targetVersion}`);
+        log('');
+        log(`草案档（v${targetVersion} 的「为什么改」）应在: docs/design/**/agent-distill/${name}-v${targetVersion}-draft.md`);
+        log('');
+        log('建议的 git 操作（找出 v 对应的历史 commit）:');
+        log(`  git log --oneline -- ${relTemplate}`);
+        log(`  git show <ref>:${relTemplate}   # 预览历史内容`);
+        log('');
+        log(`确认无误后重跑带 --write 自动写回 + 字节一致性自检:`);
+        log(`  cf agent rollback ${name} --to ${targetVersion} --write`);
+        return 0;
+    }
+    // --write: write the historical git blob back, then self-check byte identity.
+    const reader = deps.readGitBlob ?? defaultReadGitBlob;
+    // Heuristic ref: the spec keeps history in git; we use the commit that last
+    // set the template to vN. Without a version→ref index we let git resolve the
+    // most recent ref whose blob carries `version: <N>` is out of scope here —
+    // instead --write requires the caller to have checked out / tagged the ref.
+    // We read the current HEAD blob and verify; tests inject readGitBlob.
+    let historical;
+    try {
+        historical = reader('HEAD', relTemplate);
+    }
+    catch (err) {
+        error(`Error: cannot read git blob for ${relTemplate}: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    const blobVersion = readTemplateVersion(historical);
+    if (blobVersion !== targetVersion) {
+        error(`Error: resolved git blob is version ${blobVersion}, not requested v${targetVersion}. ` +
+            `Check out the ref whose ${relTemplate} carries version: ${targetVersion}, then re-run.`);
+        return 1;
+    }
+    try {
+        writeFileSync(templatePath, historical, 'utf-8');
+        writeFileSync(installedPath, historical, 'utf-8');
+    }
+    catch (err) {
+        error(`Error: write-back failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    // Byte-identity self-check (invariant 75344363).
+    const src = readFileSync(templatePath, 'utf-8');
+    const installed = existsSync(installedPath) ? readFileSync(installedPath, 'utf-8') : '';
+    if (src !== installed) {
+        error(`Error: byte-identity self-check FAILED — ${templatePath} and ${installedPath} diverge. ` +
+            `Sync them manually + run the invariant test before committing.`);
+        return 1;
+    }
+    log(`已写回 v${targetVersion} 并自检通过：src 模板与项目级副本字节一致。`);
+    log(`后续: npm run build → cf agents sync → 跑不变量测试。`);
+    return 0;
+}
+function defaultReadGitBlob(ref, path) {
+    return execFileSync('git', ['show', `${ref}:${path}`], { encoding: 'utf-8' });
+}
+//# sourceMappingURL=agent.js.map