@ouro.bot/cli 0.1.0-alpha.730 → 0.1.0-alpha.732

package/dist/repertoire/guardrails.js

@@ -38,6 +38,7 @@ exports.guardInvocation = guardInvocation;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const friends_1 = require("@ouro.bot/friends");
+const shell_quote_1 = require("shell-quote");
 const runtime_1 = require("../nerves/runtime");
 const store_1 = require("../commerce/store");
 const deny = (reason) => ({ allowed: false, reason });
@@ -298,6 +299,676 @@ const COMMERCE_FAMILY_TOOLS = new Set(["commerce_checkout_preview", "commerce_ch
 const COMMERCE_AUTHORITY_TOOLS = new Set(["stripe_create_card", "flight_hold", "flight_book"]);
 const MAIL_FAMILY_TOOLS = new Set(["mail_screener", "mail_decide", "mail_access_log", "mail_send", "mail_index_refresh"]);
 const MAIL_DELEGATED_READ_TOOLS = new Set(["mail_recent", "mail_search"]);
+function opaqueAnsiShellAtoms(command) {
+    const atoms = [];
+    let inAnsiQuote = false;
+    for (let index = 0; index < command.length;) {
+        if (!inAnsiQuote && command.startsWith("$'", index)) {
+            inAnsiQuote = true;
+            index += 2;
+            continue;
+        }
+        const character = command[index];
+        if (inAnsiQuote && character === "'") {
+            inAnsiQuote = false;
+            index += 1;
+            continue;
+        }
+        if (inAnsiQuote && character === "\\") {
+            const escape = command.slice(index).match(/^\\(?:x[0-9a-fA-F]{1,2}|u[0-9a-fA-F]{1,4}|U[0-9a-fA-F]{1,8}|[0-7]{1,3}|c.|.)?/s)[0];
+            atoms.push(null);
+            index += escape.length;
+            continue;
+        }
+        if (!inAnsiQuote && (character === "'" || character === '"')) {
+            index += 1;
+            continue;
+        }
+        if (!inAnsiQuote && character === "\\" && index + 1 < command.length) {
+            atoms.push(command[index + 1]);
+            index += 2;
+            continue;
+        }
+        atoms.push(character);
+        index += 1;
+    }
+    return atoms;
+}
+function shellContainsAmbiguousAnsiMailCacheSync(command) {
+    if (!command.includes("$'"))
+        return false;
+    const expected = ["ouro", "mail", "sync-cache"];
+    let states = new Set(["0:0"]);
+    const crossTokenBoundary = (current) => {
+        const next = new Set(["0:0"]);
+        for (const state of current) {
+            const [tokenIndex, characterIndex] = state.split(":").map(Number);
+            if (characterIndex !== expected[tokenIndex].length)
+                continue;
+            if (tokenIndex === expected.length - 1)
+                return { matched: true, states: next };
+            next.add(`${tokenIndex + 1}:0`);
+        }
+        return { matched: false, states: next };
+    };
+    for (const atom of opaqueAnsiShellAtoms(command)) {
+        if (atom === null) {
+            const next = new Set(states);
+            for (const state of states) {
+                const [tokenIndex, characterIndex] = state.split(":").map(Number);
+                if (characterIndex >= 0 && characterIndex < expected[tokenIndex].length) {
+                    next.add(`${tokenIndex}:${characterIndex + 1}`);
+                }
+            }
+            const boundary = crossTokenBoundary(states);
+            if (boundary.matched)
+                return true;
+            states = new Set([...next, ...boundary.states]);
+            continue;
+        }
+        if (/\s|[;&|()`]/.test(atom)) {
+            const boundary = crossTokenBoundary(states);
+            if (boundary.matched)
+                return true;
+            states = boundary.states;
+            continue;
+        }
+        const next = new Set();
+        for (const state of states) {
+            const [tokenIndex, characterIndex] = state.split(":").map(Number);
+            const wanted = expected[tokenIndex]?.[characterIndex];
+            next.add(wanted?.toLowerCase() === atom.toLowerCase() ? `${tokenIndex}:${characterIndex + 1}` : `${tokenIndex}:-1`);
+        }
+        states = next;
+    }
+    return crossTokenBoundary(states).matched;
+}
+const SHELL_COMMAND_BOUNDARIES = new Set(["||", "&&", ";;", "|&", "&", ";", "(", ")", "|", "<("]);
+const SHELL_INTERPRETERS = new Set(["sh", "bash", "zsh"]);
+const SHELL_TOKEN_BOUNDARIES = new Set(["{", "}", "then", "elif", "else", "do"]);
+const SHELL_GRAMMAR_PREFIXES = new Set(["!", "if", "until", "while"]);
+const SHELL_PARAMETER_MARKER = "__OURO_SHELL_PARAMETER_";
+const SHELL_ARRAY_EXPANSION = "__OURO_ARRAY_EXPANSION__";
+function hasUnescapedShellSubstitution(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        if (value[index] === "\\") {
+            index += 1;
+            continue;
+        }
+        if (value.startsWith("$(", index) && !value.startsWith("$((", index))
+            return true;
+        if (value[index] === "`")
+            return true;
+    }
+    return false;
+}
+function stripHereDocBodies(command) {
+    const pending = [];
+    const lines = command.split("\n");
+    return lines.map((sourceLine) => {
+        if (pending.length > 0) {
+            const active = pending[0];
+            const candidate = active.stripTabs ? sourceLine.replace(/^\t+/, "") : sourceLine;
+            if (candidate === active.delimiter) {
+                pending.shift();
+                return "";
+            }
+            if (active.quoted || !hasUnescapedShellSubstitution(sourceLine))
+                return "";
+            return exposeShellSubstitutions(sourceLine).split("\n").slice(1).join("\n");
+        }
+        const pattern = /<<(?!<)(-)?\s*(?:'([^']*)'|"([^"]*)"|\\([^\s;&|]+)|([^\s;&|]+))/g;
+        for (const match of stripShellComments(sourceLine).matchAll(pattern)) {
+            pending.push({
+                stripTabs: match[1] !== undefined,
+                delimiter: match[2] ?? match[3] ?? match[4] ?? match[5],
+                quoted: match[2] !== undefined || match[3] !== undefined || match[4] !== undefined,
+            });
+        }
+        return sourceLine;
+    }).join("\n");
+}
+function stripShellComments(command) {
+    let result = "";
+    let quote = null;
+    for (let index = 0; index < command.length; index += 1) {
+        const character = command[index];
+        if (character === "\\" && quote !== "single") {
+            result += character + (command[index + 1] ?? "");
+            index += 1;
+            continue;
+        }
+        if (character === "'" && quote !== "double")
+            quote = quote === "single" ? null : "single";
+        else if (character === '"' && quote !== "single")
+            quote = quote === "double" ? null : "double";
+        if (character === "#" && quote === null && (index === 0 || /[\s;&|()]/.test(command[index - 1]))) {
+            const newline = command.indexOf("\n", index);
+            if (newline < 0)
+                break;
+            result += " ".repeat(newline - index) + "\n";
+            index = newline;
+            continue;
+        }
+        result += character;
+    }
+    return result;
+}
+const SHELL_ARRAY_ASSIGNMENT = /([A-Za-z_][A-Za-z0-9_]*)(\+?=)\(([^()\n]*)\)/y;
+const SHELL_INDEXED_ASSIGNMENT = /([A-Za-z_][A-Za-z0-9_]*)\[(\d+)\]=("[^"]*"|'[^']*'|[^\s;&|]+)/y;
+const SHELL_SCALAR_ASSIGNMENT = /([A-Za-z_][A-Za-z0-9_]*)=("[^"]*"|'[^']*'|[^\s;&|()]+)/y;
+const SHELL_ARRAY_PARAMETER = /\$\{([A-Za-z_][A-Za-z0-9_]*)\[(@|\*)\]\}/y;
+const SHELL_SCALAR_PARAMETER = /\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/y;
+function shellMatchAt(pattern, command, index) {
+    pattern.lastIndex = index;
+    return pattern.exec(command);
+}
+function shellAssignmentPosition(command, index) {
+    let previous = index - 1;
+    while (previous >= 0 && /[ \t]/.test(command[previous]))
+        previous -= 1;
+    return previous < 0 || /[;&|()\n]/.test(command[previous]);
+}
+function parseShellWords(value) {
+    if (hasUnescapedShellSubstitution(value) || /(^|[^\\])\$(?!['"])/.test(value))
+        return undefined;
+    try {
+        const entries = (0, shell_quote_1.parse)(value);
+        if (entries.some((entry) => typeof entry !== "string"))
+            return undefined;
+        return entries;
+    }
+    catch {
+        return undefined;
+    }
+}
+function shellAssignmentPersists(command, endIndex) {
+    let next = endIndex;
+    while (next < command.length && /[ \t]/.test(command[next]))
+        next += 1;
+    return next === command.length || /[;&|\n]/.test(command[next]);
+}
+function shellUnquotedFields(values) {
+    const fields = values.flatMap((value) => value.split(/\s+/).filter(Boolean));
+    return fields.some((field) => /[*?[]/.test(field)) ? SHELL_ARRAY_EXPANSION : (0, shell_quote_1.quote)(fields);
+}
+function doubleQuotedFragment(value) {
+    if (hasUnescapedShellSubstitution(value))
+        return undefined;
+    try {
+        const parsed = (0, shell_quote_1.parse)(`"${value}"`);
+        return parsed.length === 1 && typeof parsed[0] === "string" ? parsed[0] : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function closingDoubleQuote(command, startIndex) {
+    for (let index = startIndex; index < command.length; index += 1) {
+        if (command[index] === "\\")
+            index += 1;
+        else if (command[index] === '"')
+            return index;
+    }
+    return -1;
+}
+function transformOrderedShellVariables(command) {
+    const variables = new Map();
+    const result = [];
+    let quote = null;
+    let doubleQuoteStart = -1;
+    let doubleQuoteResultIndex = -1;
+    for (let index = 0; index < command.length; index += 1) {
+        const character = command[index];
+        if (character === "\\" && quote !== "single") {
+            result.push(character + (command[index + 1] ?? ""));
+            index += 1;
+            continue;
+        }
+        if (character === "'") {
+            if (quote !== "double")
+                quote = quote === "single" ? null : "single";
+            result.push(character);
+            continue;
+        }
+        if (character === '"') {
+            if (quote !== "single") {
+                if (quote === "double") {
+                    quote = null;
+                    doubleQuoteStart = -1;
+                    doubleQuoteResultIndex = -1;
+                }
+                else {
+                    quote = "double";
+                    doubleQuoteStart = index;
+                    doubleQuoteResultIndex = result.length;
+                }
+            }
+            result.push(character);
+            continue;
+        }
+        if (quote === null && /[A-Za-z_]/.test(character) && shellAssignmentPosition(command, index)) {
+            const arrayAssignment = shellMatchAt(SHELL_ARRAY_ASSIGNMENT, command, index);
+            if (arrayAssignment) {
+                const [, name, operator, body] = arrayAssignment;
+                const elements = parseShellWords(body);
+                if (elements === undefined)
+                    variables.delete(name);
+                else
+                    variables.set(name, { array: operator === "+=" ? [...(variables.get(name)?.array ?? []), ...elements] : elements });
+                result.push(`${name}=__OURO_ARRAY_LITERAL`);
+                index += arrayAssignment[0].length - 1;
+                continue;
+            }
+            const indexedAssignment = shellMatchAt(SHELL_INDEXED_ASSIGNMENT, command, index);
+            if (indexedAssignment) {
+                const [, name, elementIndex, rawValue] = indexedAssignment;
+                const element = parseShellWords(rawValue);
+                if (element?.length !== 1)
+                    variables.delete(name);
+                else {
+                    const array = [...(variables.get(name)?.array ?? [])];
+                    array[Number(elementIndex)] = element[0];
+                    variables.set(name, { array });
+                }
+                result.push(`${name}=__OURO_ARRAY_LITERAL`);
+                index += indexedAssignment[0].length - 1;
+                continue;
+            }
+            const scalarAssignment = shellMatchAt(SHELL_SCALAR_ASSIGNMENT, command, index);
+            if (scalarAssignment) {
+                const [, name, rawValue] = scalarAssignment;
+                const scalar = parseShellWords(rawValue);
+                if (shellAssignmentPersists(command, index + scalarAssignment[0].length)) {
+                    if (scalar?.length === 1)
+                        variables.set(name, { scalar: scalar[0] });
+                    else
+                        variables.delete(name);
+                }
+                result.push(scalarAssignment[0]);
+                index += scalarAssignment[0].length - 1;
+                continue;
+            }
+        }
+        if (quote !== "single" && character === "$") {
+            const arrayExpansion = shellMatchAt(SHELL_ARRAY_PARAMETER, command, index);
+            if (arrayExpansion) {
+                const [, name, mode] = arrayExpansion;
+                const elements = variables.get(name)?.array;
+                if (elements === undefined)
+                    result.push(SHELL_ARRAY_EXPANSION);
+                else if (quote === "double" && mode === "@") {
+                    const closing = closingDoubleQuote(command, index + arrayExpansion[0].length);
+                    const prefix = doubleQuotedFragment(command.slice(doubleQuoteStart + 1, index));
+                    const suffix = closing < 0 ? undefined : doubleQuotedFragment(command.slice(index + arrayExpansion[0].length, closing));
+                    if (closing < 0 || prefix === undefined || suffix === undefined)
+                        result.push(SHELL_ARRAY_EXPANSION);
+                    else {
+                        const presentElements = elements.filter((element) => element !== undefined);
+                        const expanded = presentElements.length === 0
+                            ? (prefix.length + suffix.length === 0 ? [] : [`${prefix}${suffix}`])
+                            : presentElements.map((element, elementIndex) => `${elementIndex === 0 ? prefix : ""}${element}${elementIndex === presentElements.length - 1 ? suffix : ""}`);
+                        result.splice(doubleQuoteResultIndex);
+                        result.push((0, shell_quote_1.quote)(expanded));
+                        quote = null;
+                        doubleQuoteStart = -1;
+                        doubleQuoteResultIndex = -1;
+                        index = closing;
+                        continue;
+                    }
+                }
+                else if (quote === "double")
+                    result.push(elements.join(" "));
+                else
+                    result.push(shellUnquotedFields(elements));
+                index += arrayExpansion[0].length - 1;
+                continue;
+            }
+            const scalarExpansion = shellMatchAt(SHELL_SCALAR_PARAMETER, command, index);
+            if (scalarExpansion) {
+                const name = scalarExpansion[1] ?? scalarExpansion[2];
+                const scalar = variables.get(name)?.scalar;
+                if (scalar !== undefined) {
+                    if (quote === "double")
+                        result.push(scalar.replace(/["\\$`]/g, "\\$&"));
+                    else
+                        result.push(shellUnquotedFields([scalar]));
+                    index += scalarExpansion[0].length - 1;
+                    continue;
+                }
+                if (quote === null) {
+                    result.push(SHELL_ARRAY_EXPANSION);
+                    index += scalarExpansion[0].length - 1;
+                    continue;
+                }
+            }
+        }
+        result.push(character);
+    }
+    return result.join("");
+}
+function findCommandSubstitutionEnd(command, start) {
+    let depth = 1;
+    let quote = null;
+    for (let index = start; index < command.length; index += 1) {
+        const character = command[index];
+        if (character === "\\" && quote !== "single") {
+            index += 1;
+            continue;
+        }
+        if (character === "'" && quote !== "double") {
+            quote = quote === "single" ? null : "single";
+            continue;
+        }
+        if (character === '"' && quote !== "single") {
+            quote = quote === "double" ? null : "double";
+            continue;
+        }
+        if (quote !== null)
+            continue;
+        if (character === "(")
+            depth += 1;
+        else if (character === ")") {
+            depth -= 1;
+            if (depth === 0)
+                return index;
+        }
+    }
+    return -1;
+}
+function exposeShellSubstitutions(command, depth = 0) {
+    if (depth >= 32)
+        return "ouro mail sync-cache";
+    let outer = "";
+    const nested = [];
+    let quote = null;
+    for (let index = 0; index < command.length; index += 1) {
+        const character = command[index];
+        if (character === "\\" && quote !== "single") {
+            outer += character + (command[index + 1] ?? "");
+            index += 1;
+            continue;
+        }
+        if (character === "'" && quote !== "double") {
+            quote = quote === "single" ? null : "single";
+            outer += character;
+            continue;
+        }
+        if (character === '"' && quote !== "single") {
+            quote = quote === "double" ? null : "double";
+            outer += character;
+            continue;
+        }
+        if (quote !== "single" && command.startsWith("$(", index) && !command.startsWith("$((", index)) {
+            const end = findCommandSubstitutionEnd(command, index + 2);
+            if (end >= 0) {
+                nested.push(exposeShellSubstitutions(command.slice(index + 2, end), depth + 1));
+                outer += "${__OURO_COMMAND_SUBSTITUTION}";
+                index = end;
+                continue;
+            }
+        }
+        if (quote !== "single" && character === "`") {
+            let end = index + 1;
+            while (end < command.length && command[end] !== "`") {
+                if (command[end] === "\\")
+                    end += 1;
+                end += 1;
+            }
+            if (end < command.length) {
+                nested.push(exposeShellSubstitutions(command.slice(index + 1, end), depth + 1));
+                outer += "${__OURO_COMMAND_SUBSTITUTION}";
+                index = end;
+                continue;
+            }
+        }
+        outer += character;
+    }
+    return [outer, ...nested].join("\n");
+}
+function normalizeShellNewlines(command) {
+    let result = "";
+    let quote = null;
+    for (let index = 0; index < command.length; index += 1) {
+        const character = command[index];
+        if (character === "\\" && quote !== "single") {
+            result += character + (command[index + 1] ?? "");
+            index += 1;
+            continue;
+        }
+        if (character === "'" && quote !== "double")
+            quote = quote === "single" ? null : "single";
+        else if (character === '"' && quote !== "single")
+            quote = quote === "double" ? null : "double";
+        result += character === "\n" && quote === null ? " ; " : character;
+    }
+    return result;
+}
+function executableShellView(command) {
+    const withoutData = stripShellComments(stripHereDocBodies(command));
+    return normalizeShellNewlines(transformOrderedShellVariables(exposeShellSubstitutions(withoutData)));
+}
+function parseShellCommands(command) {
+    let parameterIndex = 0;
+    const parameterNames = new Map();
+    const entries = (0, shell_quote_1.parse)(command, (name) => {
+        const marker = `${SHELL_PARAMETER_MARKER}${parameterIndex}__`;
+        parameterIndex += 1;
+        parameterNames.set(marker, name);
+        return marker;
+    });
+    const commands = [];
+    let current = [];
+    let skipRedirectionTarget = false;
+    const flush = () => {
+        if (current.length > 0)
+            commands.push(current);
+        current = [];
+        skipRedirectionTarget = false;
+    };
+    for (const entry of entries) {
+        if (typeof entry === "string") {
+            if (skipRedirectionTarget)
+                skipRedirectionTarget = false;
+            else if (SHELL_TOKEN_BOUNDARIES.has(entry.toLowerCase()))
+                flush();
+            else
+                current.push(entry);
+            continue;
+        }
+        const operation = entry;
+        if (operation.op === "glob") {
+            current.push(operation.pattern);
+            continue;
+        }
+        if (SHELL_COMMAND_BOUNDARIES.has(operation.op)) {
+            flush();
+            continue;
+        }
+        // Every remaining control operator is a redirection. Its next string is
+        // a path or descriptor, not an argv token.
+        skipRedirectionTarget = true;
+    }
+    flush();
+    return { commands, parameterNames };
+}
+function resolveKnownShellParameters(token, knownVariables, parameterNames) {
+    let resolved = token;
+    for (const [marker, name] of parameterNames) {
+        const known = knownVariables.get(name);
+        if (known !== undefined)
+            resolved = resolved.replaceAll(marker, known);
+    }
+    return resolved;
+}
+function shellTokenCanEqual(token, expected) {
+    const escaped = token
+        .split(new RegExp(`(?:${SHELL_PARAMETER_MARKER}\\d+__|${SHELL_ARRAY_EXPANSION})`, "g"))
+        .map((literal) => literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+        .join(".*");
+    return new RegExp(`^${escaped}$`, "i").test(expected);
+}
+function shellExecutableCanEqual(token, expected) {
+    const basenameToken = token.slice(token.lastIndexOf("/") + 1);
+    return shellTokenCanEqual(basenameToken, expected);
+}
+function exactShellExecutable(token) {
+    if (token === undefined || token.includes(SHELL_PARAMETER_MARKER))
+        return undefined;
+    return token.slice(token.lastIndexOf("/") + 1).toLowerCase();
+}
+const SUDO_SHORT_OPERANDS = new Set(["-C", "-D", "-g", "-h", "-p", "-R", "-r", "-T", "-t", "-U", "-u"]);
+const SUDO_LONG_OPERANDS = new Set(["--chdir", "--chroot", "--close-from", "--command-timeout", "--group", "--host", "--other-user", "--prompt", "--role", "--type", "--user"]);
+const TIME_SHORT_OPERANDS = new Set(["-f", "-o"]);
+const TIME_LONG_OPERANDS = new Set(["--format", "--output"]);
+function wrapperOptionAdvance(option, shortOperands, longOperands) {
+    if (shortOperands.has(option) || longOperands.has(option))
+        return 2;
+    if ([...shortOperands].some((candidate) => option.startsWith(candidate) && option.length > candidate.length))
+        return 1;
+    if ([...longOperands].some((candidate) => option.startsWith(`${candidate}=`)))
+        return 1;
+    return 0;
+}
+function resolveShellCommand(tokens, startIndex) {
+    let index = startIndex;
+    while (index < tokens.length) {
+        const executable = exactShellExecutable(tokens[index]);
+        if (SHELL_GRAMMAR_PREFIXES.has(executable ?? "")) {
+            index += 1;
+            continue;
+        }
+        if (executable === "coproc") {
+            index += 1;
+            const candidate = tokens[index] ?? "";
+            if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(candidate) && !shellExecutableCanEqual(candidate, "ouro") && tokens[index + 1] !== undefined)
+                index += 1;
+            continue;
+        }
+        if (executable === "command" || executable === "nohup") {
+            index += 1;
+            if (executable === "command" && (tokens[index] === "-v" || tokens[index] === "-V"))
+                return { index: tokens.length };
+            while (tokens[index]?.startsWith("-"))
+                index += 1;
+            continue;
+        }
+        if (executable === "env") {
+            index += 1;
+            while (index < tokens.length) {
+                const option = tokens[index];
+                if (option === "-S" || option === "--split-string")
+                    return { index, script: `env ${tokens.slice(index + 1).join(" ")}` };
+                if (option.startsWith("--split-string="))
+                    return { index, script: `env ${[option.slice("--split-string=".length), ...tokens.slice(index + 1)].join(" ")}` };
+                if (["-u", "-C", "--unset", "--chdir"].includes(option))
+                    index += 2;
+                else if (option.startsWith("-") || /^[A-Za-z_][A-Za-z0-9_]*=/.test(option))
+                    index += 1;
+                else
+                    break;
+            }
+            continue;
+        }
+        if (executable === "sudo") {
+            index += 1;
+            while (tokens[index]?.startsWith("-")) {
+                const advance = wrapperOptionAdvance(tokens[index], SUDO_SHORT_OPERANDS, SUDO_LONG_OPERANDS);
+                index += advance === 0 ? 1 : advance;
+            }
+            continue;
+        }
+        if (executable === "time") {
+            index += 1;
+            while (tokens[index]?.startsWith("-")) {
+                const advance = wrapperOptionAdvance(tokens[index], TIME_SHORT_OPERANDS, TIME_LONG_OPERANDS);
+                index += advance === 0 ? 1 : advance;
+            }
+            continue;
+        }
+        if (executable === "exec") {
+            index += 1;
+            while (tokens[index]?.startsWith("-"))
+                index += tokens[index] === "-a" ? 2 : 1;
+            continue;
+        }
+        break;
+    }
+    return { index };
+}
+function shellScriptRequiresFamily(script, variables, depth) {
+    if (script.includes(SHELL_PARAMETER_MARKER) || script.includes(SHELL_ARRAY_EXPANSION))
+        return true;
+    return shellCommandsContainMailCacheSync(script, variables, depth + 1);
+}
+function shellTokensContainMailCacheSync(tokens, startIndex, variables, depth) {
+    const resolved = resolveShellCommand(tokens, startIndex);
+    if (resolved.script !== undefined)
+        return shellScriptRequiresFamily(resolved.script, variables, depth);
+    const executableToken = tokens[resolved.index] ?? "";
+    const executable = exactShellExecutable(executableToken);
+    if (executableToken.includes(SHELL_ARRAY_EXPANSION))
+        return true;
+    if (SHELL_INTERPRETERS.has(executable ?? "")) {
+        const commandOption = tokens.findIndex((token, index) => index > resolved.index && /^-[^-]*c/.test(token));
+        return commandOption >= 0
+            && shellScriptRequiresFamily(tokens[commandOption + 1] ?? "", variables, depth);
+    }
+    if (executable === "eval")
+        return shellScriptRequiresFamily(tokens.slice(resolved.index + 1).join(" "), variables, depth);
+    return shellExecutableCanEqual(executableToken, "ouro")
+        && shellTokenCanEqual(tokens[resolved.index + 1] ?? "", "mail")
+        && shellTokenCanEqual(tokens[resolved.index + 2] ?? "", "sync-cache");
+}
+function shellCommandsContainMailCacheSync(command, inheritedVariables = new Map(), depth = 0) {
+    if (depth >= 32)
+        return true;
+    let parsed;
+    try {
+        parsed = parseShellCommands(command);
+    }
+    catch {
+        return false;
+    }
+    const knownVariables = new Map(inheritedVariables);
+    for (const rawTokens of parsed.commands) {
+        const tokens = rawTokens.map((token) => resolveKnownShellParameters(token, knownVariables, parsed.parameterNames));
+        const invocationVariables = new Map(knownVariables);
+        let commandIndex = 0;
+        while (commandIndex < tokens.length) {
+            const assignment = tokens[commandIndex].match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/s);
+            if (!assignment)
+                break;
+            if (assignment[2].includes(SHELL_PARAMETER_MARKER))
+                invocationVariables.delete(assignment[1]);
+            else
+                invocationVariables.set(assignment[1], assignment[2]);
+            commandIndex += 1;
+        }
+        if (commandIndex === tokens.length) {
+            knownVariables.clear();
+            for (const [name, value] of invocationVariables)
+                knownVariables.set(name, value);
+            continue;
+        }
+        if (shellTokensContainMailCacheSync(tokens, commandIndex, invocationVariables, depth))
+            return true;
+    }
+    return false;
+}
+function shellContainsMailCacheSync(command) {
+    const executableCommand = executableShellView(command);
+    if (shellContainsAmbiguousAnsiMailCacheSync(executableCommand))
+        return true;
+    return shellCommandsContainMailCacheSync(executableCommand);
+}
+function mailCacheSyncShellGuardrail(toolName, args, context) {
+    if (toolName !== "shell" || !shellContainsMailCacheSync(args.command ?? ""))
+        return allow;
+    if (context.trustLevel === undefined || context.trustLevel === "family")
+        return allow;
+    return deny("hosted mail cache convergence requires family trust.");
+}
 function mailTrustGuardrail(toolName, args, context) {
     if (MAIL_FAMILY_TOOLS.has(toolName)) {
         if (context.trustLevel === undefined || context.trustLevel === "family")
@@ -360,6 +1031,9 @@ function checkFirstClassMcpTrust(context) {
     return allow;
 }
 function checkTrustLevelGuardrails(toolName, args, context) {
+    const cacheSyncResult = mailCacheSyncShellGuardrail(toolName, args, context);
+    if (!cacheSyncResult.allowed)
+        return cacheSyncResult;
     const mailResult = mailTrustGuardrail(toolName, args, context);
     if (!mailResult.allowed)
         return mailResult;