@sema-agent/server 7.146.0 → 7.147.0

package/dist/plugins/remote-shell.js

@@ -1,6 +1,8 @@
 import { ExecutionError, FileError, SYMLINK_CHAIN_MAX_HOPS } from "@sema-agent/core";
 import { NAME_MAX_BYTES, classifyFsStderr, fileErrorFromExec } from "./remote-env-file-error.js";
 import { recordFailOpen } from "../observability/fail-open.js";
+import { createLogger } from "../observability/logger.js";
+import { seatText } from "../trace/exit-seat.js";
 import { randomBytes } from "node:crypto";
 export const EXEC_FORCE_SETTLE_GRACE_MS = 3000;
 export function armPipeDestroyGrace(child) {
@@ -157,8 +159,11 @@ export async function runSymlinkChain(absPath, run) {
 const STAGED_FILE = "data";
 const STAGE_DIR_REFUSED_EXIT = 3;
 const STAGE_DIR_UNSEALED_EXIT = 4;
-const STAGE_DIR_UNSEALED_MESSAGE = "sema: the private staging directory could not be made private (chmod 700 failed or did not take effect, the mode or owner read back differently, or an inherited ACL entry could not be removed or read on this platform — the filesystem ignores permission bits or the parent directory carries a default or inheritable ACL); nothing was staged";
+const STAGE_DIR_UNSEALED_REASON = "chmod 700 failed or did not take effect, the mode or owner read back differently, or an inherited ACL entry could not be removed or read on this platform — the filesystem ignores permission bits or the parent directory carries a default or inheritable ACL";
+const STAGE_DIR_UNSEALED_MESSAGE = `sema: the private staging directory could not be made private (${STAGE_DIR_UNSEALED_REASON}); nothing was staged`;
+const RESTAGE_DIR_UNSEALED_MESSAGE = `sema: the private staging directory beside the link's target could not be made private (${STAGE_DIR_UNSEALED_REASON}); the target was not touched`;
 export const STAGE_DIR_LEFT_MARK = "sema: staging directory left behind:";
+export const STAGE_MODE_NOT_CARRIED_MARK = "sema: file mode not carried:";
 export function buildStagingPaths(abs, nonce = randomBytes(6).toString("hex")) {
     const cut = abs.lastIndexOf("/");
     const parent = abs.slice(0, cut + 1);
@@ -172,9 +177,11 @@ export function buildStagingPaths(abs, nonce = randomBytes(6).toString("hex")) {
 function privateMkdir(dir) {
     return `(umask 077 && mkdir -- ${dir})`;
 }
+function readModeOwner(path) {
+    return `l=$(ls -ldn -- ${path} 2>/dev/null) && set -f && set -- $l && [ -n "$3" ]`;
+}
 function hardenPrivate(dir) {
-    const statOf = (gnu, bsd) => `$(stat -c ${gnu} -- ${dir} 2>/dev/null || stat -f ${bsd} -- ${dir} 2>/dev/null)`;
-    return `( chmod -- 700 ${dir} 2>/dev/null && m=${statOf("%a", "%Lp")} && u=${statOf("%u", "%u")} && case "$m" in 700|[1-7]700) [ "$u" = "$(id -u)" ];; *) false;; esac && ${aclCleared(dir)} )`;
+    return `( chmod -- 700 ${dir} 2>/dev/null && ${readModeOwner(dir)} && case "$1" in drw[xs]--[-S]--[-T]*) [ "$3" = "$(id -u)" ];; *) false;; esac && ${aclCleared(dir)} )`;
 }
 function aclCleared(dir) {
     const marker = `ls_out=$(cd ${dir} && ls -ld . 2>&1) && [ -z "$(printf '%s\\n' "$ls_out" | sed -n 2p)" ] && mode_word=\${ls_out%% *} && ` +
@@ -189,9 +196,6 @@ function aclCleared(dir) {
 function emptyPrivate(dir) {
     return `[ ! -e ${dir}/${STAGED_FILE} ] && [ ! -L ${dir}/${STAGED_FILE} ]`;
 }
-function sealPrivate(dir) {
-    return `${hardenPrivate(dir)} && ${emptyPrivate(dir)}`;
-}
 function removalOf(dir) {
     return `{ [ ! -L ${dir} ] && rm -f -- ${dir}/${STAGED_FILE} && { rmdir -- ${dir} 2>/dev/null || [ ! -e ${dir} ]; }; }`;
 }
@@ -213,21 +217,31 @@ export function buildStagingPrepareCommand(stage) {
 }
 function takeAndWrite(redirect) {
     return (`[ -r "$s" ] || chmod -- u+r "$s" 2>/dev/null; exec 3< "$s" || exit 1; { [ ! -L "$d" ] && rm -f -- "$s"; } || { ${leftMark(`"$d"`)}; exit 1; }; ` +
-        `cat <&3 ${redirect} "$t"; w=$?; exec 3<&-; ${removePrivate(`"$d"`)}; exit $w; `);
+        `cat <&3 ${redirect} "$t"; w=$?; [ "$w" -eq 0 ] || w=1; exec 3<&-; ${removePrivate(`"$d"`)}; exit $w; `);
+}
+function carryMode(src, dst) {
+    const digit = `perm_digit() { case "$1" in ---|--S|--T) echo 0;; --x|--s|--t) echo 1;; -w-|-wS|-wT) echo 2;; -wx|-ws|-wt) echo 3;; ` +
+        `r--|r-S|r-T) echo 4;; r-x|r-s|r-t) echo 5;; rw-|rwS|rwT) echo 6;; rwx|rws|rwt) echo 7;; *) return 1;; esac; }`;
+    const triples = `m=\${1#?} && pu=\${m%"\${m#???}"} && m=\${m#???} && pg=\${m%"\${m#???}"} && m=\${m#???} && po=\${m%"\${m#???}"}`;
+    const special = `sp=0; case "$pu" in ??[sS]) sp=4;; esac; case "$pg" in ??[sS]) sp=$((sp+2));; esac; case "$po" in ??[tT]) sp=$((sp+1));; esac`;
+    return (`( if ${readModeOwner(src)}; then ${digit} && ${triples} && du=$(perm_digit "$pu") && dg=$(perm_digit "$pg") && do_=$(perm_digit "$po") && ` +
+        `{ ${special}; chmod "$sp$du$dg$do_" ${dst}; } && exit 0; printf '%s' "$1"; fi; exit 1 ) 2>/dev/null`);
 }
 export function buildStagedCommitCommand(stage, target) {
     return (`{ d=${shellQuote(stage.dir)}; s="$d/${STAGED_FILE}"; t=${shellQuote(target)}; ` +
-        `if [ -L "$t" ]; then h=$(readlink -n -- "$t" && printf .) || h=; h=\${h%.}; ` +
+        `if [ -L "$t" ]; then nl=$(printf '\\n.'); nl=\${nl%.}; h=$(readlink -- "$t" && printf .) || h=; h=\${h%.}; h=\${h%"$nl"}; ` +
         `case "$h" in "") ;; /*) ;; *) l="\${t%/*}"; case "$l" in "") h="/$h" ;; */) h="$l$h" ;; *) h="$l/$h" ;; esac ;; esac; ` +
-        `if [ -n "$h" ] && [ ! -L "$h" ] && { [ ! -e "$h" ] || [ -f "$h" ]; }; then t="$h"; fi; fi; ` +
+        `if [ -n "$h" ] && [ ! -L "$h" ] && [ -f "$h" ] && [ ! -e "$h$nl" ] && [ ! -L "$h$nl" ] && [ "$h" -ef "$t" ]; then t="$h"; fi; fi; ` +
         `if [ ! -L "$t" ] && { [ ! -e "$t" ] || [ -f "$t" ]; }; then ` +
         `if [ "\${t%/*}" != "\${d%/*}" ]; then e="\${t%/*}/\${d##*/}"; ` +
         `if { ${privateMkdir(`"$e"`)}; } 2>/dev/null; then ` +
-        `if { ${sealPrivate(`"$e"`)}; } 2>/dev/null; then ` +
+        `if { ${hardenPrivate(`"$e"`)}; } 2>/dev/null; then ` +
+        `if { ${emptyPrivate(`"$e"`)}; } 2>/dev/null; then ` +
         `if cat -- "$s" > "$e/${STAGED_FILE}" 2>/dev/null; then o="$d"; d="$e"; s="$e/${STAGED_FILE}"; ${removePrivate(`"$o"`)}; else ${removePrivate(`"$e"`)}; fi; ` +
-        `else ${abandonPrivate(`"$e"`)}; fi; fi; fi; ` +
-        `if [ -f "$t" ]; then m=$(stat -c %a -- "$t" 2>/dev/null || stat -f %Lp -- "$t" 2>/dev/null) && chmod "$m" "$s" 2>/dev/null; fi; ` +
-        `if mv -f -- "$s" "$t" 2>/dev/null; then ${removePrivate(`"$d"`)}; exit 0; fi; fi; ` +
+        `else ${abandonPrivate(`"$e"`)}; fi; ` +
+        `else ${abandonPrivate(`"$e"`)}; printf '%s\\n' ${shellQuote(RESTAGE_DIR_UNSEALED_MESSAGE)} >&2; exit ${STAGE_DIR_UNSEALED_EXIT}; fi; fi; fi; ` +
+        `carry_mode() { ${carryMode('"$t"', '"$s"')}; }; cm=-; if [ -f "$t" ]; then cm=$(carry_mode) && cm=-; fi; ` +
+        `if mv -f -- "$s" "$t" 2>/dev/null; then [ "$cm" = - ] || printf '%s %s\\0' ${shellQuote(STAGE_MODE_NOT_CARRIED_MARK)} "$cm"; ${removePrivate(`"$d"`)}; exit 0; fi; fi; ` +
         `${takeAndWrite(">")}}`);
 }
 export function buildStagedAppendCommand(stage, target) {
@@ -236,14 +250,77 @@ export function buildStagedAppendCommand(stage, target) {
 export function buildStagingDiscardCommand(stage) {
     return removalOf(shellQuote(stage.dir));
 }
-async function discardStaged(lane, stage) {
-    const r = await lane.run(buildStagingDiscardCommand(stage));
+export function readyUpload(upload) {
+    return async () => ({ ok: true, value: { upload } });
+}
+async function cleanOnce(lane, cmd, fallbackWhy) {
+    const r = await lane.run(cmd);
     if (!r.ok)
         return r.error.message;
-    return r.value.exitCode === 0 ? undefined : r.value.stderr.trim() || "it holds something this write did not put there, or it was replaced by a link";
+    return r.value.exitCode === 0 ? undefined : r.value.stderr.trim() || fallbackWhy;
+}
+function scriptRecordsOf(stdout) {
+    const heads = [
+        { kind: "left", head: `${STAGE_DIR_LEFT_MARK} ` },
+        { kind: "mode", head: `${STAGE_MODE_NOT_CARRIED_MARK} ` },
+    ];
+    const leftDirs = [];
+    let modeNotCarried;
+    for (const rec of stdout.split("\0")) {
+        let first;
+        for (const { kind, head } of heads) {
+            const at = rec.indexOf(head);
+            if (at >= 0 && (first === undefined || at < first.at))
+                first = { kind, at, head };
+        }
+        if (first === undefined)
+            continue;
+        const value = rec.slice(first.at + first.head.length);
+        switch (first.kind) {
+            case "left":
+                leftDirs.push(value);
+                break;
+            case "mode":
+                modeNotCarried = value;
+                break;
+            default: {
+                const unreachable = first.kind;
+                throw new Error(`unhandled script record kind ${String(unreachable)}`);
+            }
+        }
+    }
+    return { leftDirs, modeNotCarried };
+}
+async function settleStaging(lane, stage, named, discardOriginal) {
+    const todo = new Map();
+    if (discardOriginal)
+        todo.set(stage.dir, { cmd: buildStagingDiscardCommand(stage), why: "it holds something this write did not put there, or it was replaced by a link" });
+    const name = stage.dir.slice(stage.dir.lastIndexOf("/") + 1);
+    for (const dir of named) {
+        if (todo.has(dir))
+            continue;
+        const faithful = dir.endsWith(`/${name}`) && !dir.includes("\uFFFD");
+        todo.set(dir, faithful ? { cmd: reapCommandOf(dir), why: "it still holds an entry, or it was replaced by a link" } : { cmd: undefined, why: "the script named a directory that is not this write's staging directory under a path that can be trusted; left alone" });
+    }
+    const left = [];
+    for (const [dir, { cmd, why }] of todo) {
+        const still = cmd === undefined ? why : await cleanOnce(lane, cmd, why);
+        if (still === undefined)
+            continue;
+        left.push({ dir, why: still });
+        recordFailOpen("server.remote-write.staging-dir-left", dir);
+    }
+    return left;
 }
-function withResidue(e, stage, why) {
-    return why === undefined ? e : new FileError(e.code, `${e.message} (the staging directory ${stage.dir} could not be removed: ${why})`, e.path, e);
+function reapCommandOf(dir) {
+    const d = shellQuote(dir);
+    return `{ rmdir -- ${d} 2>/dev/null || { [ ! -e ${d} ] && [ ! -L ${d} ]; }; }`;
+}
+function withResidue(e, left) {
+    if (left.length === 0)
+        return e;
+    const named = left.length === 1 ? `the staging directory ${left[0].dir}` : `the staging directories ${left.map((l) => l.dir).join(", ")}`;
+    return new FileError(e.code, `${e.message} (${named} could not be removed: ${left.map((l) => l.why).join("; ")})`, e.path, e);
 }
 async function landStaged(lane, abs, abortSignal, commitOf, direct) {
     if (abortSignal?.aborted)
@@ -251,78 +328,114 @@ async function landStaged(lane, abs, abortSignal, commitOf, direct) {
     const stage = buildStagingPaths(abs);
     const prep = await lane.run(buildStagingPrepareCommand(stage), abortSignal);
     if (!prep.ok) {
-        const left = await discardStaged(lane, stage);
-        return { ok: false, error: withResidue(fileErrorFromExec(prep.error, abs), stage, left) };
+        const left = await settleStaging(lane, stage, [], true);
+        return { ok: false, error: withResidue(fileErrorFromExec(prep.error, abs), left) };
     }
     if (prep.value.exitCode !== 0) {
-        noteLeftDirs(prep.value.stdout);
+        const left = await settleStaging(lane, stage, scriptRecordsOf(prep.value.stdout).leftDirs, false);
         if (abortSignal?.aborted)
-            return { ok: false, error: new FileError("aborted", "aborted before the write started; the target was not touched", abs) };
+            return { ok: false, error: withResidue(new FileError("aborted", "aborted before the write started; the target was not touched", abs), left) };
         const e = classifyFsStderr(prep.value.stderr, abs, "unknown");
         if (prep.value.exitCode === STAGE_DIR_REFUSED_EXIT && e.code === "permission_denied")
-            return direct(createDirectContext(abs, abortSignal, "the directory does not accept new names"));
+            return viaDirect(direct, abs, abortSignal, "the directory does not accept new names", left);
         if (prep.value.exitCode === STAGE_DIR_UNSEALED_EXIT) {
             recordFailOpen("server.remote-write.stage-seal-fallback", `${abs}: ${prep.value.stderr.trim()}`);
-            return direct(createDirectContext(abs, abortSignal, "the private staging directory could not be made private"));
+            return viaDirect(direct, abs, abortSignal, "the private staging directory could not be made private", left);
         }
-        return { ok: false, error: e };
+        return { ok: false, error: withResidue(e, left) };
     }
     if (abortSignal?.aborted) {
-        const left = await discardStaged(lane, stage);
-        return { ok: false, error: withResidue(new FileError("aborted", "aborted before the write started; the target was not touched", abs), stage, left) };
+        const left = await settleStaging(lane, stage, [], true);
+        return { ok: false, error: withResidue(new FileError("aborted", "aborted before the write started; the target was not touched", abs), left) };
+    }
+    const piece = await lane.prepare(abortSignal);
+    if (!piece.ok) {
+        const left = await settleStaging(lane, stage, [], true);
+        return { ok: false, error: withResidue(piece.error, left) };
+    }
+    let up;
+    try {
+        up = abortSignal?.aborted ? { ok: false, error: new FileError("aborted", "aborted before the write started; the target was not touched", abs) } : await piece.value.upload(stage.file, abortSignal);
+    }
+    finally {
+        await piece.value.release?.();
     }
-    const up = await lane.upload(stage.file, abortSignal);
     if (!up.ok) {
-        const left = await discardStaged(lane, stage);
-        return { ok: false, error: withResidue(up.error, stage, left) };
+        const left = await settleStaging(lane, stage, [], true);
+        return { ok: false, error: withResidue(up.error, left) };
     }
     if (abortSignal?.aborted) {
-        const left = await discardStaged(lane, stage);
-        return { ok: false, error: withResidue(new FileError("aborted", "aborted before the commit; the target was not touched", abs), stage, left) };
+        const left = await settleStaging(lane, stage, [], true);
+        return { ok: false, error: withResidue(new FileError("aborted", "aborted before the commit; the target was not touched", abs), left) };
     }
     const c = await lane.run(commitOf(stage));
     if (!c.ok) {
-        const left = await discardStaged(lane, stage);
+        const left = await settleStaging(lane, stage, [], true);
         const e = fileErrorFromExec(c.error, abs);
-        return { ok: false, error: withResidue(new FileError("unknown", `${e.message} (the commit's round trip failed, so whether it ran is unknown — re-read the target before retrying)`, abs, e), stage, left) };
+        return { ok: false, error: withResidue(new FileError("unknown", `${e.message} (the commit's round trip failed, so whether it ran is unknown — re-read the target before retrying)`, abs, e), left) };
+    }
+    if (c.value.exitCode === STAGE_DIR_UNSEALED_EXIT) {
+        const left = await settleStaging(lane, stage, scriptRecordsOf(c.value.stdout).leftDirs, true);
+        if (abortSignal?.aborted)
+            return { ok: false, error: withResidue(new FileError("aborted", "aborted before the write started; the target was not touched", abs), left) };
+        recordFailOpen("server.remote-write.stage-seal-fallback", `${abs}: ${c.value.stderr.trim()}`);
+        return viaDirect(direct, abs, abortSignal, "the private staging directory could not be made private", left);
     }
-    noteLeftDirs(c.value.stdout);
     if (c.value.exitCode !== 0) {
-        const left = await discardStaged(lane, stage);
-        return { ok: false, error: withResidue(classifyFsStderr(c.value.stderr, abs, "unknown"), stage, left) };
+        const left = await settleStaging(lane, stage, scriptRecordsOf(c.value.stdout).leftDirs, true);
+        return { ok: false, error: withResidue(classifyFsStderr(c.value.stderr, abs, "unknown"), left) };
+    }
+    const records = scriptRecordsOf(c.value.stdout);
+    await settleStaging(lane, stage, records.leftDirs, false);
+    if (records.modeNotCarried !== undefined) {
+        (lane.logger ?? fallbackLaneLogger()).warn("remote_env_file_mode_failed", {
+            provider: lane.provider,
+            path: seatText("operator-log-arg", abs),
+            ...(records.modeNotCarried !== "" ? { mode: seatText("operator-log-text", records.modeNotCarried) } : {}),
+            error: records.modeNotCarried !== "" ? "the target machine refused to set the target's mode on the replacement" : "the target's mode could not be read",
+            effect: "the new bytes are in place; the target's previous mode bits were not carried over, so it now has the mode the replacement was created with (setting the mode is best effort)",
+        });
     }
     return { ok: true, value: undefined };
 }
-function noteLeftDirs(stdout) {
-    const head = `${STAGE_DIR_LEFT_MARK} `;
-    for (const rec of stdout.split("\0")) {
-        const at = rec.indexOf(head);
-        if (at >= 0)
-            recordFailOpen("server.remote-write.staging-dir-left", rec.slice(at + head.length));
+let fallbackLogger;
+function fallbackLaneLogger() {
+    return (fallbackLogger ??= createLogger());
+}
+async function viaDirect(direct, abs, abortSignal, why, left) {
+    const r = await writeInPlace(direct, abs, abortSignal, why);
+    return r.ok ? r : { ok: false, error: withResidue(r.error, left) };
+}
+async function writeInPlace(direct, abs, abortSignal, why) {
+    const abortedBefore = () => ({ ok: false, error: new FileError("aborted", `aborted before the in-place write started (${why}); the target was not touched`, abs) });
+    if (abortSignal?.aborted)
+        return abortedBefore();
+    const piece = await direct(abortSignal);
+    if (!piece.ok)
+        return piece;
+    try {
+        if (abortSignal?.aborted)
+            return abortedBefore();
+        const r = await piece.value.upload(abs, abortSignal);
+        if (r.ok || r.error.code !== "aborted")
+            return r;
+        return { ok: false, error: new FileError("unknown", `cancelled during an in-place write (${why}, so the bytes went straight to the target); the target may be partially written — re-read it before retrying`, abs, r.error) };
+    }
+    finally {
+        await piece.value.release?.();
     }
 }
-function createDirectContext(abs, abortSignal, why) {
-    return {
-        signal: abortSignal,
-        inPlace: async (step) => {
-            if (abortSignal?.aborted)
-                return { ok: false, error: new FileError("aborted", `aborted before the in-place write started (${why}); the target was not touched`, abs) };
-            const r = await step(abortSignal);
-            if (r.ok || r.error.code !== "aborted")
-                return r;
-            return { ok: false, error: new FileError("unknown", `cancelled during an in-place write (${why}, so the bytes went straight to the target); the target may be partially written — re-read it before retrying`, abs, r.error) };
-        },
+export function rewriteAppend(read, prepareOf, add) {
+    return async (abortSignal) => {
+        const existing = await read(abortSignal);
+        if (!existing.ok && existing.error.code !== "not_found")
+            return existing;
+        const merged = Buffer.concat([existing.ok ? existing.value : new Uint8Array(0), typeof add === "string" ? Buffer.from(add, "utf8") : add]);
+        return prepareOf(merged)(abortSignal);
     };
 }
-export async function rewriteAppend(read, write, add, ctx) {
-    const existing = await read(ctx.signal);
-    if (!existing.ok && existing.error.code !== "not_found")
-        return existing;
-    const merged = Buffer.concat([existing.ok ? existing.value : new Uint8Array(0), typeof add === "string" ? Buffer.from(add, "utf8") : add]);
-    return ctx.inPlace((signal) => write(merged, signal));
-}
 export function writeFileStaged(lane, abs, abortSignal) {
-    return landStaged(lane, abs, abortSignal, (stage) => buildStagedCommitCommand(stage, abs), (ctx) => ctx.inPlace((signal) => lane.upload(abs, signal)));
+    return landStaged(lane, abs, abortSignal, (stage) => buildStagedCommitCommand(stage, abs), lane.prepare);
 }
 export function appendFileStaged(lane, abs, abortSignal, direct) {
     return landStaged(lane, abs, abortSignal, (stage) => buildStagedAppendCommand(stage, abs), direct);

package/dist/plugins/retention-declaration.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 托管留存的**声明词**(部署说的话):三只被托管的 SQL 店交给引擎的 `retention` 词,与「本部署跑不跑扫车道」这一个事实。
+ *
+ * 为什么不住在执行器文件里:执行器(`stores-sql/retention-store-sql.ts`)是阶段三逐字搬进引擎包的那一半;「这只店的行有没有人按期删」是**部署**知道的事
+ * (扫车道开不开),声明词由装配它的部署给 —— 引擎包里同一个事实读 `retention` 选项(必填,部署表态),不读店类常量。阶段三这两只常量随店类常量一起退役。
+ */
+import type { RetentionDeclaration } from "@sema-agent/core";
+/**
+ * 三只**被托管**的 SQL 店(session / checkpoint / tool-result)在扫车道开着时的 `retention` 声明常量。
+ *
+ * 🔴 **谁说这个词**(引擎 7.58.0 起:店说 `"managed"` 而部署不跑执行器 ⇒ 锁不锁都拒启):「这只店的行有没有人按期删」不是店类自己知道的事,
+ * 是装配它的部署知道的事。唯一事实 = 扫车道开不开({@link retentionSweepRuns});后端铸店时按它给词({@link sqlStoreRetention}),
+ * 交给引擎启动检查的执行器读同一个事实(开 ⇒ 执行器,关 ⇒ `null`)。店构造不给词 ⇒ `"none"`(引擎对缺席的同一读法)。
+ *
+ * 🔴 为什么是一个共享常量而不是各写各的字面量:这一格是 core `assertRetentionCapability` 的**唯一**读点,
+ * 三只店的答案必须同进同退 —— 哪天本能力从某只店的行上撤了(比如 tool_result 改由别处清),漏改一处
+ * 就是一句谎,而谎的方向是「locked policy 放行了一只其实不删的店」。
+ *
+ * 🔴 声明的**读法**(与 core 契约的字面对齐,别读大也别读小):`"managed"` 说的是「**这只店的行**由本
+ * 部署的托管留存按期删除」,不是「本对象自己实现了三个方法」。三方法的实现体是执行器
+ * `SqlRetentionStore`(`stores-sql/retention-store-sql.ts`)—— 它是 E21 purge 协调器的事务化孪生,横跨十余张表(部署那几张经它的事务内钩)。
+ * core 的门读的是「这只店的数据会不会被按期删掉」(拒启文案逐字:「a locked retention policy over stores
+ * that cannot delete would be *policy locked, data immortal*」),SQL 三店的诚实答案就是 `"managed"`。
+ * file/in-memory 形没有任何东西会按期删它们的行 ⇒ 显式 `"none"`(缺席也读 none,但显式是文档义务)。
+ */
+export declare const MANAGED_RETENTION: RetentionDeclaration;
+/** file/in-memory 形、以及扫车道关着的 SQL 店的诚实声明(见 {@link MANAGED_RETENTION} 的读法说明)。 */
+export declare const UNMANAGED_RETENTION: RetentionDeclaration;
+/** 本部署跑不跑托管留存的扫车道(`RETENTION_SWEEP_INTERVAL_SEC > 0`)—— 三只 SQL 店的声明与交给引擎启动检查的执行器只读这一处。 */
+export declare function retentionSweepRuns(sweep: {
+    readonly intervalSec: number;
+}): boolean;
+/** 后端铸三只被托管的 SQL 店时交给店的词:扫车道开 ⇒ `"managed"`,关 ⇒ `"none"`。 */
+export declare function sqlStoreRetention(sweep: {
+    readonly intervalSec: number;
+}): RetentionDeclaration;
+//# sourceMappingURL=retention-declaration.d.ts.map

package/dist/plugins/retention-declaration.js

@@ -0,0 +1,9 @@
+export const MANAGED_RETENTION = "managed";
+export const UNMANAGED_RETENTION = "none";
+export function retentionSweepRuns(sweep) {
+    return sweep.intervalSec > 0;
+}
+export function sqlStoreRetention(sweep) {
+    return retentionSweepRuns(sweep) ? MANAGED_RETENTION : UNMANAGED_RETENTION;
+}
+//# sourceMappingURL=retention-declaration.js.map

package/dist/plugins/retention-deployment.d.ts

@@ -0,0 +1,126 @@
+/**
+ * 托管留存的**部署那一半** —— 本仓的表经执行器(`stores-sql/retention-store-sql.ts`)的事务内钩表(K4)参与同一个破坏性事务。
+ * 执行器是事务属主(开 / 提交 / 回滚),只认 core 的 `{domain, cutoffMs}`;部署的事实(hold、审计行的判定时点三格、认领、十一张部署表、
+ * 结束了的空间)全在这里,经钩出场:
+ *   · `holdLock`(首句)  —— hold 哨兵行锁读(`retention-lane-store-sql.ts` 的 {@link lockHoldSentinel});
+ *   · `beforeDelete`(终集)—— 删十一张部署表里这批会话的行(下面 {@link deleteDeploymentSessionRows}),并按收到的
+ *     `{sessionId, incarnation}` 自算结束了的空间(一份来源:执行器交来的那批行,不再读第二份);
+ *   · `audit`(提交前末句)—— 破坏性审计行({@link appendDestructiveAuditRow}),判定时点三格是这一次调用的。
+ * 认领判(每只候选根的 `session.beforeCommit`)不在这里:它是会话座的钩(`plugins/session-store-sql.ts` 的 `createSqlSessionWriteHooks`,
+ * `retention-delete` 臂),组合座把同一只交给执行器 —— 一处实现。
+ * 钩只拿语句面(`query`),从不碰事务本身;库外副作用(回收空间)不在钩里做 —— 执行器提交成功返回之后,组合座把结束了的空间交给 lane。
+ *
+ * 钩表为什么**每次破坏性调用**铸一份(组合座 `plugins/store-backend.ts` 的 `createSqlRetentionExecutor`):审计行的 `{mode, policyDays,
+ * fencingToken}` 与 `checkpoint_ctx` 属主门要的域是**这一次调用**的事实,而 core 的钩签名不带它们(`audit` 收 `{domain, op}` 与回执,
+ * `beforeDelete` 只收行)。
+ *
+ * ── 方言差异(只列本文件独有的;其余见执行器顶注)──────────────────────────────────────────────────
+ *   - 级联 DELETE 的 JOIN 形:`DELETE te FROM a te JOIN b …` vs `DELETE FROM a te USING b …`
+ */
+import type { ManagedRetentionCapability, RetentionReceipt } from "@sema-agent/core";
+import type { SqlDialect, SqlExec } from "./sql-driver.js";
+import { type RetentionAuditContext } from "./retention-lane-store-sql.js";
+import type { EndedSpace } from "../workspace-space.js";
+/**
+ * lane 消费的**执行器**面 —— core `ManagedRetentionCapability` 的三方法 + 非契约窄读口 `previewRetention`
+ * (audit-only 档的读数源;core 契约无 count 面)+ 声明位。真身 = 组合座 `createSqlRetentionExecutor`。
+ *
+ * 🔴 三方法的入参是 core 契约形的**超集**(多一个必填的 `audit`):判定时点三格是部署的事实,组合座把它绑进这一次调用的 audit 钩
+ * —— 写进类型,让「忘了传」是编译错。
+ */
+export interface RetentionExecutor {
+    readonly retention?: "managed" | "none";
+    listRetentionDomains(): Promise<readonly string[]>;
+    previewRetention(input: {
+        domain: string;
+        cutoffMs: number;
+    }): Promise<{
+        checkpoints: number;
+        sessions: number;
+        toolResults: number;
+    }>;
+    expireCheckpoints(input: RetentionDestructiveInput): Promise<RetentionReceipt>;
+    deleteExpiredSessions(input: RetentionDestructiveInput): Promise<RetentionSessionsReceipt>;
+    deleteOrphanToolResults(input: RetentionDestructiveInput): Promise<RetentionReceipt>;
+}
+/** 破坏性调用的入参(判定时点的三格随行 —— 理由逐字见 {@link RetentionAuditContext} 的头注)。 */
+export interface RetentionDestructiveInput {
+    domain: string;
+    cutoffMs: number;
+    audit: RetentionAuditContext;
+}
+/**
+ * 会话树 sweep 的回执 = core 契约的 `RetentionReceipt` + 本仓一位:`endedSpaces` = 本次删掉的会话树里**结束了的空间**(会话 id + 住客空间键 = 会话化身;
+ * 读不出住客的空化身不算),present-iff 非空。lane 把它交给空间的回收座(与会话删除协调器同一只),缓存卷与快照随空间的终结回收。
+ */
+export type RetentionSessionsReceipt = RetentionReceipt & {
+    readonly endedSpaces?: readonly EndedSpace[];
+};
+/** 装配面必须如实告知的**可选部署表在场性**(+ 执行器的诊断日志座)。 */
+export interface RetentionExecutorOptions {
+    /**
+     * `task_attachment` 表是否在场。**必填,没有默认值**:boot 只在配了对象存储时才 ensure 这张表
+     * (`boot/stores.ts` 的附件段:无 MinIO ⇒ 整段不接线、表不建),于是一条盲发的 DELETE 在无对象存储的
+     * 部署上会以 unknown-table 报错、把整轮 sweep 打红。让装配层如实回答,比让钩去吞一个错误好 —— 吞错误
+     * 就是静默 fail-open(附件行从此永不被留存清理,而没有任何人知道)。
+     */
+    taskAttachmentTable: boolean;
+    /**
+     * [ref] `task_list_meta` / `task_list_item` 两表是否在场。**必填,没有默认值**(与
+     * `taskAttachmentTable` 同一条理由:盲发 DELETE 会在没建表的库上把整轮 sweep 打红)。
+     * 生产上 `boot/task-list-lane.ts` 在**任何 SQL 后端**都无条件 ensure 这两张表 ⇒ 装配层照实传 true;
+     * 纯内存/local 车道压根没有 SQL 留存腿。
+     */
+    taskListTables: boolean;
+    /** 诊断日志座(可选;交给执行器)。 */
+    logger?: {
+        info?(msg: string, meta?: unknown): void;
+        warn?(msg: string, meta?: unknown): void;
+    };
+}
+/** 执行器会删东西的那几只成员(钩被告知的 `op`;与执行器钩表的同名型同读 core 的键集)。 */
+type RetentionOp = Exclude<keyof ManagedRetentionCapability, "listRetentionDomains">;
+/**
+ * 一次破坏性调用的钩表 + 它收集到的结束了的空间。`call` = 这一次调用(域与判定时点三格)。
+ * 钩的形对齐执行器的 `SqlTransactionHooks`(组合座把 `hooks` 交给执行器时由类型系统对表,形一分叉就编译红)。
+ */
+export declare function createRetentionDeploymentHooks(dialect: SqlDialect, opts: RetentionExecutorOptions, call: RetentionDestructiveInput): {
+    hooks: {
+        retention: {
+            holdLock: (txn: SqlExec, at: {
+                readonly domain: string;
+                readonly op: RetentionOp;
+            }) => Promise<"proceed" | "held">;
+            beforeDelete: (txn: SqlExec, rows: readonly {
+                readonly sessionId: string;
+                readonly incarnation: string | undefined;
+            }[]) => Promise<void>;
+            audit: (txn: SqlExec, at: {
+                readonly domain: string;
+                readonly op: RetentionOp;
+            }, receipt: RetentionReceipt) => Promise<void>;
+        };
+    };
+    endedSpaces: () => readonly EndedSpace[];
+};
+/**
+ * 会话树里**部署表**这一半的删除(`beforeDelete` 钩的身体):十一张部署表,发在执行器事务的连接上,先于执行器删自己的表(K4 次序)。
+ * 表与相对次序与在线协调器(`boot/session-faces.ts` 的 `purgeSession`)同一条顺序契约;等价性由
+ * `retention-e21-equivalence-db-integration.test.ts` 的同种子剩余行集断言钉住(逐表比剩余行,与发语句的先后无关)。
+ * 次序的承重理由:
+ *   · `task_event` / `task_active` 经 `task_run` 连删 ⇒ 必须排在 `task_run` 删除**之前**;
+ *   · `checkpoint_ctx` 的属主门是 `session_meta.owner` 的 EXISTS 子查询 ⇒ 必须在 meta 删除之前(执行器的 meta 删除在本钩之后,天然满足);
+ *   · 任务清单:meta 行锁 → item → meta(与 `mutate` 同向的锁序,见该腿注)。
+ *
+ * 🔴 运行账本(task_event / task_active / task_run)**没有**属主门,按 `session_id` 单键删(F-A,2026-08-17
+ * 合并码扫描;与在线协调器同刀改):`task_run.owner` 是**每次提交的 principal**,与会话主会分叉(无主存量
+ * 会话被带 principal 的壳续聊 ⇒ 新行 owner="default")。行级属主门于是只删得掉半棵树,而 `session_meta`
+ * 在同一事务里随后就删掉 ⇒ 执行器的候选读从此**永远枚举不到**这些行:它们不是
+ * "下一轮再清",是**没有任何清理路径**的孤儿。域隔离不靠这道门承担 —— `ids` 已经是**本域** session_meta
+ * 里选出来并 `FOR UPDATE` 锁住的终集,行级门去掉之后越域仍然结构上不可能。
+ *
+ * `checkpoint_ctx` 的属主门用**域键**(`domain`,`""` = 无主桶)而不是会话的 owner 值 —— 理由逐字见执行器 `purgeSessionTrees` 头注「有意改写」段。
+ */
+export declare function deleteDeploymentSessionRows(txn: SqlExec, dialect: SqlDialect, domain: string, ids: readonly string[], opts: RetentionExecutorOptions): Promise<void>;
+export {};
+//# sourceMappingURL=retention-deployment.d.ts.map

package/dist/plugins/retention-deployment.js

@@ -0,0 +1,88 @@
+import { TASK_LIST_ITEM_TABLE, TASK_LIST_META_TABLE, taskListKeyFor } from "./task-list-store-sql.js";
+import { USER_INPUT_ACCEPTANCE_TABLE } from "./user-input-ledger-sql.js";
+import { retentionDomainWhere, retentionIdSet } from "./retention-sql.js";
+import { appendDestructiveAuditRow, lockHoldSentinel } from "./retention-lane-store-sql.js";
+function auditActionOf(op) {
+    switch (op) {
+        case "expireCheckpoints":
+            return "expired_checkpoints";
+        case "deleteExpiredSessions":
+            return "deleted_sessions";
+        case "deleteOrphanToolResults":
+            return "deleted_tool_results";
+    }
+}
+function endedSpacesOf(rows) {
+    return rows.flatMap((r) => (r.incarnation === undefined ? [] : [{ sessionId: r.sessionId, spaceKey: r.incarnation }]));
+}
+export function createRetentionDeploymentHooks(dialect, opts, call) {
+    if (!call.audit) {
+        throw new Error(`retention: refusing a destructive call in domain ${JSON.stringify(call.domain)} with no audit context — every destructive retention ` +
+            `transaction must persist its {mode, policyDays, fencingToken} alongside the deletion. Pass \`audit\` from the sweep lane's current round.`);
+    }
+    const ended = [];
+    const hooks = {
+        retention: {
+            holdLock: async (txn, at) => (await lockHoldSentinel(txn, dialect, at.domain)) ? "held" : "proceed",
+            beforeDelete: async (txn, rows) => {
+                await deleteDeploymentSessionRows(txn, dialect, call.domain, rows.map((r) => r.sessionId), opts);
+                ended.push(...endedSpacesOf(rows));
+            },
+            audit: async (txn, at, receipt) => appendDestructiveAuditRow(txn, dialect, {
+                domain: at.domain,
+                action: auditActionOf(at.op),
+                audit: call.audit,
+                deleted: receipt.deleted,
+                skipped: receipt.skipped,
+                tombstones: receipt.tombstones,
+            }),
+        },
+    };
+    return { hooks, endedSpaces: () => ended };
+}
+export async function deleteDeploymentSessionRows(txn, dialect, domain, ids, opts) {
+    const q = (mysql, pg) => (dialect === "mysql" ? mysql : pg);
+    const set = (col, pgIndex) => retentionIdSet(dialect, col, ids, pgIndex);
+    {
+        const s = set("tr.session_id", 1);
+        await txn.query(q(`DELETE te FROM task_event te JOIN task_run tr ON te.task_id = tr.task_id WHERE ${s.sql}`, `DELETE FROM task_event te USING task_run tr WHERE te.task_id = tr.task_id AND ${s.sql}`), [...s.params]);
+    }
+    {
+        const s = set("tr.session_id", 1);
+        await txn.query(q(`DELETE ta FROM task_active ta JOIN task_run tr ON ta.task_id = tr.task_id WHERE ${s.sql}`, `DELETE FROM task_active ta USING task_run tr WHERE ta.task_id = tr.task_id AND ${s.sql}`), [...s.params]);
+    }
+    {
+        const s = set("session_id", 1);
+        await txn.query(`DELETE FROM task_run WHERE ${s.sql}`, [...s.params]);
+    }
+    {
+        const s = set("checkpoint_ctx.session_id", 1);
+        const w = retentionDomainWhere(dialect, "sm.owner", domain, 2);
+        await txn.query(`DELETE FROM checkpoint_ctx WHERE ${s.sql} AND EXISTS (SELECT 1 FROM session_meta sm WHERE sm.session_id = checkpoint_ctx.session_id AND ${w.sql})`, [...s.params, ...w.params]);
+    }
+    for (const [table, col] of [
+        ["resume_anchor", "session_id"],
+        ["approval_exemption", "session_id"],
+        ...(opts.taskAttachmentTable ? [["task_attachment", "session_id"]] : []),
+        [USER_INPUT_ACCEPTANCE_TABLE, "session_id"],
+    ]) {
+        const s = set(col, 1);
+        await txn.query(`DELETE FROM ${table} WHERE ${s.sql}`, s.params);
+    }
+    if (opts.taskListTables) {
+        const listKeys = ids.map((id) => taskListKeyFor(id)).sort();
+        {
+            const s = retentionIdSet(dialect, "list_key", listKeys, 1);
+            await txn.query(`SELECT list_key FROM ${TASK_LIST_META_TABLE} WHERE ${s.sql} ORDER BY list_key FOR UPDATE`, s.params);
+        }
+        for (const table of [TASK_LIST_ITEM_TABLE, TASK_LIST_META_TABLE]) {
+            const s = retentionIdSet(dialect, "list_key", listKeys, 1);
+            await txn.query(`DELETE FROM ${table} WHERE ${s.sql}`, s.params);
+        }
+    }
+    {
+        const s = set("session_id", 1);
+        await txn.query(`DELETE FROM workflow_completion_inbox WHERE ${s.sql}`, s.params);
+    }
+}
+//# sourceMappingURL=retention-deployment.js.map