agent-trellis 0.19.0 → 0.20.0

package/dist/evolve/jobMain.js

@@ -0,0 +1,52 @@
+/**
+ * 一次性 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` 取)。
+ */
+import { runJobShell } from "./jobShell.js";
+const TRIGGER_KINDS = ["event", "manual", "chain"];
+const argv = process.argv.slice(2);
+let holdMs = 0;
+const holdIdx = argv.indexOf("--hold-ms");
+if (holdIdx !== -1) {
+    holdMs = Number(argv[holdIdx + 1] ?? 0);
+    argv.splice(holdIdx, 2);
+}
+let trigger = "event";
+const triggerIdx = argv.indexOf("--trigger");
+if (triggerIdx !== -1) {
+    const raw = argv[triggerIdx + 1];
+    if (raw === undefined || !TRIGGER_KINDS.includes(raw)) {
+        console.error(`jobMain: --trigger 必须是 ${TRIGGER_KINDS.join(" | ")}`);
+        process.exit(2);
+    }
+    trigger = raw;
+    argv.splice(triggerIdx, 2);
+}
+const homeDir = argv[argv.length - 1];
+if (homeDir === undefined || homeDir === "") {
+    console.error("jobMain: 用法 node jobMain.js [--hold-ms N] [--trigger event|manual|chain] <homeDir>");
+    process.exit(2);
+}
+const result = await runJobShell(homeDir, { trigger, holdMs });
+if (result.status === "error") {
+    console.error(`jobMain: 作业体失败:${result.message}`);
+    process.exitCode = 1;
+}
+// lock-busy:静默退出 0(竞态窗口已有作业在跑,不排队)。

package/dist/evolve/jobRun.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 一次性作业的作业体(trellis-evolve 任务 11.5;14.1 fixture E2E 的流水
+ * 在此落地为生产入口)。作业体是下述 rule-based 治理流水;引擎内核
+ * (packages/evolve-engine 的 schedule/recursion/proposer/selection/judge)
+ * golden 锚定但生产未经此消费,待 L2/探针任务集接入(review-fixes 纠偏
+ * 旧注"作业即运行移植引擎"的名不副实)。
+ *
+ * 流水(顺序即依赖,与 fixtureE2e 同链):
+ *   0. 级别闸:没有任何 propose/auto-A 设置 → 零副作用返回(触发器只在
+ *      propose+ 拉起;这里是直接 spawn 的防御)。
+ *   1. 可选源探测(11.3):agent-bridge 缺席记 unavailable,不失败。
+ *   2. 信号合并(自上次作业的信号合并时刻以来;首次为全部,11.5"未
+ *      消费"语义)。
+ *   3. 检查发现:全局 + 信号层归属出现过/级别策略声明过的 workspace,
+ *      各自 `runChecks`(L1 的 doctor oracle)。观察面即发现面——只有
+ *      进过信号/策略的 workspace 会被扫描(与"信号是观察记录"一致)。
+ *   4. 提案草稿:rule-based 通道——`proposeFromSignals` 的信号对齐路径
+ *      ∪ 当前发现直接 `ruleBasedProposal`(同一内核、提案 id 同源
+ *      `rule-<findingId>` 天然去重;已入 pending 的跳过)。editor/spawn
+ *      通道(design D7)在 `runDelegatedCall` 就绪前不在作业里拉真实
+ *      CLI 会话,见 `ProposalChannelAvailability` 注释。
+ *   5. 逐草稿治理:域分派(配置类才进通道)→ 机械校验(无 editor 不
+ *      重试)→ L1 前闸(verdict 差集,唯一 verdict)→ 风险分类(不采信
+ *      自报)→ 采纳门(A 仅 auto-A 且闸通过自动采纳并通知;B 永远待批)。
+ *      草稿的提案/采纳级别按其目标层解析(workspace > default;agent
+ *      粒度只闸观察与触发,不进提案产出——提案的来源 agent 不可考,
+ *      发现是 doctor 检查面而非 agent 行为)。
+ *   6. 应用阶段(12.5):全部已批准未应用的编辑在同一备份会话写入;
+ *      按 delivery 分类对原生渲染 agent 触发同步(host 门面 `triggerRenderSync`)。
+ *   7. lesson(12.6):本次应用的每条提案蒸馏一条 lesson;记忆启用走
+ *      记忆管道,否则只留档案(skipped 不是 failed)。
+ *
+ * 每步都只经 `src/host/*` 门面与本目录模块(边界 10.3);无模型调用、
+ * 不 spawn 真实 agent CLI。摘要返回给 jobMain 并入 job-run 档案。
+ */
+import type { CheckEntry } from "../host/index.js";
+import { type EvolveLevelPolicy } from "../host/index.js";
+import { type AgentEffectiveness, type ApplyAgent } from "./apply.js";
+import { type EvaluateL1Options, type L1GateResult } from "./gate.js";
+import { type OptionalSourceProbe } from "./sources.js";
+import type { Proposal, Signal } from "./types.js";
+/** 草稿来源的输入面(proposeFn 注入缝的契约)。 */
+export interface ProposeInput {
+    readonly homeDir: string;
+    readonly signals: readonly Signal[];
+    readonly findings: readonly CheckEntry[];
+    readonly now: () => number;
+}
+export interface RunEvolveJobOptions {
+    /** 时间源(毫秒);缺省 Date.now(测试注入固定时钟)。 */
+    readonly now?: () => number;
+    /** 草稿来源注入缝(测试直达治理层);缺省 rule-based 通道组装。 */
+    readonly proposeFn?: (input: ProposeInput) => readonly Proposal[];
+    /** L1 前闸注入缝(与 `EvaluateL1Options` 自带缝同风格);缺省真实闸。 */
+    readonly evaluateL1Fn?: (options: EvaluateL1Options) => Promise<L1GateResult>;
+    /** 应用阶段的 agent 分类(测试传空避开真实同步);缺省按 delivery 分类。 */
+    readonly applyAgents?: readonly ApplyAgent[];
+    /** 原生渲染同步触发缝;缺省 host `triggerRenderSync`。 */
+    readonly triggerSync?: () => Promise<{
+        exitCode: number;
+    }>;
+}
+export interface EvolveJobSummary {
+    readonly signalsConsidered: number;
+    readonly findingsConsidered: number;
+    readonly draftCount: number;
+    readonly enqueuedIds: string[];
+    readonly autoAdoptedIds: string[];
+    readonly discarded: readonly {
+        readonly id: string;
+        readonly code: string;
+        readonly reason: string;
+    }[];
+    readonly skippedNotes: readonly string[];
+    readonly applied: {
+        readonly runId: string | null;
+        readonly appliedProposalIds: readonly string[];
+        readonly syncExitCode: number | null;
+        /** 同步触发失败文本(收口为效果文本);无为 null。 */
+        readonly syncError: string | null;
+        /** 逐 agent 生效时点(review-fixes ❌3:随 job-run 档案入档)。 */
+        readonly effects: readonly AgentEffectiveness[];
+    };
+    readonly lessonIds: string[];
+    readonly notices: string[];
+    readonly optionalSources: readonly OptionalSourceProbe[];
+    /** 信号合并时刻(步骤 2 的 now());job-run 档案据此推进消费水位线,
+     * 作业运行期间到达的信号下次仍被消费。级别闸早退为 null(未合并)。 */
+    readonly signalsMergedAtMs: number | null;
+}
+/** 作业级闸:任一粒度出现 propose/auto-A 才值得运行(observe 只采集)。
+ * `trellis evolve run` 的早退判定与作业体同源(1.3)。 */
+export declare function anyProposalLevel(policy: EvolveLevelPolicy): boolean;
+export declare function runEvolveJob(homeDir: string, options?: RunEvolveJobOptions): Promise<EvolveJobSummary>;

package/dist/evolve/jobRun.js

@@ -0,0 +1,273 @@
+/**
+ * 一次性作业的作业体(trellis-evolve 任务 11.5;14.1 fixture E2E 的流水
+ * 在此落地为生产入口)。作业体是下述 rule-based 治理流水;引擎内核
+ * (packages/evolve-engine 的 schedule/recursion/proposer/selection/judge)
+ * golden 锚定但生产未经此消费,待 L2/探针任务集接入(review-fixes 纠偏
+ * 旧注"作业即运行移植引擎"的名不副实)。
+ *
+ * 流水(顺序即依赖,与 fixtureE2e 同链):
+ *   0. 级别闸:没有任何 propose/auto-A 设置 → 零副作用返回(触发器只在
+ *      propose+ 拉起;这里是直接 spawn 的防御)。
+ *   1. 可选源探测(11.3):agent-bridge 缺席记 unavailable,不失败。
+ *   2. 信号合并(自上次作业的信号合并时刻以来;首次为全部,11.5"未
+ *      消费"语义)。
+ *   3. 检查发现:全局 + 信号层归属出现过/级别策略声明过的 workspace,
+ *      各自 `runChecks`(L1 的 doctor oracle)。观察面即发现面——只有
+ *      进过信号/策略的 workspace 会被扫描(与"信号是观察记录"一致)。
+ *   4. 提案草稿:rule-based 通道——`proposeFromSignals` 的信号对齐路径
+ *      ∪ 当前发现直接 `ruleBasedProposal`(同一内核、提案 id 同源
+ *      `rule-<findingId>` 天然去重;已入 pending 的跳过)。editor/spawn
+ *      通道(design D7)在 `runDelegatedCall` 就绪前不在作业里拉真实
+ *      CLI 会话,见 `ProposalChannelAvailability` 注释。
+ *   5. 逐草稿治理:域分派(配置类才进通道)→ 机械校验(无 editor 不
+ *      重试)→ L1 前闸(verdict 差集,唯一 verdict)→ 风险分类(不采信
+ *      自报)→ 采纳门(A 仅 auto-A 且闸通过自动采纳并通知;B 永远待批)。
+ *      草稿的提案/采纳级别按其目标层解析(workspace > default;agent
+ *      粒度只闸观察与触发,不进提案产出——提案的来源 agent 不可考,
+ *      发现是 doctor 检查面而非 agent 行为)。
+ *   6. 应用阶段(12.5):全部已批准未应用的编辑在同一备份会话写入;
+ *      按 delivery 分类对原生渲染 agent 触发同步(host 门面 `triggerRenderSync`)。
+ *   7. lesson(12.6):本次应用的每条提案蒸馏一条 lesson;记忆启用走
+ *      记忆管道,否则只留档案(skipped 不是 failed)。
+ *
+ * 每步都只经 `src/host/*` 门面与本目录模块(边界 10.3);无模型调用、
+ * 不 spawn 真实 agent CLI。摘要返回给 jobMain 并入 job-run 档案。
+ */
+import { classifyManagedObservation, isMemoryDeliveryEnabled, loadEvolveLevelPolicy, resolveEvolveLevel, runChecks, triggerRenderSync, } from "../host/index.js";
+import { appendArchiveRecord, readArchiveRecords } from "./archive.js";
+import { applyApprovedProposals } from "./apply.js";
+import { dispatchProposalDomain, evaluateL1Proposal } from "./gate.js";
+import { recordLesson } from "./lesson.js";
+import { decideProposal, enqueueProposal, readPendingRecord, readPendingRecords, safeProposalFileName, } from "./pending.js";
+import { proposeFromSignals, ruleBasedProposal } from "./propose.js";
+import { readAllSignals } from "./recorder.js";
+import { classifyProposalRisk, evaluateAdoptionGate, retargetNotificationRollback } from "./risk.js";
+import { probeAgentBridgeSource } from "./sources.js";
+import { PROPOSAL_ARCHIVE_KIND, lastSignalWatermarkMs, } from "./trigger.js";
+import { validateProposalWithRetry } from "./validate.js";
+/** 作业级闸:任一粒度出现 propose/auto-A 才值得运行(observe 只采集)。
+ * `trellis evolve run` 的早退判定与作业体同源(1.3)。 */
+export function anyProposalLevel(policy) {
+    const levels = [
+        policy.defaultLevel,
+        ...Object.values(policy.agents),
+        ...Object.values(policy.workspaces),
+    ];
+    return levels.some((level) => level === "propose" || level === "auto-A");
+}
+/** 草稿目标层的生效级别(workspace > agent > default > off)。 */
+function draftLevel(policy, layer) {
+    return resolveEvolveLevel(policy, layer.kind === "workspace" ? { workspaceRoot: layer.root } : {});
+}
+/** 缺省草稿组装:信号对齐 ∪ 当前发现直提,id 同源去重。 */
+function defaultPropose(input) {
+    // editor/spawn 通道就绪前,生产走 rule-based 兜底(design D7:委派不可
+    // 用时 doctor finding 形态信号走 rule-based)。ruleBasedProposal 是
+    // proposeFromSignals 的同一内核;这里补上"无对齐信号但发现仍在"的条目
+    // ——发现由作业的 runChecks 观察(9.4①:doctor/sync 检查即原生渲染
+    // agent 的信号来源),生产信号面里事件信号 stableId 恒为 null。
+    const loop = proposeFromSignals({
+        signals: input.signals,
+        findings: input.findings,
+        availability: { delegate: false, spawn: false },
+        now: input.now,
+    });
+    const drafts = [...loop.proposals];
+    const covered = new Set(drafts.map((draft) => draft.id));
+    for (const entry of input.findings) {
+        const draft = ruleBasedProposal(entry, { now: input.now });
+        if (draft === null || covered.has(draft.id))
+            continue;
+        covered.add(draft.id);
+        drafts.push(draft);
+    }
+    return drafts;
+}
+/** 上一作业的信号水位线(优先"信号合并时刻",旧档案回退 endedAtMs);
+ * 从未跑过为 null。 */
+function lastSignalWatermark(homeDir) {
+    return lastSignalWatermarkMs(readArchiveRecords(homeDir));
+}
+export async function runEvolveJob(homeDir, options = {}) {
+    const now = options.now ?? Date.now;
+    const empty = {
+        signalsConsidered: 0,
+        findingsConsidered: 0,
+        draftCount: 0,
+        enqueuedIds: [],
+        autoAdoptedIds: [],
+        discarded: [],
+        skippedNotes: [],
+        applied: { runId: null, appliedProposalIds: [], syncExitCode: null, syncError: null, effects: [] },
+        lessonIds: [],
+        notices: [],
+        optionalSources: [],
+        signalsMergedAtMs: null,
+    };
+    // ── 0. 级别闸 ─────────────────────────────────────────────────────────
+    const policy = loadEvolveLevelPolicy(homeDir);
+    if (!anyProposalLevel(policy))
+        return empty;
+    // ── 1. 可选源探测(缺席合法,记状态不失败)────────────────────────────
+    const optionalSources = [probeAgentBridgeSource(homeDir)];
+    // ── 2. 信号合并(自上次作业的信号水位线以来)────────────────────────
+    const signalsMergedAtMs = now();
+    const signals = readAllSignals(homeDir, lastSignalWatermark(homeDir));
+    // ── 3. 检查发现(全局 + 观察面内的 workspace)────────────────────────
+    const workspaceRoots = new Set();
+    for (const signal of signals) {
+        if (signal.layer.kind === "workspace")
+            workspaceRoots.add(signal.layer.root);
+    }
+    for (const root of Object.keys(policy.workspaces))
+        workspaceRoots.add(root);
+    const findingsById = new Map();
+    const runOne = async (runOptions) => {
+        const result = await runChecks(runOptions);
+        for (const entry of result.entries)
+            findingsById.set(entry.id, entry);
+    };
+    await runOne({ homeDir });
+    for (const root of workspaceRoots)
+        await runOne({ homeDir, workspaceRoot: root });
+    const findings = [...findingsById.values()];
+    // ── 4. 提案草稿 ───────────────────────────────────────────────────────
+    const proposeFn = options.proposeFn ?? defaultPropose;
+    const drafts = proposeFn({ homeDir, signals, findings, now });
+    // ── 5. 逐草稿治理 ─────────────────────────────────────────────────────
+    const enqueuedIds = [];
+    const autoAdoptedIds = [];
+    const discarded = [];
+    const skippedNotes = [];
+    const notices = [];
+    // 自动采纳通知先收集、应用后定稿:决策时备份会话尚不存在,回滚行只能
+    // 是泛化占位,拿到真实 runId 再重写(review-fixes ❌5)。
+    const adoptedNotifications = [];
+    const known = new Set(readPendingRecords(homeDir).map((record) => record.id));
+    for (const draft of drafts) {
+        if (known.has(draft.id)) {
+            skippedNotes.push(`${draft.id}:已有提案记录,不重复产出`);
+            continue;
+        }
+        const level = draftLevel(policy, draft.layer);
+        if (level !== "propose" && level !== "auto-A") {
+            skippedNotes.push(`${draft.id}:目标层级别 ${level},不产出提案`);
+            continue;
+        }
+        const domain = dispatchProposalDomain(draft.kind);
+        if (!domain.entersProposalChannel) {
+            skippedNotes.push(`${draft.id}:${domain.note}`);
+            continue;
+        }
+        const validated = await validateProposalWithRetry({ homeDir, proposal: draft, now });
+        if (validated.status === "discarded") {
+            discarded.push({ id: draft.id, code: validated.code, reason: validated.reason });
+            continue;
+        }
+        const proposal = validated.proposal;
+        const evaluateL1 = options.evaluateL1Fn ?? evaluateL1Proposal;
+        const gate = await evaluateL1({
+            homeDir,
+            workspaceRoot: proposal.layer.kind === "workspace" ? proposal.layer.root : null,
+            proposal,
+            now,
+        });
+        const classification = classifyProposalRisk(proposal, {
+            homeDir,
+            ...(validated.validation.needsExplicitApproval !== undefined
+                ? { needsExplicitApproval: validated.validation.needsExplicitApproval }
+                : {}),
+        });
+        const adoption = evaluateAdoptionGate({
+            level,
+            classification,
+            probePassed: gate.decision === "acceptable",
+            proposal,
+        });
+        if (gate.decision !== "acceptable") {
+            skippedNotes.push(`${proposal.id}:L1 前闸不可采纳(${gate.reason})`);
+            continue;
+        }
+        enqueueProposal({
+            homeDir,
+            proposal,
+            riskClass: classification.riskClass,
+            riskRuleId: classification.ruleId,
+            now,
+        });
+        appendArchiveRecord(homeDir, {
+            kind: PROPOSAL_ARCHIVE_KIND,
+            payload: { proposalId: proposal.id, riskClass: classification.riskClass, riskRuleId: classification.ruleId },
+        }, () => new Date(now()));
+        known.add(proposal.id);
+        if (adoption.action === "auto-adopt") {
+            decideProposal({ homeDir, id: proposal.id, decision: "approved", now });
+            autoAdoptedIds.push(proposal.id);
+            adoptedNotifications.push(adoption.notification);
+        }
+        else {
+            enqueuedIds.push(proposal.id);
+        }
+    }
+    // ── 6. 应用阶段(全部已批准未应用,同一备份会话)──────────────────────
+    const agents = options.applyAgents ?? classifyManagedObservation(homeDir).map((entry) => ({
+        agent: entry.agent,
+        observation: entry.observation,
+    }));
+    const triggerSync = options.triggerSync ?? (async () => await triggerRenderSync({ homeDir }));
+    const applied = await applyApprovedProposals({
+        homeDir,
+        agents,
+        triggerSync,
+        now: () => new Date(now()),
+    });
+    for (const id of applied.skippedInvalidIds) {
+        skippedNotes.push(`${id}:应用前重校验不通过(pending 磁盘状态漂移?),跳过`);
+    }
+    // 自动采纳通知定稿:回滚行重写为真实备份会话标识(应用失败/未开会话时
+    // 保留泛化占位——没有真实 runId 可指)。
+    for (const notification of adoptedNotifications) {
+        notices.push(applied.runId === null
+            ? notification.message
+            : retargetNotificationRollback(notification, `trellis evolve rollback ${applied.runId}`).message);
+    }
+    // ── 7. lesson(本次应用的每条提案蒸馏一条)───────────────────────────
+    const memoryEnabled = isMemoryDeliveryEnabled(homeDir);
+    const lessonIds = [];
+    for (const id of applied.appliedProposalIds) {
+        const record = readPendingRecord(homeDir, id);
+        if (record === null)
+            continue;
+        const lesson = {
+            id: `lesson-${safeProposalFileName(id)}`,
+            createdAt: now(),
+            cue: record.proposal.summary,
+            body: `应用阶段已写入备份会话 ${applied.runId ?? "?"}(风险 ${record.riskClass});` +
+                `编辑:${record.proposal.edits.map((edit) => `${edit.op} ${edit.path}`).join("; ")}(kind ${record.proposal.kind})。`,
+            evidence: record.proposal.evidence,
+            layer: record.proposal.layer,
+        };
+        recordLesson({ homeDir, lesson, memoryEnabled });
+        lessonIds.push(lesson.id);
+    }
+    return {
+        signalsConsidered: signals.length,
+        findingsConsidered: findings.length,
+        draftCount: drafts.length,
+        enqueuedIds,
+        autoAdoptedIds,
+        discarded,
+        skippedNotes,
+        applied: {
+            runId: applied.runId,
+            appliedProposalIds: applied.appliedProposalIds,
+            syncExitCode: applied.syncExitCode,
+            syncError: applied.syncError,
+            effects: applied.effects,
+        },
+        lessonIds,
+        notices,
+        optionalSources,
+        signalsMergedAtMs,
+    };
+}

package/dist/evolve/jobShell.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 作业壳(trellis-evolve-run-backfill 任务 1.1)。
+ *
+ * jobMain(detached 入口)与 `trellis evolve run`(前台手动触发)共享的
+ * 一次作业运行外壳:抢锁 → 跑作业体 → 落 job-run 档案 → 释锁,错误收口
+ * (失败也落档案——不落档案会让水位线与冷却都不推进,同一确定性错误在
+ * 每次会话结束被立即重拉成崩溃循环)。job-run payload 带 `trigger` 触发
+ * 来源(`event` / `manual` / `chain`);旧档案无该字段时消费端视作 `event`。
+ *
+ * 本模块只做壳:作业体在 `jobRun.js`(rule-based 治理流水),锁与档案
+ * 原语在 `trigger.js`。jobMain 仍是唯一 detached 入口(链起用),CLI
+ * 前台调用本壳即手动触发(D1:不另写执行路径)。
+ */
+import { type EvolveJobSummary } from "./jobRun.js";
+import { type JobTriggerKind, type TryLaunchJobOptions } from "./trigger.js";
+/** 触发来源(单一来源在 trigger.js;此处 re-export 保持壳类型面完整)。 */
+export type { JobTriggerKind } from "./trigger.js";
+export interface RunJobShellOptions {
+    /** 触发来源,入 job-run 档案。 */
+    readonly trigger: JobTriggerKind;
+    /** 持锁 N 毫秒后再跑作业体(jobMain `--hold-ms` 测试缝;生产不传)。 */
+    readonly holdMs?: number;
+    /** 时间源(毫秒);缺省 Date.now(测试注入固定时钟)。 */
+    readonly now?: () => number;
+    /** 补跑链起的作业命令/ spawn 注入缝(测试);缺省真实 jobMain 与 spawn。 */
+    readonly chainJobCommand?: TryLaunchJobOptions["jobCommand"];
+    readonly chainSpawnFn?: TryLaunchJobOptions["spawnFn"];
+}
+export type RunJobShellResult = 
+/** 抢锁失败:已有作业在跑(竞态窗口),不做任何工作、不排队。 */
+{
+    readonly status: "lock-busy";
+} | {
+    readonly status: "ok";
+    readonly summary: EvolveJobSummary;
+}
+/** 作业体抛错:job-run 档案已落 error 记录(推进冷却)。 */
+ | {
+    readonly status: "error";
+    readonly message: string;
+};
+/**
+ * 跑一次作业(壳语义):锁由本壳持有,收尾无论成败都释锁并落 job-run。
+ * lock-busy 时不落任何档案(一次根本没发生的运行不在档案说谎)。
+ */
+export declare function runJobShell(homeDir: string, options: RunJobShellOptions): Promise<RunJobShellResult>;

package/dist/evolve/jobShell.js

@@ -0,0 +1,75 @@
+/**
+ * 作业壳(trellis-evolve-run-backfill 任务 1.1)。
+ *
+ * jobMain(detached 入口)与 `trellis evolve run`(前台手动触发)共享的
+ * 一次作业运行外壳:抢锁 → 跑作业体 → 落 job-run 档案 → 释锁,错误收口
+ * (失败也落档案——不落档案会让水位线与冷却都不推进,同一确定性错误在
+ * 每次会话结束被立即重拉成崩溃循环)。job-run payload 带 `trigger` 触发
+ * 来源(`event` / `manual` / `chain`);旧档案无该字段时消费端视作 `event`。
+ *
+ * 本模块只做壳:作业体在 `jobRun.js`(rule-based 治理流水),锁与档案
+ * 原语在 `trigger.js`。jobMain 仍是唯一 detached 入口(链起用),CLI
+ * 前台调用本壳即手动触发(D1:不另写执行路径)。
+ */
+import { loadEvolveLevelPolicy } from "../host/index.js";
+import { appendArchiveRecord } from "./archive.js";
+import { runEvolveJob } from "./jobRun.js";
+import { acquireJobLock, chainAfterJob, consumeRunRequest, releaseJobLock, JOB_RUN_KIND, } from "./trigger.js";
+/**
+ * 跑一次作业(壳语义):锁由本壳持有,收尾无论成败都释锁并落 job-run。
+ * lock-busy 时不落任何档案(一次根本没发生的运行不在档案说谎)。
+ */
+export async function runJobShell(homeDir, options) {
+    const now = options.now ?? Date.now;
+    const pid = process.pid;
+    if (!acquireJobLock(homeDir, pid, now())) {
+        return { status: "lock-busy" };
+    }
+    // 任何作业启动即清补跑标记(D3:该请求已被本次运行满足)。
+    consumeRunRequest(homeDir);
+    const startedAtMs = now();
+    try {
+        if (options.holdMs !== undefined && options.holdMs > 0) {
+            await new Promise((resolve) => setTimeout(resolve, options.holdMs));
+        }
+        const summary = await runEvolveJob(homeDir, { now });
+        appendArchiveRecord(homeDir, {
+            kind: JOB_RUN_KIND,
+            payload: {
+                pid,
+                startedAtMs,
+                endedAtMs: now(),
+                trigger: options.trigger,
+                signalsMergedAtMs: summary.signalsMergedAtMs,
+                summary,
+            },
+        });
+        return { status: "ok", summary };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        try {
+            appendArchiveRecord(homeDir, {
+                kind: JOB_RUN_KIND,
+                payload: { pid, startedAtMs, endedAtMs: now(), trigger: options.trigger, error: message },
+            });
+        }
+        catch {
+            // 档案写入自身失败(如磁盘满)时不再连锁,锁仍由 finally 释放。
+        }
+        return { status: "error", message };
+    }
+    finally {
+        releaseJobLock(homeDir, pid);
+        // 收尾(释锁后)消费补跑标记并链起至多一次补跑(D3):运行期间到达的
+        // 请求塌缩为一个标记,在这里被消费;无标记不链。
+        const policy = loadEvolveLevelPolicy(homeDir);
+        chainAfterJob({
+            homeDir,
+            now,
+            ...(policy.trigger !== undefined ? { limits: policy.trigger } : {}),
+            ...(options.chainJobCommand !== undefined ? { jobCommand: options.chainJobCommand } : {}),
+            ...(options.chainSpawnFn !== undefined ? { spawnFn: options.chainSpawnFn } : {}),
+        });
+    }
+}

package/dist/evolve/l2.d.ts

@@ -0,0 +1,93 @@
+/**
+ * L2 匿名前后对比记录协议(trellis-evolve 任务 13.1)。
+ *
+ * spec"匿名前后对比记录协议(L2)":内容类对比的比较记录以类型化档案
+ * 格式持久化——baseline 与候选各自的运行标识、冻结的交付物引用、按
+ * 任务设种子的匿名标识映射、选择器结果与失败收口的 verdict;base 保留在
+ * 比较中;记录格式表达两种收口:选中 baseline ⟹ 不采纳,选择器失败 ⟹
+ * invalid。本模块只定义记录格式与边界;选择器执行(运行比较与裁决)不
+ * 在本期范围。
+ *
+ * 匿名性:呈现给选择器的匿名标识(anonId)由任务种子 + 运行标识派生,
+ * 本身不含角色词;选择器视图(`presentL2Arms`)只给 anonId 与冻结交付
+ * 物引用,不带 role/runId。角色映射只存在于档案(审计用)。
+ */
+import type { ArchiveEntry } from "./archive.js";
+/** 运行档案 kind:一条 L2 比较记录。 */
+export declare const L2_COMPARISON_ARCHIVE_KIND = "l2-comparison";
+export type L2ArmRole = "baseline" | "candidate";
+/** 冻结的交付物引用:标签 + 内容摘要键(切片任何变化即键变)。 */
+export interface L2FrozenArtifact {
+    readonly label: string;
+    readonly digest: string;
+}
+export interface L2Arm {
+    /** 种子派生的匿名标识(呈现面);不含角色词。 */
+    readonly anonId: string;
+    /** 该臂自己的运行标识。 */
+    readonly runId: string;
+    readonly role: L2ArmRole;
+    readonly artifacts: readonly L2FrozenArtifact[];
+}
+/** 按任务设种子:每条探针任务一个种子,匿名标识由此派生。 */
+export interface L2TaskSeed {
+    readonly task: string;
+    readonly seed: string;
+}
+export type L2SelectorResult = {
+    readonly status: "selected";
+    readonly anonId: string;
+} | {
+    readonly status: "failed";
+    readonly reason: string;
+};
+/** 失败收口的 verdict:
+ *   - selected baseline → not-adopted(不采纳);
+ *   - 选择器失败 / 任一臂未交付 → invalid(同样不采纳,收口形态不同)。 */
+export type L2Verdict = {
+    readonly kind: "adopt-candidate";
+    readonly anonId: string;
+} | {
+    readonly kind: "not-adopted-baseline";
+    readonly anonId: string;
+} | {
+    readonly kind: "invalid";
+    readonly reason: string;
+};
+export interface L2ComparisonRecord {
+    readonly comparisonId: string;
+    readonly createdAt: number;
+    readonly taskSeeds: readonly L2TaskSeed[];
+    /** baseline 与候选全在(base 留池,13.2 的偏差在引擎侧,记录层照存)。 */
+    readonly arms: readonly L2Arm[];
+    readonly selector: L2SelectorResult;
+    readonly verdict: L2Verdict;
+}
+/**
+ * 匿名标识:按任务种子 + 运行标识派生的稳定短哈希。构造上不可能
+ * 含角色词——呈现面与档案里的值同源,泄露面为零。
+ */
+export declare function anonArmId(taskSeeds: readonly L2TaskSeed[], runId: string): string;
+export interface BuildL2ComparisonInput {
+    readonly comparisonId: string;
+    readonly createdAt: number;
+    readonly taskSeeds: readonly L2TaskSeed[];
+    /** 每臂运行标识 + 角色 + 冻结交付物;anonId 由本函数派生。 */
+    readonly arms: readonly {
+        readonly runId: string;
+        readonly role: L2ArmRole;
+        readonly artifacts: readonly L2FrozenArtifact[];
+    }[];
+    readonly selector: L2SelectorResult;
+}
+/** 由臂与选择器结果构建完整记录(派生匿名映射 + 失败收口 verdict)。 */
+export declare function buildL2Comparison(input: BuildL2ComparisonInput): L2ComparisonRecord;
+/** 追加一条比较记录到运行档案。 */
+export declare function appendL2Comparison(homeDir: string, record: L2ComparisonRecord, now?: () => Date): ArchiveEntry;
+/** 读回全部比较记录(档案读取,零副作用)。 */
+export declare function readL2Comparisons(homeDir: string): L2ComparisonRecord[];
+/** 选择器视图:只给匿名标识与冻结交付物引用——不带 role/runId。 */
+export declare function presentL2Arms(record: L2ComparisonRecord): {
+    readonly anonId: string;
+    readonly artifacts: readonly L2FrozenArtifact[];
+}[];