evolcore 0.0.33 → 0.0.34

package/dist/core/permission/ec-command-parser.js

@@ -714,6 +714,77 @@ function decodePositionalText(argv, start, optionFlags) {
         argv[index] = decodeEvolcoreInlineText(value);
     }
 }
+// 取值为「逗号分隔、单项不含空格」的列表参数。aid、标签值、角色名里都不会有
+// 空格，所以按空格拆分是安全的。
+const MEMORY_LIST_FLAGS = new Set(['--tags', '--speakers']);
+const SEND_LIST_FLAGS = new Set(['--mention']);
+const FS_LIST_FLAGS = new Set(['--allow-roles']);
+// 取值可能含空格的列表参数，只能按逗号拆：关键词是自由文本，记忆路径是 config
+// 相对路径，两者都可能有空格。
+const MEMORY_COMMA_ONLY_FLAGS = new Set(['--keywords', '--replaces']);
+/** 逗号分隔项：去空、去首尾空白，重新用逗号连接。 */
+function joinCommaList(value) {
+    return value.split(',').map(item => item.trim()).filter(Boolean).join(',');
+}
+/**
+ * 把列表参数统一成逗号分隔。PowerShell 把未加引号的 `a,b` 当数组，经 npm 的
+ * ec.ps1 用 `$args` 转发给 node 时逗号消失：`a,b` 变成 `a b`，`a, b` 和
+ * `a,b, c` 也变成 `a b` / `a b c`（实测 PS 5.1）。审批侧按命令串解析时看到的
+ * 是 `a,` 和 `b` 两个 token。两边在这里收敛到同一表示，委托哈希才能对上。
+ *
+ * 值以逗号结尾说明逗号数组还没结束：把后续 token 并进同一个值里再拆。值里本来
+ * 带逗号却没有空格的写法（bash 下 `--tags "a, b"`）也会被拆成两个标签，这是刻
+ * 意取舍——标签都是不含空格的单词，而 ec.ps1 已经把 `a, b` 和 `a,b` 归成了一
+ * 个值，无法再区分。
+ */
+function canonicalizeListFlags(argv, flags) {
+    for (let index = 0; index < argv.length; index++) {
+        const value = argv[index];
+        if (value === '--')
+            break;
+        if (!flags.has(value))
+            continue;
+        if (argv[index + 1] === undefined || argv[index + 1].startsWith('--'))
+            continue;
+        // `--tags a, b` 在 PowerShell 里是同一个值，审批侧却解析成 `a,` 加 `b`，
+        // 这里按逗号是否收尾把后续 token 续接回来
+        let end = index + 1;
+        while (argv[end].endsWith(',') && argv[end + 1] !== undefined
+            && !argv[end + 1].startsWith('--')) {
+            end++;
+        }
+        argv[index + 1] = argv.slice(index + 1, end + 1)
+            .join(' ')
+            .split(/[,\s]+/u)
+            .filter(Boolean)
+            .join(',');
+        if (end > index + 1)
+            argv.splice(index + 2, end - index - 1);
+        index++;
+    }
+}
+/**
+ * 只按逗号归一化，不动值里的空格。
+ *
+ * 与 canonicalizeListFlags 的区别：`--keywords 'a b'` 是一个含空格的关键词，
+ * 不能被拆成两个。所以只在值本身带逗号时整理（顺带去掉逗号周围的空白），
+ * `--keywords a,b` 这种未加引号的写法在 PowerShell 下会先被折成 `a b`，此处
+ * 认不出来——那属于被拒绝的写法，靠规范要求单引号避免。
+ */
+function canonicalizeCommaOnlyFlags(argv, flags) {
+    for (let index = 0; index < argv.length; index++) {
+        const value = argv[index];
+        if (value === '--')
+            break;
+        if (!flags.has(value))
+            continue;
+        const next = argv[index + 1];
+        if (next === undefined || next.startsWith('--') || !next.includes(','))
+            continue;
+        argv[index + 1] = joinCommaList(next);
+        index++;
+    }
+}
 function canonicalizeHandoffText(argv) {
     const action = argv[2];
     if (action !== 'return' && action !== 'recover-return')
@@ -739,7 +810,8 @@ function canonicalizeHandoffText(argv) {
  * Convert an EC invocation to the one argv representation shared by approval,
  * delegation hashing, IPC, and command execution. Shell syntax is already
  * resolved before this function is called; this function only normalizes the
- * EC entrypoint and applies the command-specific inline text contract.
+ * EC entrypoint, applies the command-specific inline text contract, and joins
+ * memory list flags with commas.
  */
 export function canonicalizeEvolcoreCommandArgv(argv) {
     const canonical = normalizeEvolcoreCommandArgv(argv);
@@ -759,11 +831,13 @@ export function canonicalizeEvolcoreCommandArgv(argv) {
     else if (command === 'msg' && subcommand === 'send') {
         decodeInlineFlags(result, INLINE_TEXT_FLAGS.msgSend);
         decodePositionalText(result, 5, MESSAGE_POSITIONAL_FLAGS);
+        canonicalizeListFlags(result, SEND_LIST_FLAGS);
     }
     else if (command === 'group') {
         if (subcommand === 'send') {
             decodeInlineFlags(result, INLINE_TEXT_FLAGS.groupSend);
             decodePositionalText(result, 5, MESSAGE_POSITIONAL_FLAGS);
+            canonicalizeListFlags(result, SEND_LIST_FLAGS);
         }
         else if (subcommand === 'create')
             decodeInlineFlags(result, INLINE_TEXT_FLAGS.groupCreate);
@@ -785,6 +859,13 @@ export function canonicalizeEvolcoreCommandArgv(argv) {
     else if (command === 'handoff') {
         canonicalizeHandoffText(result);
     }
+    else if (command === 'memory') {
+        canonicalizeListFlags(result, MEMORY_LIST_FLAGS);
+        canonicalizeCommaOnlyFlags(result, MEMORY_COMMA_ONLY_FLAGS);
+    }
+    else if (command === 'fs' && subcommand === 'chmod') {
+        canonicalizeListFlags(result, FS_LIST_FLAGS);
+    }
     return result;
 }
 const POWERSHELL_CREDENTIAL_ENV_RE = /^(EVOLCORE_CODEX_SESSION_TOKEN|EVOLCORE_DELEGATION_TOKEN)$/i;
@@ -1496,6 +1577,8 @@ export function parseLiteralShellCommand(command, options = {}) {
     let token = '';
     let tokenStarted = false;
     let quote = null;
+    // EC 命令的自由文本有额外的写法约束（见双引号分支的反引号/$ 转义处理）。
+    const isEcCommand = hasEcCommandPrefix(input);
     const finishToken = () => {
         if (!tokenStarted)
             return;
@@ -1527,6 +1610,12 @@ export function parseLiteralShellCommand(command, options = {}) {
                 return parseFailure(issue, input, index, argv.length, 'posix');
             if (char === '\\') {
                 const next = input[++index];
+                // EC 自由文本只接受单引号一种写法。双引号里用反斜杠转义 ` 或 $ 虽然
+                // 能得到字面量，但同一条规则下要记两套写法，所以对 ec 命令显式拒绝，
+                // 把正文一律导向单引号。非 ec 命令保持原行为。
+                if (isEcCommand && (next === '`' || next === '$')) {
+                    return parseFailure('unsupported-escape', input, index, argv.length, 'posix');
+                }
                 token += ['"', '\\', '$', '`'].includes(next) ? next : `\\${next}`;
                 continue;
             }
@@ -1715,7 +1804,7 @@ function normalizeApplyPatchPath(value) {
         return undefined;
     return normalized;
 }
-function parseApplyPatchDocument(source) {
+export function parseApplyPatchDocument(source) {
     const lines = source.replace(/\r\n?/gu, '\n').split('\n');
     while (lines.at(-1) === '')
         lines.pop();
@@ -3022,7 +3111,7 @@ export function describeProactiveSendCommandFailure(toolName, input, session) {
     const from = argv[3];
     const to = argv[4];
     const fullFormHint = `${prefix}缺少发送者与目标。完整形式为 ${expectedForm}；`
-        + '省略 from/to 仅在带 --thread 的跨话题发送中允许，普通回复也可用 ec ctl send "<正文>" 继承当前会话。';
+        + `省略 from/to 仅在带 --thread 的跨话题发送中允许，普通回复也可用 ec ctl send '<正文>' 继承当前会话。`;
     if (!from || from.startsWith('--')) {
         return fullFormHint;
     }
@@ -3030,7 +3119,7 @@ export function describeProactiveSendCommandFailure(toolName, input, session) {
         return looksLikeAid(from)
             ? fullFormHint
             : `${prefix}缺少发送者与目标（"${from}" 是正文而非 AID）。完整形式为 ${expectedForm}；`
-                + '省略 from/to 仅在带 --thread 的跨话题发送中允许，普通回复也可用 ec ctl send "<正文>" 继承当前会话。';
+                + `省略 from/to 仅在带 --thread 的跨话题发送中允许，普通回复也可用 ec ctl send '<正文>' 继承当前会话。`;
     }
     if (!looksLikeAid(from) || !looksLikeAid(to)) {
         return `${prefix}发送者/目标不是合法 AID（收到 from="${from}" to="${to}"）。完整形式为 ${expectedForm}。`;

package/dist/core/permission/protected-paths.js

@@ -938,7 +938,11 @@ export function lClassGrantIncludesProtectedPath(value, options = {}) {
         // A grant covering an Agent root also covers its L-class configuration.
         if (segments.length <= 2)
             return true;
-        return ['config.json', 'contact.json', 'contact-operations.jsonl', 'relations', 'roles', 'triggers']
+        // relations/ 下的 L 类只有 relations/<peer>/config.json：只有范围是 relations/ 或
+        // relations/<peer> 本身时才覆盖它，更深的路径（如 relations/<peer>/memory/…）不会。
+        if (segments[2] === 'relations')
+            return segments.length <= 4;
+        return ['config.json', 'contact.json', 'contact-operations.jsonl', 'roles', 'triggers']
             .includes(segments[2]);
     }
     return false;

package/dist/core/permission/readonly-shell-query.js

@@ -3,7 +3,7 @@ import { parseLiteralShellArgv } from './ec-command-parser.js';
 const MAX_QUERY_LISTS = 8;
 const MAX_PIPELINE_STAGES = 3;
 const SUPPORTED_EXECUTABLES = new Set([
-    'echo', 'pwd', 'ls', 'cat', 'grep', 'rg', 'find', 'sed', 'head', 'sort', 'git', 'wc', 'stat', 'lstat', 'awk',
+    'echo', 'pwd', 'ls', 'cat', 'grep', 'rg', 'find', 'sed', 'head', 'tail', 'sort', 'git', 'wc', 'stat', 'lstat', 'awk',
     'bash', 'sh',
 ]);
 const FIND_MUTATING_PRIMARY_RE = /^-(?:delete|exec|execdir|ok|okdir|fprint|fprint0|fprintf|fls)$/;
@@ -447,6 +447,13 @@ function analyzeHead(args) {
     const parsed = parseOptionsAndPaths(args, new Set(['-c', '-n', '--bytes', '--lines']));
     return parsed?.paths.map(exact) ?? null;
 }
+function analyzeTail(args) {
+    // -f/--follow opens an indefinite watch loop — not a bounded read query.
+    if (args.some(a => a === '-f' || a === '--follow' || /^-[^-]*f/.test(a)))
+        return null;
+    const parsed = parseOptionsAndPaths(args, new Set(['-c', '-n', '--bytes', '--lines']));
+    return parsed?.paths.map(exact) ?? null;
+}
 function analyzeSort(args) {
     if (args.some(argument => /^(?:-o|-T)(?:.+|$)|^(?:--output|--compress-program|--temporary-directory|--files0-from)(?:=|$)/.test(argument))) {
         return null;
@@ -828,68 +835,95 @@ function analyzeCommand(argv) {
     const args = argv.slice(1);
     let pathOperands = null;
     let accessKind = 'content';
+    let purpose = 'unknown';
     switch (executable) {
         case 'echo':
             pathOperands = [];
+            purpose = 'passthrough';
             break;
         case 'pwd':
             pathOperands = args.every(argument => ['-L', '-P', '--help', '--version'].includes(argument)) ? [] : null;
+            purpose = 'passthrough';
             break;
         case 'ls':
             pathOperands = analyzeLs(args);
+            purpose = 'enumerate';
             break;
         case 'cat':
             pathOperands = analyzeCat(args);
+            purpose = 'content-read';
             break;
         case 'grep':
             pathOperands = analyzeGrep(args);
+            purpose = 'search';
             break;
         case 'rg':
             pathOperands = analyzeRg(args);
+            purpose = 'search';
             break;
         case 'find':
             pathOperands = analyzeFind(args);
+            purpose = 'enumerate';
             break;
         case 'sed':
             pathOperands = analyzeSed(args);
+            purpose = 'content-read';
             break;
         case 'head':
             pathOperands = analyzeHead(args);
+            purpose = 'content-read';
+            break;
+        case 'tail':
+            pathOperands = analyzeTail(args);
+            purpose = 'content-read';
             break;
         case 'sort':
             pathOperands = analyzeSort(args);
+            // sort 有路径参数时是文件读取，无路径参数时是纯 stdin 排序
+            purpose = 'stdin-transform';
             break;
         case 'git':
             pathOperands = analyzeGit(args);
+            purpose = 'vcs-query';
             break;
         case 'wc':
             pathOperands = analyzeWc(args);
+            // wc 有路径参数时是元数据读取，无路径参数时是纯 stdin 统计
+            purpose = 'metadata-read';
             break;
         case 'stat':
         case 'lstat':
             pathOperands = analyzeStat(args);
             accessKind = 'metadata';
+            purpose = 'metadata-read';
             break;
         case 'awk':
             pathOperands = analyzeAwk(args);
+            purpose = 'content-read';
             break;
         case 'bash':
         case 'sh':
             pathOperands = analyzeShellSyntaxCheck(args);
+            purpose = 'syntax-check';
             break;
     }
     if (!pathOperands)
         return null;
     if (['ls', 'find'].includes(executable))
         accessKind = 'enumerate';
+    // 无路径操作数的命令是纯 stdin→stdout 变换，可安全出现在管道任意位置。
+    // 对于 sort/wc/awk/grep/head/tail/sed：有路径参数时读文件，无路径参数时为 stdin 变换。
+    const stdinTransform = pathOperands.length === 0
+        && ['sort', 'wc', 'awk', 'grep', 'rg', 'head', 'tail', 'sed'].includes(executable);
+    // 修正 purpose：stdin 变换时统一标记，避免 'metadata-read'/'content-read' 歧义
+    const resolvedPurpose = stdinTransform ? 'stdin-transform' : purpose;
     return {
         command: {
             executable,
             argv,
             pathOperands,
-            // Keep the established IR shape for ordinary queries. Only metadata
-            // commands need an explicit action marker; content/enumeration are
-            // derived from their operands by policy consumers.
+            stdinTransform,
+            purpose: resolvedPurpose,
             ...(accessKind === 'metadata' ? { accessKind } : {}),
         },
     };
@@ -910,7 +944,11 @@ export function analyzeReadonlyShellQuery(command, options = {}) {
             if (!analyzed)
                 return { kind: 'unproven', reason: 'unsupported-command-or-option' };
             if (index > 0) {
-                if (!['head', 'sort', 'grep', 'wc'].includes(analyzed.command.executable)) {
+                // 管道后续段必须是纯 stdin→stdout 变换（stdinTransform=true 由 analyzeCommand 打标，
+                // 表示命令无 FS 路径操作数、只处理 stdin 流）。
+                // 黑名单规则已在 analyzeCommand 内部拦截（如 sort -o、tail -f 等），到这里的都是
+                // 白名单规则捞回后的安全命令，用标签判断而非硬编码可执行文件列表。
+                if (!analyzed.command.stdinTransform) {
                     return { kind: 'unproven', reason: 'unsupported-pipeline-filter' };
                 }
                 if (analyzed.command.pathOperands.length > 0) {

package/dist/core/permission/session-path-grants.js

@@ -0,0 +1,334 @@
+/**
+ * session-path-grants.ts — 用户会话路径授权表
+ *
+ * 形状：路径模板 → [{ identities, access }]，identities 为角色名（owner/admin/member/visitor）。
+ *
+ * 只服务用户会话。系统会话（记忆整理等）与角色体系无关，路径边界由
+ * src/core/system-session/ 下的模块在代码里决定，不走本表、不并运行时授予。
+ *
+ * 判定规则（两条，别加第三条）：
+ *   1. 同会话多条命中 → 取最大权限（none 显式覆盖通配）
+ *   2. 与权限模式取交集：readonly 下 write 降级为 read
+ *
+ * 多表合并（mergeSessionPathGrantTables）同路径追加而非替换。
+ * 运行时动态授予（ec ctl path grant）走 grantSessionPath()，按 sessionId 持久化。
+ *
+ * 详见 docs/memory/system-session-plugin-design.md
+ */
+import fs from 'fs';
+import path from 'path';
+import { resolveRoot } from '../../paths.js';
+import { resolveProtectedCandidate, isSameOrDescendant } from './protected-paths.js';
+import { logger } from '../../utils/logger.js';
+import { registerContent, unregisterFile } from '../file-integrity/store.js';
+const ACCESS_RANK = { none: -1, read: 1, write: 2 };
+/**
+ * 内置默认授权表。当前为空：用户会话缺省只能读工作目录，
+ * 额外路径由 owner/admin 经 `ec ctl path grant` 按会话授予。
+ */
+export const BUILTIN_SESSION_PATH_GRANTS = {};
+/**
+ * 合并多张授权表：同路径模板的条目**追加**，不替换。
+ *
+ * 对象展开 `{ ...a, ...b }` 在同键时会整组丢弃前者——会话表里一旦出现同名路径，
+ * 前一张表的授予就静默消失。追加后判定仍走「同路径取最大、none 锁定」，
+ * 所以想收窄只能显式写 none，不会因为键名巧合丢权限。
+ */
+export function mergeSessionPathGrantTables(...tables) {
+    const merged = {};
+    for (const table of tables) {
+        if (!table)
+            continue;
+        for (const [template, entries] of Object.entries(table)) {
+            if (!Array.isArray(entries))
+                continue;
+            merged[template] = [...(merged[template] ?? []), ...entries];
+        }
+    }
+    return merged;
+}
+/** 判断一份授权表里的条目是否合法。 */
+export function isValidGrantEntry(entry) {
+    return Array.isArray(entry.identities)
+        && entry.identities.length > 0
+        && entry.identities.every(value => typeof value === 'string' && value.trim().length > 0)
+        && (entry.access === 'none' || entry.access === 'read' || entry.access === 'write');
+}
+/** 替换路径模板里的变量。未知变量保持原样，由调用方按「不存在」处理。 */
+export function substitutePathTemplate(template, ctx, vars) {
+    return template.replace(/\$([A-Z_]+)/g, (match, name) => vars[name] ?? match);
+}
+function buildVars(ctx) {
+    return {
+        HOME: resolveRoot(),
+        SELF_AID: ctx.selfAid,
+        PEER: ctx.peerKey,
+        OWNER: ctx.ownerAid,
+        PROJECT: ctx.projectPath,
+    };
+}
+/** 模板里出现未解析的变量时视为不可用条目。展开后的路径必须是绝对路径。 */
+function resolveTemplate(template, ctx) {
+    const resolved = substitutePathTemplate(template, ctx, buildVars(ctx));
+    const unresolved = resolved.match(/\$[A-Z_]+/g);
+    if (unresolved) {
+        // 未知变量（拼错）与已知变量缺值（如私聊会话没有 $OWNER）都会走到这里；
+        // 两者都让整条授予失效，留一行日志，否则下游只剩一个原因不明的读拒绝。
+        logger.warn(`[path-grants] 授权模板含未解析变量，条目跳过: template=${template} unresolved=${[...new Set(unresolved)].join(',')} identity=${ctx.identity ?? ''}`);
+        return undefined;
+    }
+    if (!path.isAbsolute(resolved)) {
+        logger.warn(`[path-grants] 授权模板展开后不是绝对路径，条目跳过: template=${template} resolved=${resolved}`);
+        return undefined;
+    }
+    return resolveProtectedCandidate(resolved);
+}
+/** 当前会话是否命中某条授予的身份。 */
+function identityMatches(entry, identity) {
+    const normalized = identity.trim().toLowerCase();
+    return entry.identities.some(value => value.trim().toLowerCase() === normalized);
+}
+/**
+ * 权限模式交集。系统会话不传 permissionMode，按授予原样生效。
+ * readonly 下 write 降级为 read；none 永不升级。
+ */
+function applyPermissionModeCeiling(access, permissionMode) {
+    if (access === 'none' || !permissionMode)
+        return access;
+    return permissionMode === 'readonly' ? 'read' : access;
+}
+/**
+ * 计算当前会话在给定授权表下的**有效路径集合**。
+ *
+ * 返回 path → access 的映射，只含 access 非 none 的条目。同路径多条命中取最大权限
+ * （none 除外——任一命中 none 即整体拒绝）。
+ */
+export function resolveEffectivePathGrants(table, ctx) {
+    const effective = new Map();
+    const identity = (ctx.identity ?? '').trim();
+    if (!identity)
+        return effective;
+    for (const [template, entries] of Object.entries(table)) {
+        if (!Array.isArray(entries))
+            continue;
+        const hits = entries.filter(entry => isValidGrantEntry(entry) && identityMatches(entry, identity));
+        if (hits.length === 0)
+            continue;
+        const resolved = resolveTemplate(template, ctx);
+        if (!resolved)
+            continue;
+        const previous = effective.get(resolved);
+        // none 是显式拒绝，一旦出现就锁定，不被同路径的其它授予放宽
+        if (previous === 'none')
+            continue;
+        let next = 'none';
+        for (const hit of hits) {
+            const grant = applyPermissionModeCeiling(hit.access, ctx.permissionMode);
+            if (grant === 'none') {
+                next = 'none';
+                break;
+            }
+            if (ACCESS_RANK[grant] > ACCESS_RANK[next])
+                next = grant;
+        }
+        if (next === 'none')
+            effective.set(resolved, 'none');
+        else
+            effective.set(resolved, next);
+    }
+    return effective;
+}
+/**
+ * 有效路径授权表的可读根目录列表（含只读授予）。
+ *
+ * 判定语义是「本路径落在任一可读根之下即为可读」，因此这里连同 write 授予一起返回——
+ * write 蕴含 read。
+ */
+export function resolveGrantedReadRoots(table, ctx) {
+    const roots = [];
+    for (const [value, access] of resolveEffectivePathGrants(table, ctx)) {
+        if (access === 'read' || access === 'write')
+            roots.push(value);
+    }
+    return roots;
+}
+/** 候选路径是否落在任一授权根之下（含根自身）。 */
+export function isPathGranted(candidate, roots) {
+    const resolved = resolveProtectedCandidate(candidate);
+    return roots.some(root => isSameOrDescendant(resolved, root));
+}
+const runtimeGrants = new Map();
+/**
+ * 持久化位置：$HOME/data/path/grants/<sessionId>.json —— **每会话一个文件**。
+ *
+ * 不用单个共用大文件：那样一份损坏或半写会让**所有**会话的授予一起丢，
+ * 而且清理某个会话要重写整文件。一会话一文件让隔离和回收都变成本地操作。
+ *
+ * 代价是首次加载要扫目录。授予是低频操作，目录规模等于活跃会话数，可接受。
+ */
+function runtimeGrantDir() {
+    return path.join(resolveRoot(), 'data', 'path', 'grants');
+}
+/** sessionId 形如 meta_YYYYMMDD_<epochMs>，字符集安全；仍做一次防御性收敛。 */
+function runtimeGrantFilePath(sessionId) {
+    const safe = sessionId.replace(/[^A-Za-z0-9_-]/g, '_');
+    return path.join(runtimeGrantDir(), `${safe}.json`);
+}
+/** 原子写：同目录临时文件 + rename，避免读到半写的 JSON。 */
+function persistSessionGrants(sessionId) {
+    const file = runtimeGrantFilePath(sessionId);
+    try {
+        const list = runtimeGrants.get(sessionId);
+        if (!list || list.length === 0) {
+            fs.rmSync(file, { force: true });
+            try {
+                unregisterFile(file);
+            }
+            catch { /* best-effort */ }
+            return;
+        }
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const tmp = `${file}.tmp-${process.pid}`;
+        const content = `${JSON.stringify(list, null, 2)}\n`;
+        // 先登记，再写盘：避免 CLI 进程读到"新内容 + 旧台账"的窗口
+        try {
+            registerContent(file, content);
+        }
+        catch { /* best-effort */ }
+        fs.writeFileSync(tmp, content, 'utf-8');
+        fs.renameSync(tmp, file);
+    }
+    catch { /* 持久化失败不阻断本次会话：内存授予仍然生效 */ }
+}
+let runtimeGrantsLoaded = false;
+/** 首次使用时从磁盘加载一次。单个文件损坏只影响它自己那个会话。 */
+function ensureRuntimeGrantsLoaded() {
+    if (runtimeGrantsLoaded)
+        return;
+    runtimeGrantsLoaded = true;
+    let files;
+    try {
+        files = fs.readdirSync(runtimeGrantDir()).filter(name => name.endsWith('.json'));
+    }
+    catch {
+        return; // 首次运行：目录还不存在
+    }
+    for (const name of files) {
+        const sessionId = name.slice(0, -'.json'.length);
+        try {
+            const parsed = JSON.parse(fs.readFileSync(path.join(runtimeGrantDir(), name), 'utf-8'));
+            if (Array.isArray(parsed) && parsed.length > 0)
+                runtimeGrants.set(sessionId, parsed);
+        }
+        catch { /* 该会话的授权文件损坏：跳过它，不影响其它会话 */ }
+    }
+}
+/** 供测试与重载清空（含持久化，避免下个用例读到上个用例的残留）。 */
+export function clearRuntimePathGrants(sessionId) {
+    ensureRuntimeGrantsLoaded();
+    if (sessionId) {
+        runtimeGrants.delete(sessionId);
+        persistSessionGrants(sessionId);
+        return;
+    }
+    for (const id of [...runtimeGrants.keys()]) {
+        runtimeGrants.delete(id);
+        persistSessionGrants(id);
+    }
+}
+/** 登记一条运行时授予。授权校验由 IPC 层负责（仅 owner/admin）。 */
+export function grantSessionPath(record) {
+    ensureRuntimeGrantsLoaded();
+    const list = runtimeGrants.get(record.sessionId) ?? [];
+    // 同路径同身份重复登记按覆盖处理，避免列表无限增长
+    const kept = list.filter(existing => !(existing.path === record.path && existing.identity === record.identity));
+    kept.push(record);
+    runtimeGrants.set(record.sessionId, kept);
+    persistSessionGrants(record.sessionId);
+}
+/** 撤销一条运行时授予，返回是否命中。 */
+export function revokeSessionPath(sessionId, template, identity) {
+    ensureRuntimeGrantsLoaded();
+    const list = runtimeGrants.get(sessionId);
+    if (!list)
+        return false;
+    const before = list.length;
+    const kept = list.filter(record => !(record.path === template && (identity === undefined || record.identity === identity)));
+    if (kept.length === before)
+        return false;
+    if (kept.length === 0)
+        runtimeGrants.delete(sessionId);
+    else
+        runtimeGrants.set(sessionId, kept);
+    persistSessionGrants(sessionId);
+    return true;
+}
+/** 列出某会话的运行时授予。 */
+export function listRuntimePathGrants(sessionId) {
+    ensureRuntimeGrantsLoaded();
+    return runtimeGrants.get(sessionId) ?? [];
+}
+/**
+ * 会话结束时的清理入口。
+ *
+ * 只清**该会话自己的**运行时授予：`ec ctl path grant` 是以当前会话为归属登记的，
+ * 会话结束后不再有会话身份去消费它。
+ */
+export function releaseSessionPathGrants(sessionId) {
+    ensureRuntimeGrantsLoaded();
+    if (!runtimeGrants.delete(sessionId))
+        return;
+    persistSessionGrants(sessionId);
+}
+/**
+ * 把某会话的运行时授予并入授权表。
+ *
+ * 运行时授予以**会话身份**登记：identity 缺省时表示「该会话自身」，
+ * 亦即用调用方的 identity 匹配。
+ */
+export function mergeRuntimeGrantsForSession(table, sessionId, identity) {
+    if (!sessionId)
+        return table;
+    ensureRuntimeGrantsLoaded();
+    const list = runtimeGrants.get(sessionId);
+    if (!list || list.length === 0)
+        return table;
+    const merged = { ...table };
+    for (const record of list) {
+        if (!path.isAbsolute(record.path))
+            continue;
+        if (record.identity && record.identity.trim().toLowerCase() !== identity.trim().toLowerCase())
+            continue;
+        const existing = merged[record.path];
+        merged[record.path] = [...(existing ?? []), { identities: [identity], access: record.access }];
+    }
+    return merged;
+}
+/**
+ * 会话运行目录本身恒为可读根：它是本会话私有的临时根，runner 自己的临时产物
+ * 都落在这里（见 task-context.ts 的 ensureSessionRuntimeDir）。
+ *
+ * TMPDIR 写能力另由 managedTempDir 负责，不在这里表达。
+ */
+export function sessionOwnTempReadRoot(sessionRuntimeDir) {
+    if (!sessionRuntimeDir || !path.isAbsolute(sessionRuntimeDir))
+        return [];
+    return [resolveProtectedCandidate(sessionRuntimeDir)];
+}
+/** 缺省的文件系统根：会话工作目录。 */
+export function defaultProjectRoot(projectPath) {
+    if (!projectPath || !path.isAbsolute(projectPath))
+        return [];
+    return [resolveProtectedCandidate(projectPath)];
+}
+/** 供诊断输出：当前会话的有效路径集合（含运行时授予）。 */
+export function describeEffectivePaths(table, ctx, sessionRuntimeDir) {
+    const result = [];
+    for (const [value, access] of resolveEffectivePathGrants(table, ctx)) {
+        result.push({ path: value, access });
+    }
+    for (const value of sessionOwnTempReadRoot(sessionRuntimeDir)) {
+        result.push({ path: value, access: 'read' });
+    }
+    return result;
+}