agent-trellis 0.19.0 → 0.20.0

package/dist/evolve/gate.js

@@ -0,0 +1,295 @@
+/**
+ * L1 doctor-oracle 前闸(trellis-evolve 任务 12.1)。
+ *
+ * 两副职责:
+ *
+ * 1. **提案类域分派**:仅 `L1_CONFIG_KINDS` 白名单内的配置类提案进入
+ *    提案通道;内容类提案本期不产出(等 L2 选择器执行落地)。design D8
+ *    "L1 适用域的判定由 L4 治理层按 kind 白名单执行"——本模块就是该判定
+ *    点,12.2 的机械校验对提案 kind 的准入与此同源。
+ * 2. **确定性候选 verdict 差集**:对真实 baseline 与 staging 候选各运行
+ *    一组结构化检查(doctor findings、`sync --check`、secrets audit),
+ *    按 (稳定 id, 层归属) 集合差判定。在 L1 适用域内该差集是**唯一
+ *    verdict**,配置类提案不运行引擎评分链。
+ *
+ * 可采纳判据(design D8,从严):无新条目 ∧ 全部目标条目被消除 ∧ 其余
+ * 条目不变(未声明的消除也算变化)。目标条目 = 提案 evidence 中
+ * `doctor-finding` 链接的 `findingId`(即 CheckEntry.id);`Proposal.target`
+ * 本身是被编辑面的锚点(spec:"目标为某 MCP server auth 块"、"目标路径
+ * 位于某仓库的 .agents/ 内"),不是检查条目——两者职责分开,本闸只消费
+ * findingId。目标条目不在 baseline 时"无法确认修复",按不采纳收口。
+ *
+ * staging 复现层分裂:`createStaging` 拷 scratch 全局 HOME + 临时
+ * workspace root(墓碑生效),提案 edits 由本模块把真实面绝对路径重定位
+ * 到 scratch(越界不采纳);baseline 与候选都带 `logicalWorkspaceRoot`
+ * 归一化,条目比较键含层归属(`workspace(<root>)` 与全局不混)。
+ *
+ * 失败收口(Risks 8):staging/应用/测量任何意外错误一律"不采纳",
+ * 测量结果记 `unknown`(空条目集,绝不表示为零分或通过);域外提案同样
+ * 不采纳。全部判定都写入运行档案(kind `"verdict"`,含 baseline 与
+ * candidate 两份完整测量)。
+ */
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { appendArchiveRecord } from "./archive.js";
+import { applyEdits, createStaging, runChecks, } from "../host/index.js";
+/** 档案 kind:一次 L1 verdict(两份完整测量 + 判定原因)。 */
+export const VERDICT_ARCHIVE_KIND = "verdict";
+/**
+ * L1 适用域:配置类 kind 白名单(design D8)。名单内提案进入提案通道,
+ * L1 差集作唯一 verdict;名单外(含内容类——skill/记忆/指令正文等)本
+ * 期不产出提案,等 L2 选择器执行落地。命名与 12.2 rule-based/editor
+ * 提案的产出侧保持一致。
+ */
+export const L1_CONFIG_KINDS = new Set([
+    /** workspace 层配置面修复(如 `.codex/config.toml` 解析错误)。 */
+    "workspace-config-fix",
+    /** MCP 定义/路由等配置面修复(凭据字面值在校验阶段硬拒)。 */
+    "mcp-config-fix",
+    /** 托管投递面漂移修复(sync 可见面)。 */
+    "sync-config-fix",
+    /** secrets 策略配置修复(变量名/拒绝模式,不含任何凭据值)。 */
+    "secrets-policy-fix",
+    /** OAuth 配置元数据修复(kind/owner/client 元数据,不含凭据)。 */
+    "oauth-config-fix",
+]);
+/** 提案类域分派:白名单内 = 配置类(进通道),其余 = 内容类(不产出)。 */
+export function dispatchProposalDomain(kind) {
+    if (L1_CONFIG_KINDS.has(kind)) {
+        return {
+            domain: "config",
+            entersProposalChannel: true,
+            note: `kind "${kind}" 属配置类,进入提案通道(L1 差集为唯一 verdict)`,
+        };
+    }
+    return {
+        domain: "content",
+        entersProposalChannel: false,
+        note: `kind "${kind}" 不在配置类白名单,本期不产出提案(等 L2 选择器执行落地)`,
+    };
+}
+/**
+ * 条目比较键:(稳定 id, 层归属)。"条目 SHALL 带着层归属参与比较"——
+ * 同一 id 在全局层与 workspace 层是两条不同记录,不互相抵消。
+ */
+export function entryKey(entry) {
+    const layerKey = entry.layer.kind === "global" ? "global" : `workspace(${entry.layer.root})`;
+    return `${entry.id} ${layerKey}`;
+}
+/** 按 (id, layer) 做集合差;message 不参与比较(host/checks.ts 契约)。 */
+export function diffVerdictEntries(baseline, candidate) {
+    const baselineKeys = new Set(baseline.map(entryKey));
+    const candidateKeys = new Set(candidate.map(entryKey));
+    return {
+        introduced: candidate.filter((entry) => !baselineKeys.has(entryKey(entry))),
+        resolved: baseline.filter((entry) => !candidateKeys.has(entryKey(entry))),
+    };
+}
+/** 提案 evidence 中的目标条目(evidence 的 doctor-finding.findingId
+ * 即 CheckEntry.id;`Proposal.target` 是编辑面锚点,不在此列)。 */
+export function doctorFindingTargetIds(evidence) {
+    return evidence
+        .filter((link) => link.kind === "doctor-finding")
+        .map((link) => link.findingId);
+}
+function unknownVerdict(layer) {
+    return { status: "unknown", layer, baseline: [], candidate: [] };
+}
+/** `path` 是否落在某个真实面根之下(不含根本身)。 */
+function isInsideRoots(path, roots) {
+    const resolved = resolve(path);
+    for (const root of roots) {
+        if (!root)
+            continue;
+        const rel = relative(resolve(root), resolved);
+        if (rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))
+            return true;
+    }
+    return false;
+}
+/** 真实面绝对路径 → staging scratch 对应路径;越界抛错(不采纳)。
+ * workspace 根优先(可能嵌套在 HOME 下,与 checks 的归一化同序)。 */
+function relocateIntoStaging(path, ctx) {
+    const roots = [];
+    if (ctx.workspaceRoot && ctx.staging.workspaceRoot) {
+        roots.push({ real: ctx.workspaceRoot, scratch: ctx.staging.workspaceRoot });
+    }
+    roots.push({ real: ctx.homeDir, scratch: ctx.staging.homeDir });
+    const resolved = resolve(path);
+    for (const { real, scratch } of roots) {
+        if (!scratch)
+            continue;
+        const rel = relative(resolve(real), resolved);
+        if (rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel)) {
+            return join(scratch, rel);
+        }
+    }
+    throw new Error(`edit path escapes the measured surface: ${path}`);
+}
+/** 符号链接 target:落在真实面内才重定位到 scratch(链接不指向真实面);
+ * 相对路径与面外绝对路径保持原义(校验阶段的职责不在此)。 */
+function relocateTargetIfInside(target, ctx) {
+    if (!isAbsolute(target))
+        return target;
+    if (!isInsideRoots(target, [ctx.workspaceRoot, ctx.homeDir]))
+        return target;
+    return relocateIntoStaging(target, ctx);
+}
+function relocateEdits(edits, ctx) {
+    return edits.map((edit) => {
+        const path = relocateIntoStaging(edit.path, ctx);
+        switch (edit.op) {
+            case "write-file":
+            case "remove-symlink":
+                return { ...edit, path };
+            case "create-symlink":
+            case "repair-symlink":
+                return { ...edit, path, target: relocateTargetIfInside(edit.target, ctx) };
+        }
+    });
+}
+/**
+ * L1 前闸完整判定:域分派 → staging 副本(层分裂复现)→ edits 重定位并
+ * 应用 → baseline/候选各跑三组结构化检查 → (id, layer) 差集 → 判定并
+ * 入档。任何意外错误按"不采纳"收口、测量记 unknown;不吞掉入档写失败。
+ */
+export async function evaluateL1Proposal(options) {
+    const homeDir = options.homeDir;
+    const workspaceRoot = options.workspaceRoot ?? null;
+    const proposal = options.proposal;
+    const stamp = () => new Date((options.now ?? Date.now)());
+    const dispatch = dispatchProposalDomain(proposal.kind);
+    const settle = (outcome) => {
+        const result = {
+            decision: outcome.decision,
+            reason: outcome.reason,
+            domain: dispatch.domain,
+            verdict: outcome.verdict,
+            targetIds: outcome.targetIds,
+            introduced: outcome.introduced,
+            resolvedIds: outcome.resolvedIds,
+        };
+        // 两份 verdict 入档:baseline 与 candidate 完整条目集 + 判定原因。
+        appendArchiveRecord(homeDir, {
+            kind: VERDICT_ARCHIVE_KIND,
+            payload: {
+                proposalId: proposal.id,
+                kind: proposal.kind,
+                domain: dispatch.domain,
+                decision: outcome.decision,
+                reason: outcome.reason,
+                status: outcome.verdict.status,
+                layer: outcome.verdict.layer,
+                targetIds: outcome.targetIds,
+                introduced: outcome.introduced,
+                resolvedIds: outcome.resolvedIds,
+                baseline: outcome.verdict.baseline,
+                candidate: outcome.verdict.candidate,
+            },
+        }, stamp);
+        return result;
+    };
+    // 域分派:内容类本期不产出(等 L2)——不测量、不通过。
+    if (!dispatch.entersProposalChannel) {
+        return settle({
+            decision: "not-acceptable",
+            reason: dispatch.note,
+            verdict: unknownVerdict(proposal.layer),
+            targetIds: [],
+            introduced: [],
+            resolvedIds: [],
+        });
+    }
+    const targetIds = doctorFindingTargetIds(proposal.evidence);
+    if (targetIds.length === 0) {
+        return settle({
+            decision: "not-acceptable",
+            reason: "提案证据中没有 doctor-finding 目标条目,无法确认修复",
+            verdict: unknownVerdict(proposal.layer),
+            targetIds: [],
+            introduced: [],
+            resolvedIds: [],
+        });
+    }
+    const runChecksFn = options.runChecksFn ?? runChecks;
+    const createStagingFn = options.createStagingFn ?? createStaging;
+    const applyEditsFn = options.applyEditsFn ?? applyEdits;
+    let staging = null;
+    try {
+        staging = createStagingFn({ homeDir, workspaceRoot });
+        const edits = relocateEdits(proposal.edits, { homeDir, workspaceRoot, staging });
+        if (edits.length > 0) {
+            await applyEditsFn({ homeDir: staging.homeDir, edits, command: "evolve-l1-gate" });
+        }
+        // baseline:真实面;candidate:staging scratch。两侧都带
+        // logicalWorkspaceRoot 归一化,scratch 路径不进比较身份。
+        const baselineResult = await runChecksFn({
+            homeDir,
+            workspaceRoot,
+            logicalWorkspaceRoot: workspaceRoot,
+        });
+        const candidateResult = await runChecksFn({
+            homeDir: staging.homeDir,
+            workspaceRoot: staging.workspaceRoot,
+            logicalWorkspaceRoot: staging.logicalWorkspaceRoot,
+        });
+        const baseline = baselineResult.entries;
+        const candidate = candidateResult.entries;
+        const diff = diffVerdictEntries(baseline, candidate);
+        const targetIdSet = new Set(targetIds);
+        const baselineIds = new Set(baseline.map((entry) => entry.id));
+        const missingTargets = targetIds.filter((id) => !baselineIds.has(id));
+        const targetKeys = new Set(baseline.filter((entry) => targetIdSet.has(entry.id)).map(entryKey));
+        const resolvedKeys = new Set(diff.resolved.map(entryKey));
+        const resolvedIds = diff.resolved.map((entry) => entry.id);
+        const okVerdict = { status: "ok", layer: proposal.layer, baseline, candidate };
+        const common = { verdict: okVerdict, targetIds, introduced: diff.introduced, resolvedIds };
+        // 目标条目必须在 baseline 里——不在则"无法确认修复"。
+        if (missingTargets.length > 0) {
+            return settle({
+                ...common,
+                decision: "not-acceptable",
+                reason: `目标条目不在 baseline(${missingTargets.join(", ")}),无法确认修复`,
+            });
+        }
+        // 无新条目。
+        if (diff.introduced.length > 0) {
+            return settle({
+                ...common,
+                decision: "not-acceptable",
+                reason: `候选引入 ${diff.introduced.length} 个 baseline 中不存在的新条目`,
+            });
+        }
+        // 目标条目被消除 ∧ 其余不变(未声明的消除也算变化)。
+        const targetsAllResolved = [...targetKeys].every((key) => resolvedKeys.has(key));
+        const noExtraResolved = resolvedKeys.size === targetKeys.size && [...resolvedKeys].every((key) => targetKeys.has(key));
+        if (!targetsAllResolved) {
+            return settle({ ...common, decision: "not-acceptable", reason: "目标条目未被完全消除" });
+        }
+        if (!noExtraResolved) {
+            return settle({
+                ...common,
+                decision: "not-acceptable",
+                reason: "候选消除了未声明的条目,其余不满足不变约束",
+            });
+        }
+        return settle({
+            ...common,
+            decision: "acceptable",
+            reason: "候选消除全部目标条目,无新条目,其余不变",
+        });
+    }
+    catch (err) {
+        // Risks 8:意外错误一律不采纳,测量记 unknown,绝不表示为通过。
+        return settle({
+            decision: "not-acceptable",
+            reason: `测量/应用失败,按'不采纳'收口: ${err instanceof Error ? err.message : String(err)}`,
+            verdict: unknownVerdict(proposal.layer),
+            targetIds,
+            introduced: [],
+            resolvedIds: [],
+        });
+    }
+    finally {
+        staging?.dispose();
+    }
+}

package/dist/evolve/importHistory.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 历史数据导入与幂等回填(trellis-evolve-run-backfill 任务 3.1/3.2)。
+ *
+ * 把用户**显式选定**的既有 session 数据回填为观察信号,供后续作业按
+ * 既有水位线消费。设计(D4):
+ *   - 适配器契约 `{ name, sniff, extract }`,首个适配器 `claude-code-jsonl`
+ *     (Claude Code 会话 transcript JSONL);
+ *   - 白名单元数据:timestamp / agent / 会话 / 工具名 / 耗时 / 结果类别 /
+ *     层归属 —— 入参、结果载体与自由文本正文一律不入库(与 recorder 的
+ *     字段白名单同一条线);所有字符串字段写入前经 `eraseSecrets`;
+ *   - 台账幂等:`evolve/imports/<sha256(内容)>.json` 记源摘要与已导条目
+ *     数,同一源重复导入为空操作;stableId `import:<digest 前 12 位>:<行号>`
+ *     确定性(重复导入/重复消费不产生重复信号或重复提案);
+ *   - 写入复用 recorder 的批量 append(0600/0700、并发安全);整批先
+ *     extract 校验、后写入,任何源不可解析即非零退出且零写入。
+ *
+ * 字段缺省语义(格式缺字段时):ImportedEntry 对应字段记 null —— 耗时
+ * 缺省 0(白名单无 unknown 态),结果类别缺省 "ok"(无错误指示),agent
+ * 缺省适配器常量 "claude-code",会话缺省源文件名(D4"会话 id=文件名")。
+ * 无工具名的记录(文本轮次等)不写为 tool-call 信号,计入 skippedNoTool。
+ * 结果类别按记录自带 is_error 归类(每条记录独立映射);tool_use 与其
+ * tool_result 在 transcript 中是不同记录,跨记录关联留待适配器后续细化。
+ */
+/** 导入条目的白名单元数据(缺字段缺 null;写入侧按文档化缺省补全)。 */
+export interface ImportedEntry {
+    readonly timestampMs: number | null;
+    readonly agent: string | null;
+    readonly session: string | null;
+    readonly tool: string | null;
+    readonly durationMs: number | null;
+    readonly result: "ok" | "error" | "timeout" | null;
+}
+export interface ExtractedEntry {
+    /** 源文件物理行号(1 起):stableId 序号,确定性不受过滤影响。 */
+    readonly lineNo: number;
+    readonly entry: ImportedEntry;
+}
+export interface ExtractResult {
+    readonly entries: readonly ExtractedEntry[];
+    /** 无法解析的坏行数(跳过计数,与读取侧容错同源)。 */
+    readonly badLines: number;
+    /** 无工具名的记录数(文本轮次等,不写为 tool-call 信号)。 */
+    readonly skippedNoTool: number;
+}
+/** 源适配器契约:sniff 判定形态,extract 抽白名单元数据(不写盘)。 */
+export interface HistoryAdapter {
+    readonly name: string;
+    sniff(path: string): boolean;
+    extract(path: string): ExtractResult;
+}
+/** 源不可解析(不存在/不可读/不匹配任何适配器):整批零写入收口。 */
+export declare class ImportSourceError extends Error {
+    readonly path: string;
+    constructor(path: string, reason: string);
+}
+/** 首个适配器:Claude Code 会话 transcript(JSONL)。 */
+export declare const claudeCodeJsonlAdapter: HistoryAdapter;
+/** 已注册适配器(按序 sniff;契约先行,更多源后置)。 */
+export declare const HISTORY_ADAPTERS: readonly HistoryAdapter[];
+export interface ImportHistoryOptions {
+    readonly homeDir: string;
+    /** 显式选定的源路径(仅此处理;不扫描目录、不自动发现)。 */
+    readonly paths: readonly string[];
+    /** `--workspace` 层归属;缺省全局层。 */
+    readonly workspaceRoot?: string;
+    /** 时间源(毫秒);缺省 Date.now(采集时刻与台账打戳)。 */
+    readonly now?: () => number;
+}
+export interface ImportedSourceResult {
+    readonly path: string;
+    readonly sourceDigest: string;
+    /** 本次写入条目数(已记账源为 0)。 */
+    readonly entries: number;
+    readonly badLines: number;
+    readonly skippedNoTool: number;
+    /** 已记账源(重复导入为空操作)。 */
+    readonly duplicate: boolean;
+}
+export interface ImportHistoryResult {
+    readonly sources: readonly ImportedSourceResult[];
+    readonly written: number;
+    readonly signalFile: string | null;
+}
+/** 台账文件路径(按源内容摘要命名;内容变 = 新源)。 */
+export declare function importLedgerPath(homeDir: string, digest: string): string;
+/**
+ * 整批导入:先对全部源 sniff + extract 校验(任何源不可解析即抛
+ * `ImportSourceError`,零写入),后一次性写信号与台账(台账最后记账,
+ * 中断重跑安全:未记账则重导,提案去重兜底)。不触发任何作业。
+ */
+export declare function importHistory(options: ImportHistoryOptions): ImportHistoryResult;

package/dist/evolve/importHistory.js

@@ -0,0 +1,239 @@
+/**
+ * 历史数据导入与幂等回填(trellis-evolve-run-backfill 任务 3.1/3.2)。
+ *
+ * 把用户**显式选定**的既有 session 数据回填为观察信号,供后续作业按
+ * 既有水位线消费。设计(D4):
+ *   - 适配器契约 `{ name, sniff, extract }`,首个适配器 `claude-code-jsonl`
+ *     (Claude Code 会话 transcript JSONL);
+ *   - 白名单元数据:timestamp / agent / 会话 / 工具名 / 耗时 / 结果类别 /
+ *     层归属 —— 入参、结果载体与自由文本正文一律不入库(与 recorder 的
+ *     字段白名单同一条线);所有字符串字段写入前经 `eraseSecrets`;
+ *   - 台账幂等:`evolve/imports/<sha256(内容)>.json` 记源摘要与已导条目
+ *     数,同一源重复导入为空操作;stableId `import:<digest 前 12 位>:<行号>`
+ *     确定性(重复导入/重复消费不产生重复信号或重复提案);
+ *   - 写入复用 recorder 的批量 append(0600/0700、并发安全);整批先
+ *     extract 校验、后写入,任何源不可解析即非零退出且零写入。
+ *
+ * 字段缺省语义(格式缺字段时):ImportedEntry 对应字段记 null —— 耗时
+ * 缺省 0(白名单无 unknown 态),结果类别缺省 "ok"(无错误指示),agent
+ * 缺省适配器常量 "claude-code",会话缺省源文件名(D4"会话 id=文件名")。
+ * 无工具名的记录(文本轮次等)不写为 tool-call 信号,计入 skippedNoTool。
+ * 结果类别按记录自带 is_error 归类(每条记录独立映射);tool_use 与其
+ * tool_result 在 transcript 中是不同记录,跨记录关联留待适配器后续细化。
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { eraseSecrets } from "./erase.js";
+import { appendSignalLines, signalFilePath } from "./recorder.js";
+import { evolveStateDir } from "./stateDir.js";
+/** 源不可解析(不存在/不可读/不匹配任何适配器):整批零写入收口。 */
+export class ImportSourceError extends Error {
+    path;
+    constructor(path, reason) {
+        super(`历史源 ${path} 无法导入:${reason}`);
+        this.name = "ImportSourceError";
+        this.path = path;
+    }
+}
+function parseTimestamp(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const ms = Date.parse(raw);
+    return Number.isNaN(ms) ? null : ms;
+}
+/** 首个 tool_use 块的工具名(一条记录一元数据;多工具块取首个)。 */
+function firstToolName(record) {
+    const message = record.message;
+    const content = (message?.content ?? record.content);
+    if (Array.isArray(content)) {
+        for (const block of content) {
+            const b = block;
+            if (b.type === "tool_use" && typeof b.name === "string")
+                return b.name;
+            if (b.type === "tool_result" && typeof b.name === "string")
+                return b.name;
+        }
+    }
+    if (typeof record.tool === "string")
+        return record.tool;
+    if (typeof record.tool_name === "string")
+        return record.tool_name;
+    return null;
+}
+/** 记录自带的错误指示(顶层或内容块的 is_error);无指示为 null。 */
+function errorIndicator(record) {
+    let seen = typeof record.is_error === "boolean" ? record.is_error : null;
+    const message = record.message;
+    const content = (message?.content ?? record.content);
+    if (Array.isArray(content)) {
+        for (const block of content) {
+            const b = block;
+            if (typeof b.is_error === "boolean")
+                seen = seen === true || b.is_error;
+        }
+    }
+    return seen;
+}
+/** 首个适配器:Claude Code 会话 transcript(JSONL)。 */
+export const claudeCodeJsonlAdapter = {
+    name: "claude-code-jsonl",
+    sniff(path) {
+        if (!path.endsWith(".jsonl"))
+            return false;
+        try {
+            const first = readFileSync(path, "utf-8")
+                .split("\n")
+                .find((line) => line.trim() !== "");
+            if (first === undefined)
+                return false;
+            const record = JSON.parse(first);
+            return (typeof record === "object" &&
+                record !== null &&
+                ("type" in record || "sessionId" in record || "timestamp" in record || "uuid" in record));
+        }
+        catch {
+            return false;
+        }
+    },
+    extract(path) {
+        const text = readFileSync(path, "utf-8");
+        const stem = basename(path).replace(/\.jsonl$/, "");
+        const entries = [];
+        let badLines = 0;
+        let skippedNoTool = 0;
+        text.split("\n").forEach((line, index) => {
+            const trimmed = line.trim();
+            if (trimmed === "")
+                return;
+            let record;
+            try {
+                record = JSON.parse(trimmed);
+            }
+            catch {
+                badLines += 1;
+                return;
+            }
+            if (typeof record !== "object" || record === null) {
+                badLines += 1;
+                return;
+            }
+            const rec = record;
+            const tool = firstToolName(rec);
+            if (tool === null) {
+                skippedNoTool += 1;
+                return;
+            }
+            const isError = errorIndicator(rec);
+            entries.push({
+                lineNo: index + 1,
+                entry: {
+                    timestampMs: parseTimestamp(rec.timestamp),
+                    agent: null,
+                    session: stem,
+                    tool,
+                    durationMs: null,
+                    result: isError === null ? null : isError ? "error" : "ok",
+                },
+            });
+        });
+        return { entries, badLines, skippedNoTool };
+    },
+};
+/** 已注册适配器(按序 sniff;契约先行,更多源后置)。 */
+export const HISTORY_ADAPTERS = [claudeCodeJsonlAdapter];
+/** 台账文件路径(按源内容摘要命名;内容变 = 新源)。 */
+export function importLedgerPath(homeDir, digest) {
+    return join(evolveStateDir(homeDir), "imports", `${digest}.json`);
+}
+/**
+ * 整批导入:先对全部源 sniff + extract 校验(任何源不可解析即抛
+ * `ImportSourceError`,零写入),后一次性写信号与台账(台账最后记账,
+ * 中断重跑安全:未记账则重导,提案去重兜底)。不触发任何作业。
+ */
+export function importHistory(options) {
+    const now = options.now ?? Date.now;
+    const layer = options.workspaceRoot === undefined ? { kind: "global" } : { kind: "workspace", root: options.workspaceRoot };
+    const prepared = [];
+    const seenDigests = new Set();
+    const duplicates = new Map();
+    for (const path of options.paths) {
+        let content;
+        try {
+            content = readFileSync(path, "utf-8");
+        }
+        catch (err) {
+            throw new ImportSourceError(path, `不可读(${err instanceof Error ? err.message : String(err)})`);
+        }
+        const digest = createHash("sha256").update(content).digest("hex");
+        if (seenDigests.has(digest) || existsSync(importLedgerPath(options.homeDir, digest))) {
+            duplicates.set(path, {
+                path,
+                sourceDigest: digest,
+                entries: 0,
+                badLines: 0,
+                skippedNoTool: 0,
+                duplicate: true,
+            });
+            continue;
+        }
+        const adapter = HISTORY_ADAPTERS.find((candidate) => candidate.sniff(path));
+        if (adapter === undefined) {
+            throw new ImportSourceError(path, "不匹配任何已注册适配器(当前支持 Claude Code 会话 JSONL)");
+        }
+        seenDigests.add(digest);
+        prepared.push({ path, digest, extracted: adapter.extract(path) });
+    }
+    // ---- 阶段 2:写入(信号批量 append,台账最后记账) ----
+    const nowMs = now();
+    const allSignals = [];
+    const sources = [];
+    for (const item of prepared) {
+        const signals = [];
+        for (const { lineNo, entry } of item.extracted.entries) {
+            signals.push({
+                kind: "tool-call",
+                source: "history-import",
+                stableId: `import:${item.digest.slice(0, 12)}:${lineNo}`,
+                collectedAt: nowMs,
+                layer,
+                ts: entry.timestampMs ?? nowMs,
+                agent: eraseSecrets(entry.agent ?? "claude-code"),
+                session: eraseSecrets(entry.session ?? basename(item.path).replace(/\.jsonl$/, "")),
+                provider: eraseSecrets("claude-code"),
+                tool: eraseSecrets(entry.tool ?? "unknown"),
+                durationMs: entry.durationMs ?? 0,
+                result: entry.result ?? "ok",
+            });
+        }
+        allSignals.push(...signals);
+        sources.push({
+            path: item.path,
+            sourceDigest: item.digest,
+            entries: signals.length,
+            badLines: item.extracted.badLines,
+            skippedNoTool: item.extracted.skippedNoTool,
+            duplicate: false,
+        });
+    }
+    let signalFile = null;
+    if (allSignals.length > 0) {
+        signalFile = signalFilePath(options.homeDir, nowMs);
+        appendSignalLines(signalFile, allSignals);
+    }
+    for (const source of sources) {
+        const ledgerPath = importLedgerPath(options.homeDir, source.sourceDigest);
+        mkdirSync(dirname(ledgerPath), { recursive: true, mode: 0o700 });
+        writeFileSync(ledgerPath, `${JSON.stringify({
+            sourceDigest: source.sourceDigest,
+            entries: source.entries,
+            importedAtMs: nowMs,
+            layer,
+        }, null, 2)}\n`, { mode: 0o600 });
+    }
+    return {
+        sources: [...sources, ...duplicates.values()],
+        written: allSignals.length,
+        signalFile,
+    };
+}

package/dist/evolve/jobMain.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 一次性 detached 作业入口(trellis-evolve 任务 11.5)。
+ *
+ * 契约:argv = [--hold-ms N] [--trigger event|manual|chain] <homeDir>。
+ * `--hold-ms`(持有锁 N 毫秒后再收尾,供集成测试观察"作业运行中"的锁
+ * 状态;生产不传,作业即时完成)。`--trigger` 记录触发来源入 job-run
+ * 档案(缺省 event;chain 为补跑链起,run-backfill D3)。锁由作业自身
+ * 持有(拉起方 spawn 前只做活锁检查,本入口再权威抢一次以防并发双拉起
+ * 竞态,抢不到立即退出、不做任何工作、不排队)。壳语义(抢锁/释放、
+ * job-run 落档含 trigger 字段、错误收口)在 `jobShell.js`——`trellis
+ * evolve run` 前台手动触发走同一壳(D1 不另写执行路径)。作业体是
+ * rule-based 治理流水的一次运行:`runEvolveJob`(信号 → rule-based
+ * 提案 → 机械校验 → L1 前闸 → 风险/采纳门 → 应用 → lesson,14.1 的
+ * fixture E2E 同链)。引擎内核(packages/evolve-engine 的
+ * schedule/recursion/proposer/selection/judge)golden 锚定但生产未经
+ * 此消费,待 L2/探针任务集接入。级别 off/observe 时作业体零副作用早退。
+ *
+ * 注意:本文件是入口脚本,被 import 时顶层即执行;测试只应 spawn 它,
+ * 不应 import(需要锁原语请从 `trigger.js` 取,作业壳从 `jobShell.js`
+ * 取,作业体从 `jobRun.js` 取)。
+ */
+export {};