agent-trellis 0.19.0 → 0.21.0

package/dist/host/levels.d.ts

@@ -0,0 +1,106 @@
+/**
+ * 分级开启的级别策略(trellis-evolve 任务 10.2)。
+ *
+ * 级别配置是用户的显式选择,写入 canonical 的 `~/.trellis/evolve.yaml`
+ * (与 scope.yaml / secrets.policy.yaml 同级的根级策略文件;与 `evolve/`
+ * 运行状态目录刻意分开 —— 后者是只追加的运行记录,见任务 8.1)。格式、
+ * 校验与解析归 host:canonical 配置的解析是托管的职责,且 doctor(托管
+ * 命令)与自我进化消费者(`src/evolve/`,只允许 import `src/host/*`)必须
+ * 对同一份格式与解析规则达成一致 —— `src/host/` 是二者之间唯一合法的
+ * 共享缝(10.3 的边界)。卸载自我进化后本模块仍然自洽:文件不存在即
+ * 全部为 `off`,doctor 不出现该段。
+ *
+ * 文件形态(snake_case,沿用 servers.yaml 惯例):
+ *
+ * ```yaml
+ * default_level: observe
+ * agents:
+ *   claude-code: propose
+ * workspaces:
+ *   /abs/path/ws-a: off
+ * ```
+ *
+ * 解析优先级(更具体覆盖更宽泛):workspace > agent > default_level > `off`。
+ * 值白名单即 `LEVELS` 四级;present-but-invalid 一律硬错误,绝不静默误读。
+ * 读取零副作用:本模块永不创建文件或目录;写入只经 `writeEvolveLevelPolicy`
+ * (12.4 的 enable/disable 管理命令调用),从不静默开启。
+ */
+/** 分级开启的四级,从关闭到最激进,有序(开启判定按此序)。 */
+export declare const LEVELS: readonly ["off", "observe", "propose", "auto-A"];
+export type Level = (typeof LEVELS)[number];
+/** 显式级别策略。缺省的键即"未设置",向更宽泛的粒度回退。 */
+export interface EvolveLevelPolicy {
+    /** 全局默认级别;未设置时回退为 `off`。 */
+    readonly defaultLevel?: Level;
+    /** per-agent 覆盖(agent 标识 → 级别)。 */
+    readonly agents: Readonly<Record<string, Level>>;
+    /** per-workspace 覆盖(绝对 workspace root 路径 → 级别)。 */
+    readonly workspaces: Readonly<Record<string, Level>>;
+    /** 触发/预算上限(trellis-evolve 任务 11.5,spec"可配置");缺省键
+     * 由触发器回退到内置缺省值。全部为非负整数。 */
+    readonly trigger?: EvolveTriggerLimits;
+}
+/** `evolve.yaml` 的 `trigger:` 段(单位见字段注释;缺省值见 evolve 侧
+ * `DEFAULT_TRIGGER_LIMITS`)。 */
+export interface EvolveTriggerLimits {
+    /** 累计未消费信号数阈值,达到即考虑拉起作业。 */
+    readonly signalThreshold?: number;
+    /** 冷却期(分钟):上一作业结束后此时间内不再拉起。 */
+    readonly cooldownMinutes?: number;
+    /** 每日提案上限:当日提案数达到即跳过并记录原因。 */
+    readonly dailyProposalCap?: number;
+    /** 委派 editor 每日预算上限(调用次数)。 */
+    readonly editorBudget?: number;
+}
+/**
+ * 观测形态(trellis-evolve 任务 11.4):该 agent 的进化信号来源。
+ * `events` = gateway 事件观察(runtime 交付);`doctor-only` = 只有
+ * doctor/sync 信号(仅原生渲染,无事件面)。由调用方按 capability
+ * delivery 计算,本模块不读 MCP 配置。
+ */
+export type EvolveObservation = "events" | "doctor-only";
+/** doctor 展示形态:各 agent 的生效级别与观测形态 + 显式 workspace 覆盖。 */
+export interface EvolveLevelSection {
+    readonly defaultLevel?: Level;
+    readonly agents: readonly {
+        readonly agent: string;
+        readonly level: Level;
+        readonly observation: EvolveObservation;
+    }[];
+    readonly workspaces: readonly {
+        readonly root: string;
+        readonly level: Level;
+    }[];
+    readonly diagnostics: readonly string[];
+}
+export declare function evolveLevelPolicyPath(homeDir: string): string;
+/**
+ * 读取级别策略。文件不存在 = 从未开启,返回空策略(全 `off`),且不
+ * 创建任何文件。present-but-invalid(坏 YAML、未知键、非法级别)抛错
+ * 带原因 —— 不静默降级成 `off`,否则用户的显式开启会被伪装成关闭。
+ */
+export declare function loadEvolveLevelPolicy(homeDir: string): EvolveLevelPolicy;
+/**
+ * 显式写入级别策略(用户选择的唯一入库通道;12.4 的 enable/disable
+ * 命令调用)。幂等:相同策略重写产生相同文件。
+ */
+export declare function writeEvolveLevelPolicy(homeDir: string, policy: EvolveLevelPolicy): void;
+/**
+ * 生效级别:更具体覆盖更宽泛 —— workspace 覆盖 > agent 覆盖 > 全局
+ * 默认 > `off`。会话在固定 (agent, workspace) 上下文中取值;任一粒度
+ * 未设置即向更宽泛粒度回退。
+ */
+export declare function resolveEvolveLevel(policy: EvolveLevelPolicy, context: {
+    agent?: string;
+    workspaceRoot?: string | null;
+}): Level;
+/**
+ * doctor 展示数据:托管的每个 agent 一行生效级别与观测形态(取 agent
+ * 覆盖或全局默认;workspace 覆盖单独成行)。观测形态由调用方按 capability
+ * delivery 计算后随条目传入;`agents` 之外的显式 agent 覆盖也列出(用户
+ * 设置了就可见),它们没有 runtime 交付配置,观测形态按 `doctor-only`。
+ */
+export declare function describeEvolveLevels(policy: EvolveLevelPolicy, managedAgents: readonly {
+    readonly agent: string;
+    readonly observation: EvolveObservation;
+}[]): EvolveLevelSection;

package/dist/host/levels.js

@@ -0,0 +1,206 @@
+/**
+ * 分级开启的级别策略(trellis-evolve 任务 10.2)。
+ *
+ * 级别配置是用户的显式选择,写入 canonical 的 `~/.trellis/evolve.yaml`
+ * (与 scope.yaml / secrets.policy.yaml 同级的根级策略文件;与 `evolve/`
+ * 运行状态目录刻意分开 —— 后者是只追加的运行记录,见任务 8.1)。格式、
+ * 校验与解析归 host:canonical 配置的解析是托管的职责,且 doctor(托管
+ * 命令)与自我进化消费者(`src/evolve/`,只允许 import `src/host/*`)必须
+ * 对同一份格式与解析规则达成一致 —— `src/host/` 是二者之间唯一合法的
+ * 共享缝(10.3 的边界)。卸载自我进化后本模块仍然自洽:文件不存在即
+ * 全部为 `off`,doctor 不出现该段。
+ *
+ * 文件形态(snake_case,沿用 servers.yaml 惯例):
+ *
+ * ```yaml
+ * default_level: observe
+ * agents:
+ *   claude-code: propose
+ * workspaces:
+ *   /abs/path/ws-a: off
+ * ```
+ *
+ * 解析优先级(更具体覆盖更宽泛):workspace > agent > default_level > `off`。
+ * 值白名单即 `LEVELS` 四级;present-but-invalid 一律硬错误,绝不静默误读。
+ * 读取零副作用:本模块永不创建文件或目录;写入只经 `writeEvolveLevelPolicy`
+ * (12.4 的 enable/disable 管理命令调用),从不静默开启。
+ */
+import { mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { writeFileAtomicSync } from "../lib/fsAtomic.js";
+/** 分级开启的四级,从关闭到最激进,有序(开启判定按此序)。 */
+export const LEVELS = ["off", "observe", "propose", "auto-A"];
+const LABEL = "evolve.yaml";
+function isLevel(value) {
+    return typeof value === "string" && LEVELS.includes(value);
+}
+export function evolveLevelPolicyPath(homeDir) {
+    return join(homeDir, ".trellis", LABEL);
+}
+const EMPTY_POLICY = { agents: {}, workspaces: {} };
+/**
+ * 读取级别策略。文件不存在 = 从未开启,返回空策略(全 `off`),且不
+ * 创建任何文件。present-but-invalid(坏 YAML、未知键、非法级别)抛错
+ * 带原因 —— 不静默降级成 `off`,否则用户的显式开启会被伪装成关闭。
+ */
+export function loadEvolveLevelPolicy(homeDir) {
+    let text;
+    try {
+        text = readFileSync(evolveLevelPolicyPath(homeDir), "utf-8");
+    }
+    catch {
+        return EMPTY_POLICY;
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(text);
+    }
+    catch (err) {
+        throw new Error(`${LABEL}: invalid YAML — ${err.message}`);
+    }
+    if (parsed === null || parsed === undefined)
+        return EMPTY_POLICY;
+    if (typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`${LABEL}: top level must be a mapping { default_level?, agents?, workspaces? }`);
+    }
+    const raw = parsed;
+    for (const key of Object.keys(raw)) {
+        if (key !== "default_level" && key !== "agents" && key !== "workspaces" && key !== "trigger") {
+            throw new Error(`${LABEL}: unrecognized top-level key "${key}"`);
+        }
+    }
+    let defaultLevel;
+    if (raw.default_level !== undefined) {
+        if (!isLevel(raw.default_level)) {
+            throw new Error(`${LABEL}: "default_level" must be one of ${LEVELS.join(" | ")} — got ${JSON.stringify(raw.default_level)}`);
+        }
+        defaultLevel = raw.default_level;
+    }
+    return {
+        ...(defaultLevel !== undefined ? { defaultLevel } : {}),
+        agents: parseLevelMap(raw.agents, "agents"),
+        workspaces: parseLevelMap(raw.workspaces, "workspaces"),
+        ...(raw.trigger !== undefined ? { trigger: parseTriggerLimits(raw.trigger) } : {}),
+    };
+}
+const TRIGGER_KEYS = {
+    signal_threshold: "signalThreshold",
+    cooldown_minutes: "cooldownMinutes",
+    daily_proposal_cap: "dailyProposalCap",
+    editor_budget: "editorBudget",
+};
+function parseTriggerLimits(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${LABEL}: "trigger" must be a mapping of ${Object.keys(TRIGGER_KEYS).join(" | ")}`);
+    }
+    const limits = {};
+    for (const [key, raw] of Object.entries(value)) {
+        const camel = TRIGGER_KEYS[key];
+        if (camel === undefined) {
+            throw new Error(`${LABEL}: "trigger" has unrecognized key "${key}" — expected one of ${Object.keys(TRIGGER_KEYS).join(" | ")}`);
+        }
+        if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0) {
+            throw new Error(`${LABEL}: "trigger.${key}" must be a non-negative integer — got ${JSON.stringify(raw)}`);
+        }
+        limits[camel] = raw;
+    }
+    // 缺省键不出现(由触发器回退到内置缺省值)。
+    return limits;
+}
+function parseLevelMap(value, field) {
+    if (value === undefined)
+        return {};
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${LABEL}: "${field}" must be a mapping of key → level`);
+    }
+    const out = {};
+    for (const [key, raw] of Object.entries(value)) {
+        if (key.length === 0) {
+            throw new Error(`${LABEL}: "${field}" keys must be non-empty strings`);
+        }
+        if (!isLevel(raw)) {
+            throw new Error(`${LABEL}: "${field}.${key}" must be one of ${LEVELS.join(" | ")} — got ${JSON.stringify(raw)}`);
+        }
+        out[key] = raw;
+    }
+    return out;
+}
+/**
+ * 显式写入级别策略(用户选择的唯一入库通道;12.4 的 enable/disable
+ * 命令调用)。幂等:相同策略重写产生相同文件。
+ */
+export function writeEvolveLevelPolicy(homeDir, policy) {
+    const doc = {};
+    if (policy.defaultLevel !== undefined)
+        doc.default_level = policy.defaultLevel;
+    if (Object.keys(policy.agents).length > 0)
+        doc.agents = policy.agents;
+    if (Object.keys(policy.workspaces).length > 0)
+        doc.workspaces = policy.workspaces;
+    if (policy.trigger !== undefined && Object.keys(policy.trigger).length > 0) {
+        const trigger = {};
+        if (policy.trigger.signalThreshold !== undefined)
+            trigger.signal_threshold = policy.trigger.signalThreshold;
+        if (policy.trigger.cooldownMinutes !== undefined)
+            trigger.cooldown_minutes = policy.trigger.cooldownMinutes;
+        if (policy.trigger.dailyProposalCap !== undefined)
+            trigger.daily_proposal_cap = policy.trigger.dailyProposalCap;
+        if (policy.trigger.editorBudget !== undefined)
+            trigger.editor_budget = policy.trigger.editorBudget;
+        doc.trigger = trigger;
+    }
+    const path = evolveLevelPolicyPath(homeDir);
+    mkdirSync(dirname(path), { recursive: true });
+    // 原子写:崩溃不留半截 YAML——present-but-invalid 会硬抛,半写文件
+    // 会让 doctor/recorder 等全部读取面报错。
+    writeFileAtomicSync(path, stringifyYaml(doc));
+}
+/**
+ * 生效级别:更具体覆盖更宽泛 —— workspace 覆盖 > agent 覆盖 > 全局
+ * 默认 > `off`。会话在固定 (agent, workspace) 上下文中取值;任一粒度
+ * 未设置即向更宽泛粒度回退。
+ */
+export function resolveEvolveLevel(policy, context) {
+    const root = context.workspaceRoot;
+    if (root != null) {
+        const workspaceLevel = policy.workspaces[root];
+        if (workspaceLevel !== undefined)
+            return workspaceLevel;
+    }
+    if (context.agent !== undefined) {
+        const agentLevel = policy.agents[context.agent];
+        if (agentLevel !== undefined)
+            return agentLevel;
+    }
+    return policy.defaultLevel ?? "off";
+}
+/**
+ * doctor 展示数据:托管的每个 agent 一行生效级别与观测形态(取 agent
+ * 覆盖或全局默认;workspace 覆盖单独成行)。观测形态由调用方按 capability
+ * delivery 计算后随条目传入;`agents` 之外的显式 agent 覆盖也列出(用户
+ * 设置了就可见),它们没有 runtime 交付配置,观测形态按 `doctor-only`。
+ */
+export function describeEvolveLevels(policy, managedAgents) {
+    const seen = new Set();
+    const agents = [];
+    for (const entry of managedAgents) {
+        if (seen.has(entry.agent))
+            continue;
+        seen.add(entry.agent);
+        agents.push({ agent: entry.agent, level: resolveEvolveLevel(policy, { agent: entry.agent }), observation: entry.observation });
+    }
+    for (const agent of Object.keys(policy.agents)) {
+        if (seen.has(agent))
+            continue;
+        seen.add(agent);
+        agents.push({ agent, level: resolveEvolveLevel(policy, { agent }), observation: "doctor-only" });
+    }
+    const workspaces = Object.entries(policy.workspaces).map(([root, level]) => ({ root, level }));
+    return {
+        ...(policy.defaultLevel !== undefined ? { defaultLevel: policy.defaultLevel } : {}),
+        agents,
+        workspaces,
+        diagnostics: [],
+    };
+}

package/dist/host/staging.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `host` facade — scratch staging (host-extension-points spec).
+ *
+ * Candidate edits must be evaluated against a COPY of the canonical
+ * surface, never the live one: `staging 后真实 canonical 与 agent 原生
+ * 配置逐字节不变` is a hard scenario of the spec. `createStaging` builds
+ * a disposable scratch home (and optional scratch workspace) that the
+ * check/apply/rollback half of the facade can read and write freely.
+ *
+ * What gets copied is deliberately bounded by `NATIVE_CHECK_SURFACE`:
+ * only the configuration and skill surfaces the machine-readable checks
+ * actually read. Account caches and credential stores — `.codex/auth.json`,
+ * `.claude/projects`, OAuth token files — are NOT part of that surface and
+ * never leave the real home (same boundary as the morphix-env rule: never
+ * read or replicate agent account caches).
+ */
+/**
+ * Home-relative paths the machine-readable checks read — presence probes,
+ * native config files, and skill roots for each agent. The staging copy
+ * is exactly this set plus `~/.trellis/`, nothing more. Paths here are
+ * the ONLY agent-native content that may be replicated into a scratch
+ * home; anything credential-shaped stays out by construction.
+ */
+export declare const NATIVE_CHECK_SURFACE: readonly string[];
+export interface CreateStagingOptions {
+    homeDir: string;
+    /** Real workspace root to replicate, or omit/null for global-only. */
+    workspaceRoot?: string | null;
+    /** Where to place the scratch root. Defaults to the OS temp dir. */
+    tmpRoot?: string;
+}
+export interface Staging {
+    /** Scratch root: everything lives under here and dies with `dispose()`. */
+    root: string;
+    /** Scratch home — pass this where the facade wants `homeDir`. */
+    homeDir: string;
+    /** Scratch workspace root (`.agents/` layer + workspace MCP configs),
+     * or null when staging is global-only. Pass this where the facade wants
+     * `workspaceRoot`. */
+    workspaceRoot: string | null;
+    /** The REAL workspace root this staging replicates — the stable label
+     * for layer attribution and id normalization. Physical scratch paths
+     * must never appear in comparable identities. */
+    logicalWorkspaceRoot: string | null;
+    /** Delete the entire scratch tree. Safe to call twice. */
+    dispose(): void;
+}
+/**
+ * Build a disposable scratch home (and optional scratch workspace).
+ * Copies `~/.trellis/` minus credential/state subtrees (`mcp/oauth`,
+ * `backups`, `evolve` — see TRELLIS_STAGING_EXCLUDES) plus exactly
+ * `NATIVE_CHECK_SURFACE`, then the workspace tree minus `.git`. The real
+ * home and workspace are never written to, and credential material never
+ * leaves it.
+ */
+export declare function createStaging(options: CreateStagingOptions): Staging;

package/dist/host/staging.js

@@ -0,0 +1,106 @@
+/**
+ * `host` facade — scratch staging (host-extension-points spec).
+ *
+ * Candidate edits must be evaluated against a COPY of the canonical
+ * surface, never the live one: `staging 后真实 canonical 与 agent 原生
+ * 配置逐字节不变` is a hard scenario of the spec. `createStaging` builds
+ * a disposable scratch home (and optional scratch workspace) that the
+ * check/apply/rollback half of the facade can read and write freely.
+ *
+ * What gets copied is deliberately bounded by `NATIVE_CHECK_SURFACE`:
+ * only the configuration and skill surfaces the machine-readable checks
+ * actually read. Account caches and credential stores — `.codex/auth.json`,
+ * `.claude/projects`, OAuth token files — are NOT part of that surface and
+ * never leave the real home (same boundary as the morphix-env rule: never
+ * read or replicate agent account caches).
+ */
+import { cpSync, existsSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { basename, dirname, join, relative, sep } from "node:path";
+import { tmpdir } from "node:os";
+/**
+ * Home-relative paths the machine-readable checks read — presence probes,
+ * native config files, and skill roots for each agent. The staging copy
+ * is exactly this set plus `~/.trellis/`, nothing more. Paths here are
+ * the ONLY agent-native content that may be replicated into a scratch
+ * home; anything credential-shaped stays out by construction.
+ */
+export const NATIVE_CHECK_SURFACE = [
+    // claude-code (probe: `.claude.json` exists)
+    ".claude.json",
+    ".claude/CLAUDE.md",
+    ".claude/skills",
+    ".claude/agents",
+    // codex (probe: `.codex/config.toml` exists)
+    ".codex/config.toml",
+    ".codex/skills",
+    // kiro
+    ".kiro/settings",
+    ".kiro/skills",
+    ".kiro/steering",
+    // kimi-code
+    ".kimi-code/mcp.json",
+    // zcode
+    ".zcode/cli",
+    ".zcode/skills",
+    ".zcode/AGENTS.md",
+    // pi
+    ".pi/agent",
+    // home-level shared skills root (codex plan reads `.agents/skills`)
+    ".agents/skills",
+    // kiro adapter's user-level settings file (macOS layout)
+    "Library/Application Support/Kiro/User/settings.json",
+];
+/** True unless `src` is a `.git` directory — VCS metadata is neither a
+ * check surface nor something a staging copy needs. */
+function notGitDir(src) {
+    return basename(src) !== ".git";
+}
+/** `.trellis` subtrees that NEVER leave the real home: credential stores
+ * (mcp/oauth token material), backup sessions, and evolve run state
+ * (pending records carry config file contents). A job killed mid-gate
+ * must not leave tokens behind in /tmp. */
+const TRELLIS_STAGING_EXCLUDES = ["mcp/oauth", "backups", "evolve"];
+function trellisStagingFilter(sourceRoot) {
+    return (src) => {
+        const rel = relative(sourceRoot, src).split(sep).join("/");
+        return !TRELLIS_STAGING_EXCLUDES.some((excluded) => rel === excluded || rel.startsWith(excluded + "/"));
+    };
+}
+function copyIfExists(from, to, filter) {
+    if (!existsSync(from))
+        return;
+    mkdirSync(dirname(to), { recursive: true });
+    cpSync(from, to, { recursive: true, ...(filter ? { filter } : {}) });
+}
+/**
+ * Build a disposable scratch home (and optional scratch workspace).
+ * Copies `~/.trellis/` minus credential/state subtrees (`mcp/oauth`,
+ * `backups`, `evolve` — see TRELLIS_STAGING_EXCLUDES) plus exactly
+ * `NATIVE_CHECK_SURFACE`, then the workspace tree minus `.git`. The real
+ * home and workspace are never written to, and credential material never
+ * leaves it.
+ */
+export function createStaging(options) {
+    const logicalWorkspaceRoot = options.workspaceRoot ?? null;
+    const root = mkdtempSync(join(options.tmpRoot ?? tmpdir(), "trellis-staging-"));
+    const scratchHome = join(root, "home");
+    mkdirSync(scratchHome, { recursive: true });
+    copyIfExists(join(options.homeDir, ".trellis"), join(scratchHome, ".trellis"), trellisStagingFilter(join(options.homeDir, ".trellis")));
+    for (const rel of NATIVE_CHECK_SURFACE) {
+        copyIfExists(join(options.homeDir, rel), join(scratchHome, rel), notGitDir);
+    }
+    let scratchWorkspace = null;
+    if (logicalWorkspaceRoot) {
+        scratchWorkspace = join(root, "workspace");
+        copyIfExists(logicalWorkspaceRoot, scratchWorkspace, notGitDir);
+    }
+    return {
+        root,
+        homeDir: scratchHome,
+        workspaceRoot: scratchWorkspace,
+        logicalWorkspaceRoot,
+        dispose() {
+            rmSync(root, { recursive: true, force: true });
+        },
+    };
+}

package/dist/host/surface.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `host` facade — surface read (host-extension-points spec).
+ *
+ * The narrow host boundary the self-evolution consumer codes against:
+ * every function here is part of the published `./host` contract, and
+ * nothing from `src/adapters/*` or `src/commands/*` is re-exported
+ * through it. This module is the read half: hand the facade a home
+ * directory (and optionally a workspace root) and get back the canonical
+ * surface for that exact layer — read-only, no mutation, no rendering.
+ */
+import type { CanonicalSource } from "../core/types.js";
+/** Which layer a surface read (or a structured check entry) belongs to.
+ * A workspace layer is always pinned to a concrete root so two different
+ * workspaces never share an identity. */
+export type SurfaceLayer = {
+    kind: "global";
+} | {
+    kind: "workspace";
+    root: string;
+};
+export interface ReadSurfaceOptions {
+    homeDir: string;
+    /** Explicit workspace root (as `findWorkspaceRoot` would return).
+     * Omit or pass null for the global layer only. Never inferred from
+     * `process.cwd()` — the host facade never guesses which project the
+     * caller means. */
+    workspaceRoot?: string | null;
+}
+export interface SurfaceRead {
+    source: CanonicalSource;
+    layer: SurfaceLayer;
+}
+/** Read the canonical surface at the requested layer. Read-only: the
+ * returned `CanonicalSource` is the same structure every other reader
+ * sees; this function writes nothing. */
+export declare function readSurface(options: ReadSurfaceOptions): SurfaceRead;

package/dist/host/surface.js

@@ -0,0 +1,20 @@
+/**
+ * `host` facade — surface read (host-extension-points spec).
+ *
+ * The narrow host boundary the self-evolution consumer codes against:
+ * every function here is part of the published `./host` contract, and
+ * nothing from `src/adapters/*` or `src/commands/*` is re-exported
+ * through it. This module is the read half: hand the facade a home
+ * directory (and optionally a workspace root) and get back the canonical
+ * surface for that exact layer — read-only, no mutation, no rendering.
+ */
+import { loadCanonicalSource } from "../core/canonical.js";
+/** Read the canonical surface at the requested layer. Read-only: the
+ * returned `CanonicalSource` is the same structure every other reader
+ * sees; this function writes nothing. */
+export function readSurface(options) {
+    const workspaceRoot = options.workspaceRoot ?? null;
+    const source = loadCanonicalSource({ homeDir: options.homeDir, workspaceDir: workspaceRoot });
+    const layer = workspaceRoot ? { kind: "workspace", root: workspaceRoot } : { kind: "global" };
+    return { source, layer };
+}

package/dist/lib/backup.js

@@ -73,21 +73,29 @@ export function openBackupSession(homeDir, command) {
         writeFile(path, content) {
             ensureDir();
             const afterHash = sha256(content);
+            // Record AFTER the write lands: an operation logged before its write
+            // is a phantom if the write throws (e.g. missing parent dir) — the
+            // manifest would claim a file-create for a path that never existed,
+            // and rollback would report a spurious conflict instead of "nothing
+            // to undo". The overwrite branch's before-snapshot must still be
+            // captured first, but it is an unreferenced file in the run dir
+            // until the push below references it — harmless on failure.
+            let operation;
             if (existsSync(path)) {
                 const before = readFileSync(path, "utf-8");
                 const relSnapshot = join("files", `${fileIndex}-${basename(path)}`);
                 fileIndex += 1;
                 writeFileSync(join(runDir, relSnapshot), before);
-                operations.push({
+                operation = {
                     kind: "file-overwrite",
                     path,
                     beforeFile: relSnapshot,
                     beforeHash: sha256(before),
                     afterHash,
-                });
+                };
             }
             else {
-                operations.push({ kind: "file-create", path, afterHash });
+                operation = { kind: "file-create", path, afterHash };
             }
             // A lock/provenance update must not leave a partially-written JSON file
             // if the process stops mid-write.  This also strengthens the existing
@@ -95,6 +103,7 @@ export function openBackupSession(homeDir, command) {
             const temporary = join(dirname(path), `.${basename(path)}.${process.pid}.${fileIndex}.tmp`);
             writeFileSync(temporary, content);
             renameSync(temporary, path);
+            operations.push(operation);
         },
         async createSymlink(path, linkTarget) {
             ensureDir();

package/dist/lib/envVarNames.js

@@ -22,7 +22,14 @@ export function extractTemplateVarNames(value) {
  * same answer to "what names does this def reference," not two
  * separately-maintained collections. */
 export function declaredEnvNames(def) {
+    // RAW entries, including `envAliases` sources (mx-env-secret-source
+    // secrets-audit delta): consumers that RESOLVE must see the original
+    // `mxenv://` text so references go through composition, then look the
+    // result up by delivered name; consumers that want the delivered NAMES
+    // map through `deliveredName` at their own use site (e.g. Kiro).
     const names = new Set(def.env ?? []);
+    for (const source of Object.values(def.envAliases ?? {}))
+        names.add(source);
     for (const value of Object.values(def.headers ?? {})) {
         for (const name of extractTemplateVarNames(value))
             names.add(name);

package/dist/lib/fsAtomic.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 原子文件写(tmp + rename):进程崩溃不留半截文件,读取方要么看到
+ * 旧内容要么看到新内容。canonical 配置与 pending 记录的写路径统一走
+ * 这里(对照:运行档案是只追加 JSONL,语义不同,不用本助手)。
+ */
+/** 原子写入整个文件(调用方负责确保目录存在)。 */
+export declare function writeFileAtomicSync(path: string, content: string): void;

package/dist/lib/fsAtomic.js

@@ -0,0 +1,14 @@
+/**
+ * 原子文件写(tmp + rename):进程崩溃不留半截文件,读取方要么看到
+ * 旧内容要么看到新内容。canonical 配置与 pending 记录的写路径统一走
+ * 这里(对照:运行档案是只追加 JSONL,语义不同,不用本助手)。
+ */
+import { randomBytes } from "node:crypto";
+import { renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** 原子写入整个文件(调用方负责确保目录存在)。 */
+export function writeFileAtomicSync(path, content) {
+    const temporary = join(dirname(path), `.atomic-${process.pid}-${randomBytes(6).toString("hex")}.tmp`);
+    writeFileSync(temporary, content, "utf-8");
+    renameSync(temporary, path);
+}

package/dist/lib/hostEventBus.d.ts

@@ -0,0 +1,47 @@
+/**
+ * In-process host event bus (host-extension-points spec).
+ *
+ * Dispatch is synchronous and ordered: `emit` walks listeners at the event
+ * point so a session-end event is observably delivered before upstream
+ * release continues. Failures are contained per listener — a synchronous
+ * throw or a rejected promise is swallowed and warned, never propagated to
+ * the tool call or to sibling listeners. With no subscribers `emit` is a
+ * single length check (zero overhead; runtime behavior stays byte-identical
+ * to the pre-event world). Listeners are expected to return promptly; slow
+ * work belongs behind the returned promise, which the caller never awaits.
+ */
+import { type HostEvent, type ToolCallInfo } from "../host/hostEvents.js";
+export type HostEventListener = (event: HostEvent) => void | Promise<void>;
+export declare class HostEventBus {
+    private readonly warn;
+    private readonly listeners;
+    constructor(warn?: (message: string) => void);
+    /** Register a listener; returns its unsubscribe function. Registration
+     * failure isolation for extensions is the loader's job (8.6) — this method
+     * only ever pushes. */
+    subscribe(listener: HostEventListener): () => void;
+    emit(event: HostEvent): void;
+    get subscriberCount(): number;
+}
+/**
+ * Stamps events with process-level identity. One instance per gateway
+ * process: `sessionId` is generated here and carried unchanged on every
+ * event the process emits ("会话开始"/tool calls/"会话结束").
+ */
+export declare class HostEventEmitter {
+    private readonly opts;
+    readonly sessionId: string;
+    constructor(opts: {
+        bus: HostEventBus;
+        agent: string;
+        /** Workspace root observed by the process; null = no workspace
+         * attribution (consumers derive layer from this). */
+        workspaceRoot: string | null;
+        now?: () => number;
+        sessionId?: string;
+    });
+    private ts;
+    sessionStart(): void;
+    toolCall(info: ToolCallInfo): void;
+    sessionEnd(): void;
+}