@sema-agent/server 7.146.0 → 7.148.0

package/dist/plugins/local-checkpoint-store.js

@@ -1,24 +1,66 @@
+import { writeLogText } from "../observability/logger.js";
 import { z } from "zod";
 import { denySweepOwns, parkedApprovalCard } from "../approval-content-kind.js";
 import { parkRowFacts, skillCardFacts } from "../approval-card.js";
 import { durableRowIdentity } from "../checkpoint-identity.js";
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync, readdirSync, unlinkSync, mkdirSync } from "node:fs";
+import { closeSync, existsSync, fsyncSync, openSync, readFileSync, readdirSync, rmSync, unlinkSync } from "node:fs";
+import { IS_WIN32 } from "./host-platform.js";
 import { join } from "node:path";
-import { CHECKPOINT_LIST_LIMITS, FileCheckpointStore, atomicWriteFile, executionVerdict, sanitizePathComponent, } from "@sema-agent/core";
+import { CHECKPOINT_LIST_LIMITS, FileCheckpointStore, atomicWriteFile, checkpointDeadlinePassed, ensureDir, executionVerdict, sanitizePathComponent, } from "@sema-agent/core";
 import { approvalPayloadFingerprint } from "./approval-payload-fingerprint.js";
-import { approvalDecisionOfWinner, boundedRuleOffers, boundedToolInput, candidateIdentityOf, pendingRowPrecedes, queueRowGateKind, TERMINAL_BACKSTOP_MS, TERMINAL_GRACE_MS } from "./checkpoint-store-face.js";
+import { approvalDecisionOfWinner, boundedRuleOffers, boundedToolInput, candidateIdentityOf, DENY_SWEEP_PAGE_ROWS, isUnreadableSummaryForm, parkedLegTaskId, pendingRowPrecedes, queueRowGateKind, queueTriageOrder, readRiskDescriptorBody, TERMINAL_BACKSTOP_MS, TERMINAL_GRACE_MS, } from "./checkpoint-store-face.js";
 import { quarantineUnreadableSidecar } from "./local-sidecar-quarantine.js";
-import { createZodColumnReader, decodeJsonColumn, foldJsonColumn, readStringArrayColumn } from "./sql-json-column.js";
-import { UNMANAGED_RETENTION } from "./retention-store-sql.js";
+import { hostSessionOf } from "./checkpoint-index-columns.js";
+import { createZodColumnReader, decodeJsonColumn, foldJsonColumn, isJsonObject, readStringArrayColumn } from "./sql-json-column.js";
+import { UNMANAGED_RETENTION } from "./retention-declaration.js";
 import { assertJsonColumnWritable, createObjectColumnReader } from "./sql-json-column.js";
 import { FENCE_LANDED } from "./store-contracts.js";
+import { recordFailOpen } from "../observability/fail-open.js";
+const isFiniteNumber = (v) => typeof v === "number" && Number.isFinite(v);
 function terminalAtOf(cp) {
-    return Math.max(cp.createdAt + TERMINAL_BACKSTOP_MS, (cp.deadline ?? 0) + TERMINAL_GRACE_MS);
+    const createdAt = cp.createdAt;
+    const deadline = cp.deadline;
+    const deadlineTerm = deadline === undefined ? 0 : isFiniteNumber(deadline) ? deadline : undefined;
+    if (!isFiniteNumber(createdAt) || deadlineTerm === undefined)
+        return -Infinity;
+    return Math.max(createdAt + TERMINAL_BACKSTOP_MS, deadlineTerm + TERMINAL_GRACE_MS);
+}
+function sweepDeadlineKey(deadline) {
+    return isFiniteNumber(deadline) ? deadline : -Infinity;
+}
+function sweepPositionPrecedes(a, b) {
+    return a.deadline < b.deadline || (a.deadline === b.deadline && a.token < b.token);
+}
+function queueRiskDescriptorOf(gate) {
+    const raw = isJsonObject(gate) ? gate.riskDescriptor : undefined;
+    if (raw === undefined || raw === null)
+        return null;
+    const shape = readRiskDescriptorBody(raw);
+    if (shape.problem === undefined)
+        return shape.value;
+    recordFailOpen("server.approvals.risk-descriptor-cell-unreadable");
+    return null;
 }
 function ctxFileOf(sessionId) {
     return `${sanitizePathComponent(sessionId).slice(0, 48)}-${createHash("sha256").update(sessionId).digest("hex").slice(0, 12)}.json`;
 }
+export function dropLocalCheckpointCtxStrict(root, sessionId) {
+    const dir = localCheckpointStoreDirsFor(root).ctx;
+    const path = join(dir, ctxFileOf(sessionId));
+    if (!existsSync(path))
+        return;
+    rmSync(path, { force: true });
+    if (IS_WIN32)
+        return;
+    const fd = openSync(dir, "r");
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
 const CtxRecordSchema = z.object({
     sessionId: z.string(),
     updatedAt: z.number(),
@@ -47,6 +89,9 @@ function refusingCtx(sessionId, read) {
         throw foldJsonColumn(e, (m) => `LocalCheckpointStore: ${m} — refusing rather than serve a resume context nobody can read (session ${JSON.stringify(sessionId)})`);
     }
 }
+export function localCheckpointStoreDirsFor(root) {
+    return { ctx: join(root, "checkpoint-ctx"), tmp: join(root, ".tmp") };
+}
 export class LocalCheckpointStore {
     retention = UNMANAGED_RETENTION;
     durability = "durable";
@@ -59,16 +104,21 @@ export class LocalCheckpointStore {
     tmpDir;
     scopes = new Set();
     sessionTokens = new Map();
+    hostTokens = new Map();
+    hostOfToken = new Map();
+    hostSessionsPath;
     opts;
     constructor(root, opts = {}) {
         this.inner = new FileCheckpointStore(root);
         this.opts = opts;
         this.scopesPath = join(root, "checkpoint-scopes.json");
         this.sessionTokensPath = join(root, "checkpoint-session-tokens.json");
-        this.ctxDir = join(root, "checkpoint-ctx");
-        this.tmpDir = join(root, ".tmp");
-        mkdirSync(this.ctxDir, { recursive: true });
-        mkdirSync(this.tmpDir, { recursive: true });
+        this.hostSessionsPath = join(root, "checkpoint-host-sessions.json");
+        const dirs = localCheckpointStoreDirsFor(root);
+        this.ctxDir = dirs.ctx;
+        this.tmpDir = dirs.tmp;
+        ensureDir(this.ctxDir);
+        ensureDir(this.tmpDir);
         if (existsSync(this.scopesPath)) {
             try {
                 for (const s of decodeJsonColumn(readFileSync(this.scopesPath, "utf8"), readScopeRegistry, "checkpoint-scopes.json (the local scope registry)"))
@@ -77,7 +127,7 @@ export class LocalCheckpointStore {
             catch (e) {
                 quarantineUnreadableSidecar(this.scopesPath, "LocalCheckpointStore scope registry", e instanceof Error ? e.message : String(e));
                 this.scopeRegistryCorrupt = true;
-                console.warn("LocalCheckpointStore: will rebuild the scope set from the data plane on first read (core listScopes) — enumeration is EMPTY until then");
+                writeLogText("stderr", "LocalCheckpointStore: will rebuild the scope set from the data plane on first read (core listScopes) — enumeration is EMPTY until then");
             }
         }
         if (existsSync(this.sessionTokensPath)) {
@@ -90,21 +140,66 @@ export class LocalCheckpointStore {
                 quarantineUnreadableSidecar(this.sessionTokensPath, "LocalCheckpointStore session→tokens index", e instanceof Error ? e.message : String(e));
             }
         }
+        if (existsSync(this.hostSessionsPath)) {
+            for (const [host, toks] of Object.entries(decodeJsonColumn(readFileSync(this.hostSessionsPath, "utf8"), readSessionTokenIndex, "checkpoint-host-sessions.json (the local card→host-session index)"))) {
+                this.indexHost(host, toks);
+            }
+        }
+    }
+    registerDurably(record, undo, persist) {
+        if (!record())
+            return;
+        try {
+            persist();
+        }
+        catch (e) {
+            undo();
+            throw e;
+        }
+    }
+    indexHost(host, tokens) {
+        let added = 0;
+        for (const t of tokens) {
+            if (this.hostOfToken.has(t))
+                continue;
+            const set = this.hostTokens.get(host) ?? new Set();
+            set.add(t);
+            this.hostTokens.set(host, set);
+            this.hostOfToken.set(t, host);
+            added += 1;
+        }
+        return added;
+    }
+    unindexHost(host, token) {
+        const set = this.hostTokens.get(host);
+        set?.delete(token);
+        if (set?.size === 0)
+            this.hostTokens.delete(host);
+        this.hostOfToken.delete(token);
+    }
+    persistHostSessions() {
+        atomicWriteFile(this.tmpDir, this.hostSessionsPath, JSON.stringify(Object.fromEntries([...this.hostTokens].map(([host, set]) => [host, [...set]]))));
     }
     persistSessionTokens() {
         atomicWriteFile(this.tmpDir, this.sessionTokensPath, JSON.stringify(Object.fromEntries([...this.sessionTokens].map(([sid, set]) => [sid, [...set]]))));
     }
     async put(token, cp) {
-        if (!this.scopes.has(cp.scope)) {
-            this.scopes.add(cp.scope);
-            atomicWriteFile(this.tmpDir, this.scopesPath, JSON.stringify([...this.scopes]));
-        }
-        if (!this.sessionTokens.get(cp.sessionId)?.has(token)) {
+        const host = hostSessionOf(cp);
+        this.registerDurably(() => !this.scopes.has(cp.scope) && (this.scopes.add(cp.scope), true), () => this.scopes.delete(cp.scope), () => atomicWriteFile(this.tmpDir, this.scopesPath, JSON.stringify([...this.scopes])));
+        this.registerDurably(() => this.indexHost(host, [token]) > 0, () => this.unindexHost(host, token), () => this.persistHostSessions());
+        this.registerDurably(() => {
+            if (this.sessionTokens.get(cp.sessionId)?.has(token))
+                return false;
             const set = this.sessionTokens.get(cp.sessionId) ?? new Set();
             set.add(token);
             this.sessionTokens.set(cp.sessionId, set);
-            this.persistSessionTokens();
-        }
+            return true;
+        }, () => {
+            const set = this.sessionTokens.get(cp.sessionId);
+            set?.delete(token);
+            if (set?.size === 0)
+                this.sessionTokens.delete(cp.sessionId);
+        }, () => this.persistSessionTokens());
         return this.inner.put(token, cp);
     }
     get(token) {
@@ -146,7 +241,7 @@ export class LocalCheckpointStore {
             this.scopes.add(s);
         this.scopeRegistryCorrupt = false;
         atomicWriteFile(this.tmpDir, this.scopesPath, JSON.stringify([...this.scopes]));
-        console.warn(`LocalCheckpointStore: scope registry REBUILT from the data plane (${rebuilt.length} scope(s) with pending gates) — enumeration restored`);
+        writeLogText("stderr", `LocalCheckpointStore: scope registry REBUILT from the data plane (${rebuilt.length} scope(s) with pending gates) — enumeration restored`);
     }
     async pendings(scope) {
         await this.ensureScopesRebuilt();
@@ -185,26 +280,34 @@ export class LocalCheckpointStore {
     async listPending(scope) {
         const rows = [];
         for (const { token, cp, summary } of await this.pendings(scope)) {
-            const pa = cp.pendingAction;
-            const gate = cp.gate;
-            const gateKind = queueRowGateKind(gate?.kind);
+            const gateKind = queueRowGateKind(summary.gateKind);
             if (gateKind === undefined)
                 continue;
+            const joinKey = durableRowIdentity("approvals-queue", summary.checkpointId, token);
+            const host = this.hostOfToken.get(token);
+            const taskId = parkedLegTaskId(cp.state?.rowTaskId, host === undefined ? null : ((await this.opts.getActiveTaskId?.(host)) ?? null));
+            const createdAt = summary.createdAt !== undefined ? { createdAt: summary.createdAt } : {};
+            const deadline = summary.deadline ?? null;
+            if (isUnreadableSummaryForm(summary)) {
+                rows.push({ sessionId: summary.sessionId, ...joinKey, scope: summary.scope, toolName: null, toolCallId: null, gateKind, taskId, input: null, ...createdAt, deadline, riskDescriptor: null, rowVerdict: summary.rowVerdict });
+                continue;
+            }
+            const pa = cp.pendingAction;
             const toolCallId = pa?.toolCallId ?? null;
             rows.push({
-                sessionId: cp.sessionId,
-                ...durableRowIdentity("approvals-queue", cp.checkpointId, token),
-                scope: cp.scope,
+                sessionId: summary.sessionId,
+                ...joinKey,
+                scope: summary.scope,
                 toolName: pa?.toolName ?? null,
                 toolCallId,
                 ...(toolCallId !== null ? { boundCallId: toolCallId } : {}),
                 ...(pa?.boundInputHash !== undefined ? { boundInputHash: pa.boundInputHash } : {}),
                 gateKind,
-                taskId: (await this.opts.getActiveTaskId?.(cp.sessionId)) ?? null,
+                taskId,
                 input: boundedToolInput(pa?.args),
-                createdAt: cp.createdAt,
-                deadline: cp.deadline ?? null,
-                riskDescriptor: gate?.riskDescriptor ?? null,
+                ...createdAt,
+                deadline,
+                riskDescriptor: queueRiskDescriptorOf(cp.gate),
                 ...(() => {
                     const rs = boundedRuleOffers(pa?.ruleOffers);
                     return rs !== undefined ? { ruleOffers: rs } : {};
@@ -216,15 +319,18 @@ export class LocalCheckpointStore {
                 rowVerdict: summary.rowVerdict,
             });
         }
-        return rows.sort((a, b) => (b.riskDescriptor?.severity ?? 0) - (a.riskDescriptor?.severity ?? 0) || a.createdAt - b.createdAt);
+        return rows.sort(queueTriageOrder);
     }
     async findPendingTokenBySession(sessionId, scope, binding) {
-        return this.pickPendingRow(await this.sessionPendings(sessionId, scope || undefined), sessionId, binding)?.token ?? null;
+        return this.pickPendingRow(await this.axisPendings(sessionId, scope || undefined, binding), binding?.axis === "run" ? undefined : sessionId, binding)?.token ?? null;
+    }
+    axisPendings(sessionId, scope, binding) {
+        return binding?.axis === "run" ? this.runPendings(sessionId, scope) : this.sessionPendings(sessionId, scope);
     }
-    pickPendingRow(rows, sessionId, binding) {
+    pickPendingRow(rows, cardSessionId, binding) {
         let best;
         for (const row of rows) {
-            if (row.cp.sessionId !== sessionId)
+            if (cardSessionId !== undefined && row.cp.sessionId !== cardSessionId)
                 continue;
             if (binding?.gateKinds !== undefined) {
                 const kind = row.cp.gate?.kind;
@@ -236,30 +342,11 @@ export class LocalCheckpointStore {
         }
         return best;
     }
-    async hasExpiredBySession(sessionId) {
-        const tokens = this.sessionTokens.get(sessionId);
-        if (!tokens)
-            return false;
-        let pruned = false;
-        for (const t of [...tokens]) {
-            const cp = await this.inner.get(t);
-            if (!cp) {
-                tokens.delete(t);
-                pruned = true;
-                continue;
-            }
-            if (cp.status === "expired")
+    async hasExpiredForRun(runSessionId) {
+        for (const t of this.hostTokens.get(runSessionId) ?? []) {
+            if ((await this.inner.get(t))?.status === "expired")
                 return true;
         }
-        if (pruned) {
-            if (tokens.size === 0)
-                this.sessionTokens.delete(sessionId);
-            try {
-                this.persistSessionTokens();
-            }
-            catch {
-            }
-        }
         return false;
     }
     async findDecidedApprovalsForBinding(sessionId, boundCallId) {
@@ -311,34 +398,68 @@ export class LocalCheckpointStore {
         return (await this.inner.get(token))?.scope;
     }
     async peekPendingScope(sessionId, binding) {
-        return this.pickPendingRow(await this.sessionPendings(sessionId), sessionId, binding)?.cp.scope;
+        return this.pickPendingRow(await this.axisPendings(sessionId, undefined, binding), binding?.axis === "run" ? undefined : sessionId, binding)?.cp.scope;
+    }
+    async runPendings(runSessionId, scope) {
+        const out = [];
+        for (const token of this.hostTokens.get(runSessionId) ?? []) {
+            const cp = await this.inner.get(token);
+            if (cp === null || cp.status !== "pending" || (scope !== undefined && cp.scope !== scope))
+                continue;
+            out.push({ token, cp });
+        }
+        return out;
+    }
+    async hostSessionOfCard(token) {
+        const host = this.hostOfToken.get(token);
+        if (host !== undefined)
+            return host;
+        return (await this.inner.get(token)) === null ? undefined : null;
+    }
+    async backfillHostSessionsM49() {
+        let added = 0;
+        for (const [sessionId, toks] of this.sessionTokens)
+            added += this.indexHost(sessionId, toks);
+        for (const { token, cp } of await this.pendings())
+            added += this.indexHost(cp.sessionId, [token]);
+        if (added > 0)
+            this.persistHostSessions();
+        return added;
     }
     async reapExpired(cutoff) {
         let n = 0;
         for (const { token, cp } of await this.pendings()) {
-            const deadlineBranch = cp.deadline !== undefined && cp.deadline <= cutoff && !denySweepOwns(cp.gate);
+            const deadlineBranch = checkpointDeadlinePassed(cp.deadline, cutoff) && !denySweepOwns(cp.gate);
             const terminalBranch = terminalAtOf(cp) <= cutoff;
             if ((deadlineBranch || terminalBranch) && (await this.inner.expire(token, cp.scope)))
                 n++;
         }
         return n;
     }
-    async listExpiredApprovalGates(cutoff, limit = 100) {
+    async listExpiredApprovalGates(cutoff, limit = DENY_SWEEP_PAGE_ROWS, after) {
         const hits = [];
-        for (const { cp } of await this.pendings()) {
-            if (denySweepOwns(cp.gate) && cp.deadline !== undefined && cp.deadline <= cutoff)
-                hits.push({ sessionId: cp.sessionId, scope: cp.scope, deadline: cp.deadline });
+        for (const { token, cp } of await this.pendings()) {
+            if (!denySweepOwns(cp.gate) || !checkpointDeadlinePassed(cp.deadline, cutoff))
+                continue;
+            const position = { deadline: sweepDeadlineKey(cp.deadline), token };
+            if (after !== undefined && !sweepPositionPrecedes(after, position))
+                continue;
+            hits.push({ sessionId: cp.sessionId, scope: cp.scope, position });
         }
-        return hits
-            .sort((a, b) => a.deadline - b.deadline)
-            .slice(0, limit)
-            .map(({ sessionId, scope }) => ({ sessionId, scope }));
+        return hits.sort((a, b) => (sweepPositionPrecedes(a.position, b.position) ? -1 : sweepPositionPrecedes(b.position, a.position) ? 1 : 0)).slice(0, limit);
     }
-    async putCtx(sessionId, ctx) {
+    async putCtx(sessionId, ctx, claim) {
+        if (claim !== undefined) {
+            return this.writeCtxWhileClaimed(sessionId, ctx, claim, "local claim-fenced write", (path, text) => {
+                atomicWriteFile(this.tmpDir, path, text);
+                return "written";
+            });
+        }
         const rec = { sessionId, updatedAt: Date.now(), ctx };
         const text = JSON.stringify(rec);
         assertJsonColumnWritable(text, createCtxRecordReader(), `checkpoint ctx for session ${JSON.stringify(sessionId)} (local write leg)`);
         atomicWriteFile(this.tmpDir, join(this.ctxDir, ctxFileOf(sessionId)), text);
+        return "written";
     }
     async getCtx(sessionId) {
         const p = join(this.ctxDir, ctxFileOf(sessionId));
@@ -347,23 +468,25 @@ export class LocalCheckpointStore {
         const rec = refusingCtx(sessionId, () => decodeJsonColumn(readFileSync(p, "utf8"), createCtxRecordReader(), `checkpoint-ctx ${ctxFileOf(sessionId)} for session ${JSON.stringify(sessionId)}`));
         return rec.sessionId === sessionId ? rec.ctx : null;
     }
-    async rewriteCtxWhileClaimed(sessionId, taskId, ctx, legHolds) {
-        const claims = this.opts.claims;
-        if (claims === undefined)
-            throw new Error("LocalCheckpointStore.rewriteCtxWhileClaimed: no claim fence is bound to this store (wiring defect: the local backend binds its own run store)");
+    async rewriteCtxWhileClaimed(sessionId, ctx, claim) {
+        return this.writeCtxWhileClaimed(sessionId, ctx, claim, "local claim-fenced rewrite", (path, text) => {
+            if (!existsSync(path))
+                return "context_absent";
+            atomicWriteFile(this.tmpDir, path, text);
+            return "written";
+        });
+    }
+    writeCtxWhileClaimed(sessionId, ctx, claim, leg, write) {
+        const fence = claim.fence;
+        if ("db" in fence)
+            throw new Error(`LocalCheckpointStore ${leg}: the claim fence must be the in-process run store on this data root (wiring defect: the run store and the checkpoint store come from one backend)`);
         const rec = { sessionId, updatedAt: Date.now(), ctx };
         const text = JSON.stringify(rec);
-        assertJsonColumnWritable(text, createCtxRecordReader(), `checkpoint ctx for session ${JSON.stringify(sessionId)} (local claim-fenced rewrite)`);
+        assertJsonColumnWritable(text, createCtxRecordReader(), `checkpoint ctx for session ${JSON.stringify(sessionId)} (${leg})`);
         const path = join(this.ctxDir, ctxFileOf(sessionId));
-        let outcome = "context_absent";
-        const held = claims.whileHoldingClaim(sessionId, taskId, (run) => {
-            if (!legHolds(run)) {
-                outcome = "claim_released";
-            }
-            else if (existsSync(path)) {
-                atomicWriteFile(this.tmpDir, path, text);
-                outcome = "written";
-            }
+        let outcome = "claim_released";
+        const held = fence.whileHoldingClaim(sessionId, claim.taskId, (run) => {
+            outcome = claim.legHolds(run) ? write(path, text) : "claim_released";
             return FENCE_LANDED;
         });
         return held ? outcome : "claim_released";
@@ -409,7 +532,7 @@ export class LocalCheckpointStore {
             }
             if (rec.updatedAt >= cutoff)
                 continue;
-            if ((await this.findPendingTokenBySession(rec.sessionId)) !== null)
+            if ((await this.findPendingTokenBySession(rec.sessionId, undefined, { axis: "run" })) !== null)
                 continue;
             if ((await this.opts.getActiveTaskId?.(rec.sessionId)) !== undefined)
                 continue;

package/dist/plugins/local-data-dir-modes-m39.d.ts

@@ -0,0 +1,48 @@
+/** 披露码:路径(含数据根自身、名册目录的子项)经符号链接 —— 不跟,这一条不走(「不在根内」一类,不按链接指向哪里特判)。 */
+export declare const SYMLINK_IN_PATH = "SYMLINK_IN_PATH";
+/**
+ * 本迁移看的两只根:数据根(`LocalBackend` 持锁的那一只物理路径 —— core `resolveDataRoot` 的 `physicalPathOf` 拼写 = 店构造时拿到的值;身份核拿它当「根内」的唯一判据,
+ * 不是物理拼写的值 ⇒ 每一只目录都过不了核、逐个进披露行)与记忆引擎根(boot 的 `memoryEngineRootFor` 推导,同步游标在它下面;
+ * 调用方先把它换成与数据根同一种拼写 —— 见 `LocalBackend` 的 `dataDirLayout`)。名册包含关系按字面判:引擎根经数据根之外的别名拼写 ⇒ 当作在数据根之外(不进名册)。
+ */
+export interface DataDirLayout {
+    readonly dataRoot: string;
+    readonly memoryEngineRoot: string;
+}
+/**
+ * 布局只在这里铸一次(`LocalBackend` 取锁之后调):数据根 = 持锁的物理路径(配置里的拼写若经链接,事后改指也不影响);
+ * 记忆引擎根落在配置拼写的数据根之下 ⇒ 换成物理拼写(同一只目录只认一种拼写),否则原样(在数据根之外,名册不收)。
+ */
+export declare function buildDataDirLayout(a: {
+    readonly configuredRoot: string;
+    readonly physicalRoot: string;
+    readonly memoryEngineRoot: string;
+}): DataDirLayout;
+export interface DataDirModeRefusal {
+    /** 相对数据根的路径。 */
+    readonly path: string;
+    /** 错误码(`EPERM` / `EACCES` / `ESTALE` / …)或 {@link SYMLINK_IN_PATH};没有码的错误记 `UNKNOWN`。 */
+    readonly code: string;
+}
+export interface DataDirModeReading {
+    /** 本次收紧成 0o700 的目录(相对数据根)。 */
+    readonly tightened: readonly string[];
+    /** 本次没能收紧 / 没能看见 / 没有走的目录。 */
+    readonly refused: readonly DataDirModeRefusal[];
+}
+/** 两只日志座:成功提示与失败披露各一(失败那只由调用方接**不可缺席**的口)。 */
+export interface DataDirModeSinks {
+    readonly tightened: (msg: string, meta: Record<string, unknown>) => void;
+    readonly refused: (msg: string, meta: Record<string, unknown>) => void;
+}
+/** 测试座:收紧动作(默认对过了身份核的 fd `fchmod`)与平台(默认 `IS_WIN32`)。 */
+export interface DataDirModeSeats {
+    readonly fchmod?: (fd: number, mode: number, rel: string) => void;
+    readonly win32?: boolean;
+}
+/**
+ * 把数据根下名册里的 0755 店目录一次收紧成 0o700。起服时调(`LocalBackend.runOneTimeMigrations`,任何读者之前);数据根独占 ⇒ 没有滚动升级窗,不需要读侧半场。
+ * 失败不抛(见头注);读数也由两只日志座打出。
+ */
+export declare function tightenLocalDataDirModes(layout: DataDirLayout, sinks: DataDirModeSinks, seats?: DataDirModeSeats): DataDirModeReading;
+//# sourceMappingURL=local-data-dir-modes-m39.d.ts.map

package/dist/plugins/local-data-dir-modes-m39.js

@@ -0,0 +1,183 @@
+import { createLogger } from "../observability/logger.js";
+import { closeSync, constants as FS, fchmodSync, fstatSync, lstatSync, openSync, readdirSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { physicalPathOf } from "@sema-agent/core";
+import { IS_WIN32 } from "./host-platform.js";
+import { fileRunStoreDirsFor } from "./file-run-store.js";
+import { localCheckpointStoreDirsFor } from "./local-checkpoint-store.js";
+import { attachmentStoreDirFor } from "./local-task-attachment-store.js";
+import { scratchpadRootFor } from "../env-facts.js";
+import { pluginCacheRootFor } from "../capabilities/center-plugins.js";
+import { memorySyncCursorDirFor } from "../memory-sync-client.js";
+const DIR_MODE = 0o700;
+const GROUP_OTHER_BITS = 0o077;
+const TIGHTENED_EXAMPLES = 5;
+const REFUSED_LISTED = 10;
+export const SYMLINK_IN_PATH = "SYMLINK_IN_PATH";
+export function buildDataDirLayout(a) {
+    const rel = relative(resolve(a.configuredRoot), resolve(a.memoryEngineRoot));
+    const underConfigured = rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+    return { dataRoot: a.physicalRoot, memoryEngineRoot: underConfigured ? join(a.physicalRoot, rel) : a.memoryEngineRoot };
+}
+function rosterFor(layout) {
+    const run = fileRunStoreDirsFor(layout.dataRoot);
+    const checkpoint = localCheckpointStoreDirsFor(layout.dataRoot);
+    return [
+        { abs: run.runs, children: 1 },
+        { abs: run.tmp, children: 0 },
+        { abs: run.spaceCommits, children: 0 },
+        { abs: checkpoint.ctx, children: 0 },
+        { abs: checkpoint.tmp, children: 0 },
+        { abs: attachmentStoreDirFor(layout.dataRoot), children: 0 },
+        { abs: scratchpadRootFor(layout.dataRoot), children: 1 },
+        { abs: pluginCacheRootFor(layout.dataRoot), children: 2 },
+        { abs: memorySyncCursorDirFor(layout.memoryEngineRoot), children: 0 },
+    ];
+}
+function segmentsUnder(root, abs) {
+    const rel = relative(resolve(root), resolve(abs));
+    if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+        return undefined;
+    return rel.split(sep);
+}
+const codeOf = (e) => (typeof e === "object" && e !== null && "code" in e && typeof e.code === "string" ? e.code : "UNKNOWN");
+const emit = (sink, msg, meta) => {
+    try {
+        sink(msg, meta);
+    }
+    catch {
+        createLogger().warn(msg, meta);
+    }
+};
+const sameObject = (a, b) => a.dev === b.dev && a.ino === b.ino;
+function inRootBreak(root, segs, fd) {
+    try {
+        const held = fstatSync(fd, { bigint: true });
+        const physical = physicalPathOf(join(root, ...segs));
+        if (segmentsUnder(root, physical) === undefined)
+            return SYMLINK_IN_PATH;
+        if (!sameObject(lstatSync(physical, { bigint: true }), held))
+            return "ESTALE";
+        for (let i = 0; i <= segs.length; i += 1) {
+            const st = lstatSync(join(root, ...segs.slice(0, i)), { bigint: true });
+            if (st.isSymbolicLink())
+                return SYMLINK_IN_PATH;
+            if (!st.isDirectory())
+                return "ESTALE";
+        }
+        return undefined;
+    }
+    catch (e) {
+        return codeOf(e);
+    }
+}
+export function tightenLocalDataDirModes(layout, sinks, seats = {}) {
+    if (seats.win32 ?? IS_WIN32)
+        return { tightened: [], refused: [] };
+    const fchmod = seats.fchmod ?? ((fd, mode) => fchmodSync(fd, mode));
+    const root = layout.dataRoot;
+    const tightened = [];
+    const refused = [];
+    const refuse = (rel, code) => {
+        if (code !== "ENOENT")
+            refused.push({ path: rel, code });
+    };
+    const tighten = (segs, rel) => {
+        let fd;
+        try {
+            fd = openSync(join(root, ...segs), FS.O_RDONLY | FS.O_DIRECTORY | FS.O_NOFOLLOW);
+        }
+        catch (e) {
+            refuse(rel, codeOf(e));
+            return;
+        }
+        try {
+            const broken = inRootBreak(root, segs, fd);
+            if (broken !== undefined) {
+                refuse(rel, broken);
+                return;
+            }
+            fchmod(fd, DIR_MODE, rel);
+            tightened.push(rel);
+        }
+        catch (e) {
+            refuse(rel, codeOf(e));
+        }
+        finally {
+            closeSync(fd);
+        }
+    };
+    const step = (parent, name, more, depth) => {
+        const segs = [...parent, name];
+        const rel = join(...segs);
+        let mode;
+        try {
+            const st = lstatSync(join(root, ...segs));
+            if (st.isSymbolicLink()) {
+                refused.push({ path: rel, code: SYMLINK_IN_PATH });
+                return;
+            }
+            if (!st.isDirectory())
+                return;
+            mode = st.mode;
+        }
+        catch (e) {
+            refuse(rel, codeOf(e));
+            return;
+        }
+        const [next, ...rest] = more;
+        if (next !== undefined) {
+            step(segs, next, rest, depth);
+            return;
+        }
+        if ((mode & GROUP_OTHER_BITS) !== 0)
+            tighten(segs, rel);
+        if (depth === 0)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(join(root, ...segs), { withFileTypes: true });
+        }
+        catch (e) {
+            refuse(rel, codeOf(e));
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory() || entry.isSymbolicLink())
+                step(segs, entry.name, [], depth - 1);
+        }
+    };
+    let rootIntact = false;
+    try {
+        if (lstatSync(root).isSymbolicLink())
+            refused.push({ path: ".", code: SYMLINK_IN_PATH });
+        else
+            rootIntact = true;
+    }
+    catch (e) {
+        refuse(".", codeOf(e));
+    }
+    for (const { abs, children } of rootIntact ? rosterFor(layout) : []) {
+        const [first, ...rest] = segmentsUnder(root, abs) ?? [];
+        if (first !== undefined)
+            step([], first, rest, children);
+    }
+    if (refused.length > 0) {
+        emit(sinks.refused, "local_data_dir_mode_refused", {
+            count: refused.length,
+            mode: "0700",
+            entries: refused.slice(0, REFUSED_LISTED),
+            remedy: "these directories (relative to the data root) could not be tightened or read, or are reached through a symbolic link (SYMLINK_IN_PATH: links are never followed, the data root itself included) — as the owner of the real directory run `chmod 700` on it (or chown it to the server's user) and restart; the server keeps serving meanwhile",
+        });
+    }
+    if (tightened.length > 0) {
+        emit(sinks.tightened, "local_data_dir_modes_tightened", {
+            count: tightened.length,
+            mode: "0700",
+            examples: tightened.slice(0, TIGHTENED_EXAMPLES),
+            note: "store directories created by earlier versions with the default mode were tightened to 0700 once; later boots find them tight",
+        });
+    }
+    return { tightened, refused };
+}
+//# sourceMappingURL=local-data-dir-modes-m39.js.map