@sema-agent/server 7.44.0 → 7.45.0

package/dist/orchestration/hardened-vm-runner.js

@@ -24,14 +24,34 @@ function scrubProtoDeep(value) {
         scrubProtoDeep(value[key]);
     }
 }
+export function isScriptRealmRejection(promise) {
+    return !(promise instanceof Promise);
+}
+export function describeRejectionReason(reason) {
+    if (typeof reason === "object")
+        return reason === null ? "null" : "<object reason withheld: coercing it would run script-controlled code>";
+    if (typeof reason === "string")
+        return `string: ${reason.length > 200 ? `${reason.slice(0, 200)}…` : reason}`;
+    if (typeof reason === "number" || typeof reason === "boolean")
+        return `${typeof reason}: ${reason}`;
+    if (typeof reason === "bigint")
+        return `bigint: ${reason.toString()}`;
+    if (typeof reason === "undefined")
+        return "undefined";
+    if (typeof reason === "symbol")
+        return String(reason);
+    if (typeof reason === "function")
+        return "<function reason withheld>";
+    return `<unknown typeof ${typeof reason}>`;
+}
 let rejectionGuardInstalled = false;
 export function installScriptRealmRejectionGuard() {
     if (rejectionGuardInstalled)
         return;
     rejectionGuardInstalled = true;
     process.on("unhandledRejection", (reason, promise) => {
-        if (!(promise instanceof Promise)) {
-            const summary = reason instanceof Error ? `${reason.name}: ${reason.message}` : String(reason);
+        if (isScriptRealmRejection(promise)) {
+            const summary = describeRejectionReason(reason);
             try {
                 console.warn(`hardened-vm: un-awaited script rejection contained: ${summary}`);
             }
@@ -125,6 +145,25 @@ async function runHardened(opts) {
         }
     });
     const membrane = { bridge, dataIn, ctxEval: (src) => vm.runInContext(src, ctx) };
+    const describeScriptThrow = (thrown) => {
+        try {
+            const summaryCtx = vm.createContext({ __proto__: null, e: thrown }, { codeGeneration: { strings: false, wasm: false } });
+            const summarized = vm.runInContext(`(() => {
+           try {
+             if (e !== null && (typeof e === "object" || typeof e === "function") && typeof e.message === "string") {
+               return (typeof e.name === "string" ? e.name + ": " : "") + e.message;
+             }
+             return String(e);
+           } catch (inner) {
+             return "<script error message unavailable: summarizing it threw in-context>";
+           }
+         })()`, summaryCtx, { timeout: cfg.syncTimeoutMs });
+            return typeof summarized === "string" ? summarized : "<script error message unavailable: not a string>";
+        }
+        catch {
+            return "<script error message unavailable: summarizing it threw or timed out in-context>";
+        }
+    };
     for (const [name, value] of Object.entries(opts.buildGlobals(membrane)))
         sandbox[name] = value;
     let invocation;
@@ -135,7 +174,13 @@ async function runHardened(opts) {
         throw new WorkflowScriptError(`script failed to compile: ${err instanceof Error ? err.message : String(err)}`);
     }
     const scriptPromise = invocation.runInContext(ctx, { timeout: cfg.syncTimeoutMs });
-    scriptPromise.then(() => (scriptSettled = true), () => (scriptSettled = true));
+    let scriptThrew = false;
+    let scriptThrownValue;
+    scriptPromise.then(() => (scriptSettled = true), (thrown) => {
+        scriptSettled = true;
+        scriptThrew = true;
+        scriptThrownValue = thrown;
+    });
     probeQuiescence();
     let timer;
     let onAbort;
@@ -155,9 +200,12 @@ async function runHardened(opts) {
         return marshalOut(result);
     }
     catch (err) {
+        if (scriptThrew && err === scriptThrownValue) {
+            throw new WorkflowScriptError(`script failed at runtime: ${describeScriptThrow(err)}`);
+        }
         if (err instanceof WorkflowScriptError)
             throw err;
-        throw new WorkflowScriptError(`script failed at runtime: ${err instanceof Error ? err.message : String(err)}`);
+        throw new WorkflowScriptError(`script failed at runtime: ${err instanceof Error ? err.message : describeScriptThrow(err)}`);
     }
     finally {
         if (timer)

package/dist/plugins/remote-env-ssh.d.ts

@@ -1,3 +1,4 @@
+import { type SshHostKeyPolicy } from "../ssh-host-key.js";
 import { FileError, ExecutionError, RemoteExecutionError, type ExecutionEnv, type RemoteExecutionEnv, type WorkspaceHandle, type FileInfo, type Result, type OutputChunk, type ExecStreamOptions, type RemoteConnectConfig, type SnapshotId, type SessionToken, type VmLifecycleOptions, type ExecutionEnvFactory } from "@sema-agent/core";
 type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
 export interface SshEnvConfig {
@@ -32,6 +33,8 @@ export interface SshEnvConfig {
         maxAttempts?: number;
         backoffMs?: number;
     };
+    /** #296 / C-R21:主机密钥校验策略(两旋钮,语义见 {@link SshHostKeyPolicy});缺席 = 两旋钮都没配。 */
+    hostKey?: SshHostKeyPolicy;
 }
 type ConnectResult = {
     ok: true;

package/dist/plugins/remote-env-ssh.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { Client } from "ssh2";
+import { createSshHostKeyVerifier } from "../ssh-host-key.js";
 import { shellQuote, kindFromMode } from "./remote-shell.js";
 import { signalNumber } from "./host-platform.js";
 import { createPosixShellFs } from "./posix-shell-fs.js";
@@ -37,6 +38,7 @@ export class RemoteSshExecutionEnv {
             commandTimeoutMs: config.commandTimeoutMs ?? 5 * 60_000,
             dataTimeoutMs: config.dataTimeoutMs ?? 5 * 60_000,
             retry: { maxAttempts: config.retry?.maxAttempts ?? 3, backoffMs: config.retry?.backoffMs ?? 500 },
+            hostKey: config.hostKey,
         };
         this.cwd = this.cfg.mountPath;
     }
@@ -136,6 +138,12 @@ export class RemoteSshExecutionEnv {
             if (signal?.aborted)
                 return resolve({ ok: false, error: new RemoteExecutionError("aborted", "connect aborted") });
             const c = new Client();
+            let hostKeyRejection;
+            const verifyHostKey = createSshHostKeyVerifier({
+                host: this.cfg.host,
+                port: this.cfg.port,
+                ...(this.cfg.hostKey !== undefined ? { policy: this.cfg.hostKey } : {}),
+            });
             const opts = {
                 host: this.cfg.host,
                 port: this.cfg.port,
@@ -143,6 +151,14 @@ export class RemoteSshExecutionEnv {
                 privateKey: this.cfg.privateKey,
                 ...(this.cfg.passphrase ? { passphrase: this.cfg.passphrase } : {}),
                 readyTimeout: this.cfg.readyTimeoutMs,
+                hostVerifier: (key) => {
+                    const verdict = verifyHostKey(key);
+                    if (!verdict.ok) {
+                        hostKeyRejection = verdict.reason;
+                        return false;
+                    }
+                    return true;
+                },
             };
             c.on("ready", () => {
                 if (this.destroyed || epoch !== this.connEpoch) {
@@ -168,7 +184,10 @@ export class RemoteSshExecutionEnv {
                 }
                 catch {
                 }
-                resolve({ ok: false, error: this.connErr(e) });
+                resolve({
+                    ok: false,
+                    error: hostKeyRejection !== undefined ? new RemoteExecutionError("connect_failed", hostKeyRejection, e) : this.connErr(e),
+                });
             });
             try {
                 c.connect(opts);

package/dist/plugins/send-user-file.js

@@ -1,5 +1,6 @@
 import { createHmac } from "node:crypto";
 import { uuidv7 } from "@sema-agent/core";
+import { CONTROL_AND_BIDI_STRIP_RE } from "../text-bidi.js";
 import { presignS3CopyUrl, presignS3Url } from "./s3-presign.js";
 import { OBJECT_STORE_IO_TIMEOUT_MS } from "./blob-backend.js";
 export const PRESIGN_MAX_TTL_SEC = 604_800;
@@ -10,7 +11,7 @@ export function scopeSegment(secretKey, scope) {
 }
 export function sanitizeSendFileName(name) {
     const base = (name ?? "").split(/[/\\]/).pop() ?? "";
-    let clean = base.replace(/[\u0000-\u001f\u007f\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, "").replace(/^\.+/, "").trim();
+    let clean = base.replace(CONTROL_AND_BIDI_STRIP_RE, "").replace(/^\.+/, "").trim();
     if (clean.length > 128) {
         const dot = clean.lastIndexOf(".");
         const ext = dot > 0 && clean.length - dot <= 16 ? clean.slice(dot) : "";

package/dist/plugins/tidb-session-storage.d.ts

@@ -3,10 +3,13 @@ import type { Pool } from "mysql2/promise";
 /**
  * TiDB-backed {@link BaseSessionStorage} — the durable L1 event log for one session.
  *
- * - `appendEntry` / `setLeafId` persist with an **atomic compare-and-set** on `leaf_seq` + `leaf_id`
- *   (core's F2 optimistic-lock seam): a write only lands if the branch leaf is still what the entry
- *   was built against. Two stateless runners that both woke the same session can't silently fork —
- *   the loser gets `SessionError("conflict")` (catch with `isSessionConflict`).
+ * - `appendEntry` / `setLeafId` persist under an **atomic compare-and-set on `leaf_id`** (core's F2
+ *   optimistic-lock seam): the conditional UPDATE's only predicate is `leaf_id <=> ?`, so a write lands
+ *   only if the branch leaf is still what the entry was built against. Two stateless runners that both
+ *   woke the same session can't silently fork — the loser gets `SessionError("conflict")` (catch with
+ *   `isSessionConflict`), with the `(session_id, seq)` primary key as the backstop for a racing writer
+ *   that grabbed the same seq. (A-071 件2 更正:`leaf_seq` **不是**判据 —— 它是无条件的 `SET leaf_seq =
+ *   leaf_seq + 1` 计数器,在同一事务内重读出来给事件铸 `seq`,从不进 WHERE。)
  * - The in-memory base tree is the wake-time snapshot; every write is also mirrored into it so the
  *   live harness keeps reading a consistent view. Wake is **bounded** to `[floor .. leaf]` (F3,
  *   core 1.6.0 branch-floor seam); older history is covered by the last compaction's summary.
@@ -14,9 +17,8 @@ import type { Pool } from "mysql2/promise";
 export declare class TiDBSessionStorage extends BaseSessionStorage {
     private readonly pool;
     private readonly sessionId;
-    private leafSeq;
     private readonly floorSeq;
-    constructor(pool: Pool, sessionId: string, metadata: SessionMetadata, entries: SessionTreeEntry[], leafId: string | null, leafSeq: number, floorEntryId?: string | null, floorSeq?: number);
+    constructor(pool: Pool, sessionId: string, metadata: SessionMetadata, entries: SessionTreeEntry[], leafId: string | null, floorEntryId?: string | null, floorSeq?: number);
     /**
      * [976] S3 RB-14 pull seam — `SessionStorage.getEpochAnchor?()`: the nearest epoch carrier BELOW the
      * bounded-wake floor. core's `Session.getPromptEpoch()` (≥1.305) calls this only when the in-window

package/dist/plugins/tidb-session-storage.js

@@ -7,13 +7,11 @@ const isDupKey = isMysqlDupKeyError;
 export class TiDBSessionStorage extends BaseSessionStorage {
     pool;
     sessionId;
-    leafSeq;
     floorSeq;
-    constructor(pool, sessionId, metadata, entries, leafId, leafSeq, floorEntryId = null, floorSeq = 0) {
+    constructor(pool, sessionId, metadata, entries, leafId, floorEntryId = null, floorSeq = 0) {
         super(metadata, entries, leafId, { floorEntryId });
         this.pool = pool;
         this.sessionId = sessionId;
-        this.leafSeq = leafSeq;
         this.floorSeq = floorSeq;
     }
     async getEpochAnchor() {
@@ -43,7 +41,7 @@ export class TiDBSessionStorage extends BaseSessionStorage {
         const entries = eventRows.map((r) => typeof r.payload === "string" ? JSON.parse(r.payload) : r.payload);
         const placement = placementFromRow(meta);
         const metadata = { id: sessionId, createdAt: toIso(meta.created_at), ...(placement !== undefined ? { placement } : {}) };
-        return new TiDBSessionStorage(pool, sessionId, metadata, entries, meta.leaf_id ?? null, Number(meta.leaf_seq), floorEntryId, floorSeq);
+        return new TiDBSessionStorage(pool, sessionId, metadata, entries, meta.leaf_id ?? null, floorEntryId, floorSeq);
     }
     static async computeFloor(pool, sessionId) {
         const [compRows] = await pool.query("SELECT payload FROM session_event WHERE session_id = ? AND type = 'compaction' ORDER BY seq DESC LIMIT 1", [sessionId]);
@@ -96,7 +94,6 @@ export class TiDBSessionStorage extends BaseSessionStorage {
             const commitOwner = seqRows[0].owner ?? null;
             await conn.query("INSERT INTO session_event (session_id, seq, entry_id, parent_id, type, payload, ts) VALUES (?,?,?,?,?,?,?)", [this.sessionId, seq, entry.id, entry.parentId ?? null, entry.type, JSON.stringify(entry), new Date(entry.timestamp)]);
             await conn.commit();
-            this.leafSeq = seq;
             emitLeafAdvance(this.sessionId, newLeaf, commitOwner, seq);
         }
         catch (err) {

package/dist/rules-consent.d.ts

@@ -1,4 +1,4 @@
-import { type RuleOwner, type ImportPreview, type ImportResult, type ImportedSettingsLayer, type PersistedAllowRule, type RemoveResult, type RuleScope } from "@sema-agent/core";
+import { type RuleOwner, type ImportPreview, type ImportResult, type ImportedSettingsLayer, type PersistedAllowRule, type RemoveResult, type EditedRuleTextPrecheck, type RuleScope } from "@sema-agent/core";
 import type { PermissionRuleStoreProvider, RuleApprovalRecordStore } from "@sema-agent/core";
 import { type RuleImportTicket, type RuleTicketDecisionClock, type RuleTicketRedeemResult } from "./plugins/permission-rule-store-sql.js";
 /**
@@ -107,13 +107,7 @@ export type RuleImportRedeemed = {
     detail: string;
     retryable?: true;
 };
-/**
- * #340([4763])—— 一次卡道兑付**要兑的是什么**:两个显式臂,永不折叠。
- *
- * 🔴 判别式联合而不是「一个文本 + 一个布尔」:两个臂的文本**含义不同**——候选臂的串是「卡上第几条」的
- * 定位键(对不上 ⇒ `rule_not_offered`,语义一个字不变),编辑臂的串是**人自己写的规则**(由 core 的
- * 卡编辑面校验 + 覆盖门判)。同一个字段两种含义会让下一个读者(和下一次改动)分不清哪条路上该做哪道门。
- */
+export declare function precheckCardRuleText(text: string, command: string): EditedRuleTextPrecheck | undefined;
 export type CardRuleRedemption = 
 /** 人**点了卡上的某条候选**:文本用来在引擎铸的候选表里定位下标。 */
 {
@@ -143,17 +137,26 @@ export type CardRulePersisted = {
      * #340:人写的文本**被引擎的门拒了**——共享校验器不认这个拼写,或它不覆盖本次被裁决的命令
      * (「编辑可以更宽,但不许换成另一条授权」)。
      *
-     * 🔴 **这一格不是「重试就好」**(codex 对抗复审 [medium],验真后按实况改词):兑付发生在裁决
-     * **落定之后**(那条顺序是硬的 —— 一次没有生效的裁决不该留下一条永久规则),所以拿到这个词时
-     * 这张卡已经消费掉了,同一个 `approvalId` 再回决是 404。人的「允许这次」照常生效,只是这一次
-     * 没能顺手存下规则;改好的文本要落,得等**下一次同命令的 ask**(与 `rule_input_edited` 逐字
-     * 同一条处置)。壳的措辞据此写,别渲成「点这里重试」。
-     * 想做到「同一张卡上改了再来」需要一次**裁决之前**的预检,而那要求 core 把编辑面的校验(含它自己
-     * 的拼写规范化)导出成一只纯函数 —— 在本层照抄一个更严的校验器会把 `Bash(adb *)` 这条**成因形**
-     * 当场误拒。已登记为上游请托,不在本层用第二个解析器凑。
+     * 🔴 **射程自 #345 起收窄**(core 5.57.0 `precheckEditedRuleText` 到货 —— 下面那条上游请托兑现了)。
+     * 原话保留作史:「兑付发生在裁决**落定之后**,所以拿到这个词时这张卡已经消费掉了;想做到『同一张
+     * 卡上改了再来』需要一次**裁决之前**的预检,而那要求 core 把编辑面的校验(含它自己的拼写规范化)
+     * 导出成一只纯函数 —— 在本层照抄一个更严的校验器会把 `Bash(adb *)` 这条**成因形**当场误拒。」
+     *
+     * 现况:那只纯函数到货了,于是**文本能独立判定的那一半**({@link precheckEditedRuleText} 的语法门
+     * + 覆盖门)搬到了**裁决之前**——`POST /v1/tool-approvals/:id/respond` 在结算之前就 400,卡**还在**
+     * (与 `persistRule.rule` 的形/上限 400 同一姿势,那条 400 早就是这个形)。所以壳今天可以渲
+     * 「改一下再来」,而且真能来。
+     *
+     * 这个词因此只剩**纵深**的那一半:预检被跳过的路径(治理档 / 无车道素材 / 无属主 / ctrl+g 编辑放行
+     * 各自有自己的词,不到这里)与「预检过了但记录级仍拒」的残余竞态。到这个词时那句老话仍然成立
+     * ——卡已消费、同一把 approvalId 再回决是 404。
      */
      | "edit-rejected";
     detail: string;
+    /** #345:core 的**共享校验器**refusal code(`RuleRejectCode`,开集透传)。覆盖门拒时**缺席** ——
+     *  这条在场规则与 core `confirmRuleApproval` 的 `edit_rejected` detail 逐字同源(同一个函数体)。
+     *  🔴 不 switch、不翻译、不折叠:词表属主是 core,本仓照转。 */
+    code?: string;
 };
 /** 一层用户交上来的 settings(HTTP 载荷已 zod 校验过的形)。 */
 export interface RuleImportLayerInput {

package/dist/rules-consent.js

@@ -2,11 +2,24 @@ import { randomUUID } from "node:crypto";
 import { recordFailOpen } from "./observability/fail-open.js";
 import { createLogger } from "./observability/logger.js";
 import { MAX_CWD_CHARS } from "./task-cwd.js";
-import { confirmRuleApproval, parseAllowRuleText, prepareCardApproval, prepareCcImport, redeemRuleBatch, redeemRuleTicket, removePersistedRule, } from "@sema-agent/core";
+import { confirmRuleApproval, parseAllowRuleText, precheckEditedRuleText, prepareCardApproval, prepareCcImport, redeemRuleBatch, redeemRuleTicket, removePersistedRule, } from "@sema-agent/core";
 import { buildRulePayloadHash } from "./plugins/permission-rule-store-sql.js";
 export const RULE_IMPORT_TICKET_TTL_MS = 10 * 60_000;
 export const RULE_IMPORT_RETRY_AFTER_SEC = 2;
 export const MAX_IMPORT_CANDIDATES = 200;
+const precheckLogger = createLogger();
+export function precheckCardRuleText(text, command) {
+    try {
+        return precheckEditedRuleText(text, command);
+    }
+    catch (e) {
+        precheckLogger.warn("card_rule_precheck_unanswerable", {
+            err: String(e),
+            note: "the edit-face precheck could not be asked about these inputs — falling through to the authoritative gate inside confirmRuleApproval (same body, later)",
+        });
+        return undefined;
+    }
+}
 export function serializeRuleScope(scope) {
     return scope.kind === "global" ? "global" : `project:${scope.root}`;
 }
@@ -128,6 +141,10 @@ export function createRuleConsentLane(stores, opts) {
                 if (input.boundInputHash === undefined) {
                     return { ok: false, reason: "edit-unsupported", detail: "this approval card carries no bound-input digest — an edited rule has nothing to bind to" };
                 }
+                const pre = precheckCardRuleText(redemption.text, input.command);
+                if (pre !== undefined && !pre.ok) {
+                    return { ok: false, reason: "edit-rejected", detail: pre.message, ...(pre.code !== undefined ? { code: pre.code } : {}) };
+                }
                 const confirmed = await confirmRuleApproval({
                     approvalId: prepared.approvalId,
                     principal: input.principal,

package/dist/run-local.js

@@ -285,6 +285,8 @@ export async function runLocal(argv, deps = {}) {
             memoryRoot: memoryEngine.root,
             transport: createMemorySyncTransport({ url: config.memorySync.url, token: config.memorySync.token }),
             log: logger,
+            ...(config.memorySync.maxPushEntries !== undefined ? { maxPushEntries: config.memorySync.maxPushEntries } : {}),
+            ...(config.memorySync.maxPullEntries !== undefined ? { maxPullEntries: config.memorySync.maxPullEntries } : {}),
         });
         logger.info("memory_sync_enabled", { url: config.memorySync.url, scope: config.memorySync.scope, cursorPath: memorySync.cursorPath });
         memorySync.trigger("boot");
@@ -378,7 +380,10 @@ export async function runLocal(argv, deps = {}) {
         backgroundAgentStore: undefined,
         mailboxStore: undefined,
         rosterStore: undefined,
-        deploymentHooks: createPermissionDeniedMeter(metrics),
+        deploymentHooks: {
+            ...createPermissionDeniedMeter(metrics),
+            ...(config.hooksTimeoutMs !== undefined ? { timeoutMs: config.hooksTimeoutMs } : {}),
+        },
         toolResultStore: fileBackend.toolResultStore,
         sessionPolicyStore: fileBackend.sessionPolicyStore,
         usageWindowStore: config.usageWindows ? fileBackend.usageWindowStore : undefined,

package/dist/session-titler.js

@@ -1,3 +1,4 @@
+import { CONTROL_AND_BIDI_STRIP_RE } from "./text-bidi.js";
 export const TITLE_MAX_CHARS = 80;
 const OBJECTIVE_SNIPPET_CHARS = 600;
 const LLM_TIMEOUT_MS = 15_000;
@@ -6,7 +7,7 @@ const FAIL_CAUSE_KEY_CHARS = 80;
 const FAIL_CAUSE_CAP = 100;
 const SEEN_CAP = 10_000;
 export function sanitizeTitle(raw) {
-    const oneLine = raw.replace(/[\r\n]+/g, " ").replace(/[\u0000-\u001f\u007f\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, "").trim();
+    const oneLine = raw.replace(/[\r\n]+/g, " ").replace(CONTROL_AND_BIDI_STRIP_RE, "").trim();
     const unquoted = oneLine.replace(/^["'「『]+/, "").replace(/["'」』]+$/, "").trim();
     return unquoted.length > TITLE_MAX_CHARS ? `${unquoted.slice(0, TITLE_MAX_CHARS - 1)}…` : unquoted;
 }

package/dist/sighup-idle.d.ts

@@ -36,8 +36,22 @@ export interface SighupIdleDeps {
      *  本文件不对外报告 epoch 时间戳,故 Date.now() 一律不再出现。 */
     now?: () => number;
 }
+/**
+ * SIGHUP 处理器 + 它自己那只空闲窗的**停表口**。
+ *
+ * 🔴 `stop()` 不是可选装饰(codex 对抗复审 F2,已复现):armed 之后这只 interval **刻意不 unref**
+ * (孤儿形下它就是关停驱动),而它握着的 `shutdown`/`escalate` 是**装配那一刻**的闭包。只摘 SIGHUP 监听、
+ * 不停表 = 一个已经退役的装配仍会在 grace 到期时按旧 ctx 关停进程(实测:arm 后立刻摘监听,1.1s 后旧
+ * ctx 的 `server.close` 照样被调)。注册/摘除配对必须覆盖它。
+ */
+export interface SighupIdleHandler {
+    /** 信号处理函数本体:每次 SIGHUP 调一次(首次 arm 空闲窗,第二次 escalate)。 */
+    (): void;
+    /** 停掉已 armed 的空闲窗(幂等;没 arm 过时无操作)。 */
+    stop(): void;
+}
 /** Returns the SIGHUP handler. Call it on every SIGHUP; it arms the idle watch on the first signal and
  *  escalates on the second. The interval is deliberately NOT unref'd — in the orphan case it IS the
- *  shutdown driver (same posture as the drain tick). */
-export declare function createSighupIdleHandler(deps: SighupIdleDeps): () => void;
+ *  shutdown driver (same posture as the drain tick); {@link SighupIdleHandler.stop} is the退役口. */
+export declare function createSighupIdleHandler(deps: SighupIdleDeps): SighupIdleHandler;
 //# sourceMappingURL=sighup-idle.d.ts.map

package/dist/sighup-idle.js

@@ -4,7 +4,7 @@ export function createSighupIdleHandler(deps) {
     let watch;
     let idleSince = null;
     let armedAt = 0;
-    return () => {
+    const onSignal = () => {
         if (deps.isStopped()) {
             deps.log("sighup_ignored_shutdown_in_progress", {});
             return;
@@ -50,5 +50,14 @@ export function createSighupIdleHandler(deps) {
             }
         }, tickMs);
     };
+    return Object.assign(onSignal, {
+        stop: () => {
+            if (watch === undefined)
+                return;
+            clearInterval(watch);
+            watch = undefined;
+            idleSince = null;
+        },
+    });
 }
 //# sourceMappingURL=sighup-idle.js.map

package/dist/ssh-host-key.d.ts

@@ -0,0 +1,65 @@
+/**
+ * #296(A-052.2;clay 裁定 **C-R21** 形:「响亮警告继续连」)—— SSH lane 的**主机密钥校验**两旋钮。
+ *
+ * ## 病灶(修前逐字形)
+ * `connectOnce` 的 `ConnectConfig` 从来不设 `hostVerifier`,而 ssh2 在缺席时**不做任何主机密钥校验** ——
+ * 这条 lane 于是恒等于 `ssh -o StrictHostKeyChecking=no`:握手对面是谁都照连、照把 agent 的命令与
+ * sftp 写入交出去。适配器持有的是控制面注入的私钥(design/61 §5 #2),中间人拿不到私钥,但**拿得到
+ * 这次会话的全部命令、全部产物、以及 agent 在那台机器上的全部动作**。
+ *
+ * ## 为什么不是「一律拒连」(裁定形)
+ * 本 lane 的既有部署形是「AI 编排批量部署到一批 SSH 可达的机器」,那些机器的密钥指纹通常不在任何
+ * known_hosts 里。默认拒连 = 一次静默的**可用性**断裂,而 C-R21 裁的是:**在场即严格,缺席即响亮**。
+ * 缺席那一格是登记在案的 fail-open(`server.exec-lane.ssh-host-key-unverified`,census §1),不是遗漏。
+ *
+ * ## 两旋钮(config 面 `SSH_HOST_FINGERPRINT` / `SSH_KNOWN_HOSTS`,坏值拒启 —— #210 律)
+ *  · `fingerprintSha256` —— 主机公钥的 **SHA256 base64** 指纹(`ssh-keyscan` + `ssh-keygen -lf` 打印的
+ *    那一串)。归一后存**裸 base64**(无 `SHA256:` 前缀、无 `=` 填充);
+ *  · `knownHostsPath` —— known_hosts 文件路径,按 `host` / `[host]:port` **逐字**匹配行。
+ *
+ * **两只同时在场 = 合取**(都必须过)。任一在场 ⇒ 严格校验,不符**拒连**;两只都缺席 ⇒ 每连接一条
+ * 响亮 warn + 计数,照常连。
+ *
+ * ## 明确**不支持**的 known_hosts 语法(成文,不是遗漏 —— 遇到即拒连并在拒因里说清)
+ *  · **hashed 行**(`|1|<salt>|<hash>`,`ssh-keyscan -H` / `HashKnownHosts yes` 的产物):要按 HMAC-SHA1
+ *    反查主机名,而本适配器刻意不实现那一步(它把「读一个文件、比一串字节」变成一个需要自己实现
+ *    OpenSSH 私有派生的解析器)。⇒ hashed 行一律**跳过**;若某台机器只有 hashed 行,结果是**拒连**
+ *    (fail-closed,不是悄悄放行),拒因里逐字点名这一条并给出 `ssh-keyscan` 指路;
+ *  · **通配符 pattern**(`*.example.com`、`!host` 取反):同上跳过 ⇒ 只有通配符行的主机会被拒连;
+ *  · **`@cert-authority` 行**:证书信任链本适配器不实现 ⇒ 跳过(同样是拒连方向)。
+ *  · **`@revoked` 行**:不跳过 —— 匹配上就是**硬拒**(吊销是收紧方向,跳过它才是 fail-open)。
+ */
+export interface SshHostKeyPolicy {
+    /** 归一后的**裸 base64** SHA256 指纹(无 `SHA256:` 前缀、无 `=` 填充)。 */
+    fingerprintSha256?: string;
+    /** known_hosts 文件路径。 */
+    knownHostsPath?: string;
+}
+/** {@link createSshHostKeyVerifier} 的判词。`verified:false` = 两旋钮都缺席那一格(照连,但响亮)。 */
+export type SshHostKeyVerdict = {
+    ok: true;
+    verified: boolean;
+} | {
+    ok: false;
+    reason: string;
+};
+/** SHA256 base64 指纹的**归一**:`SHA256:` 前缀可选、`=` 填充可选;形不合 ⇒ **抛**(调用方在 boot 期拒启)。 */
+export declare function normalizeSshFingerprint(raw: string): string;
+/** ssh2 交来的**主机公钥 wire blob** → `SHA256:<base64>`(OpenSSH 打印的同一形,无 `=` 填充)。 */
+export declare function sshHostKeyFingerprint(key: Buffer): string;
+/**
+ * 主机密钥判官(#296 / C-R21)。返回一个**收 ssh2 的公钥 blob、给判词**的闭包(有捕获行为 ⇒ `create*`)。
+ *
+ * 缺席那一格调用 `onUnverified` —— **每连接一次**,不是每进程一次:一台长期未配旋钮的机器上,
+ * 「这条 lane 一直在裸连」必须在每一条连接上都看得见,否则它会随第一条日志滚出视野。
+ */
+export declare function createSshHostKeyVerifier(opts: {
+    host: string;
+    port: number;
+    policy?: SshHostKeyPolicy;
+    /** 测试缝:替掉 known_hosts 的读盘(缺省 `readFileSync`)。 */
+    readKnownHosts?: (p: string) => string;
+    /** 两旋钮全缺席时的响亮口(缺省 = 本模块 logger 的一条 warn + fail-open 计数)。 */
+    onUnverified?: (message: string) => void;
+}): (key: Buffer) => SshHostKeyVerdict;
+//# sourceMappingURL=ssh-host-key.d.ts.map

package/dist/ssh-host-key.js

@@ -0,0 +1,117 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { createLogger } from "./observability/logger.js";
+import { recordFailOpen } from "./observability/fail-open.js";
+const sshLogger = createLogger();
+export function normalizeSshFingerprint(raw) {
+    const bare = raw.trim().replace(/^SHA256:/i, "").replace(/=+$/, "");
+    if (!/^[A-Za-z0-9+/]{43}$/.test(bare)) {
+        throw new Error(`SSH host fingerprint must be a SHA256 base64 digest (43 base64 chars, optional "SHA256:" prefix / "=" padding) — got ${JSON.stringify(raw)}. ` +
+            `Read the real one with: ssh-keyscan -p <port> <host> | ssh-keygen -lf -`);
+    }
+    return bare;
+}
+export function sshHostKeyFingerprint(key) {
+    return `SHA256:${createHash("sha256").update(key).digest("base64").replace(/=+$/, "")}`;
+}
+function knownHostsPatternsFor(host, port) {
+    return port === 22 ? [host, `[${host}]:22`] : [`[${host}]:${port}`];
+}
+function matchKnownHosts(text, host, port, keyB64) {
+    const wanted = new Set(knownHostsPatternsFor(host, port));
+    let sawEntry = false;
+    let plainMatch = false;
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line === "" || line.startsWith("#"))
+            continue;
+        let fields = line.split(/\s+/);
+        let revoked = false;
+        if (fields[0]?.startsWith("@")) {
+            const marker = fields[0];
+            if (marker !== "@revoked")
+                continue;
+            revoked = true;
+            fields = fields.slice(1);
+        }
+        const [patterns, , blob] = fields;
+        if (patterns === undefined || blob === undefined)
+            continue;
+        if (revoked && blob === keyB64 && (patterns.startsWith("|") || /[*?!]/.test(patterns)))
+            return "revoked";
+        if (patterns.startsWith("|"))
+            continue;
+        const names = patterns.split(",");
+        if (!names.some((n) => wanted.has(n)))
+            continue;
+        sawEntry = true;
+        if (blob !== keyB64)
+            continue;
+        if (revoked)
+            return "revoked";
+        plainMatch = true;
+    }
+    if (plainMatch)
+        return "matched";
+    return sawEntry ? "mismatch" : "no-entry";
+}
+function keyscanHint(host, port) {
+    return `Read the host's real fingerprint with: ssh-keyscan -p ${port} ${host} | ssh-keygen -lf -`;
+}
+export function createSshHostKeyVerifier(opts) {
+    const { host, port, policy } = opts;
+    const readKnownHosts = opts.readKnownHosts ?? ((p) => readFileSync(p, "utf8"));
+    const fingerprint = policy?.fingerprintSha256;
+    const knownHostsPath = policy?.knownHostsPath;
+    const unverifiedMessage = `SSH host key NOT verified — man-in-the-middle risk: this connection to ${host}:${port} accepts ANY host key. ` +
+        `Set SSH_HOST_FINGERPRINT (SHA256 base64) or SSH_KNOWN_HOSTS (a known_hosts path) to verify it. ` +
+        keyscanHint(host, port);
+    const onUnverified = opts.onUnverified ??
+        ((message) => {
+            sshLogger.warn("ssh_host_key_unverified", { host, port, detail: message });
+            recordFailOpen("server.exec-lane.ssh-host-key-unverified", `${host}:${port}`);
+        });
+    return (key) => {
+        if (fingerprint === undefined && knownHostsPath === undefined) {
+            onUnverified(unverifiedMessage);
+            return { ok: true, verified: false };
+        }
+        const presented = sshHostKeyFingerprint(key);
+        if (fingerprint !== undefined && presented !== `SHA256:${fingerprint}`) {
+            return {
+                ok: false,
+                reason: `SSH host key rejected for ${host}:${port} — fingerprint mismatch. presented=${presented} expected=SHA256:${fingerprint} (SSH_HOST_FINGERPRINT). ` +
+                    keyscanHint(host, port),
+            };
+        }
+        if (knownHostsPath !== undefined) {
+            let text;
+            try {
+                text = readKnownHosts(knownHostsPath);
+            }
+            catch (e) {
+                return {
+                    ok: false,
+                    reason: `SSH host key rejected for ${host}:${port} — SSH_KNOWN_HOSTS (${knownHostsPath}) could not be read at connect time: ` +
+                        `${e instanceof Error ? e.message : String(e)}. presented=${presented}. ` +
+                        keyscanHint(host, port),
+                };
+            }
+            const verdict = matchKnownHosts(text, host, port, key.toString("base64"));
+            if (verdict !== "matched") {
+                const why = verdict === "revoked"
+                    ? "the presented key is listed @revoked"
+                    : verdict === "mismatch"
+                        ? "an entry for this host exists but carries a DIFFERENT key"
+                        : `no usable entry for ${knownHostsPatternsFor(host, port).join(" / ")} (hashed "|1|" lines, wildcard patterns and @cert-authority entries are deliberately NOT supported — see SshHostKeyPolicy)`;
+                return {
+                    ok: false,
+                    reason: `SSH host key rejected for ${host}:${port} — ${why}. presented=${presented} source=SSH_KNOWN_HOSTS:${knownHostsPath}. ` +
+                        keyscanHint(host, port),
+                };
+            }
+        }
+        return { ok: true, verified: true };
+    };
+}
+//# sourceMappingURL=ssh-host-key.js.map