evolcore 0.0.20 → 0.0.21

package/dist/core/permission/mode.js

@@ -1,8 +1,22 @@
 export const PUBLIC_PERMISSION_MODES = ['readonly', 'auto', 'request', 'bypass'];
+export const FULL_ACCESS_PERMISSION_MODE = 'fullaccess';
 export function isPublicPermissionMode(value) {
     return typeof value === 'string'
         && PUBLIC_PERMISSION_MODES.includes(value);
 }
+export function isExecutionPermissionMode(value) {
+    return value === FULL_ACCESS_PERMISSION_MODE || isPublicPermissionMode(value);
+}
+/**
+ * Normalize a trusted execution-call mode without exposing fullaccess as a
+ * role/session configuration value. Legacy persisted public values retain the
+ * same migration behavior as normalizePermissionMode().
+ */
+export function normalizeExecutionPermissionMode(value) {
+    if (value === FULL_ACCESS_PERMISSION_MODE)
+        return FULL_ACCESS_PERMISSION_MODE;
+    return normalizePermissionMode(value).mode;
+}
 /**
  * Normalize persisted legacy values at the runtime boundary.
  *
@@ -27,13 +41,14 @@ export function normalizePermissionMode(value) {
  * owner running in bypass mode. Every other combination remains fail-closed.
  */
 export function resolvePhaseOneExecutionSandbox(permissionMode, role) {
-    const normalizedMode = normalizePermissionMode(permissionMode).mode;
+    const normalizedMode = normalizeExecutionPermissionMode(permissionMode);
     const normalizedRole = role ?? undefined;
-    const sandboxOff = normalizedMode === 'bypass' && normalizedRole === 'owner';
+    const fullAccess = normalizedMode === FULL_ACCESS_PERMISSION_MODE;
+    const sandboxOff = fullAccess || (normalizedMode === 'bypass' && normalizedRole === 'owner');
     return {
         permissionMode: normalizedMode,
         role: normalizedRole,
         state: sandboxOff ? 'off' : 'active',
-        reason: sandboxOff ? 'owner-bypass' : 'phase-one-required',
+        reason: fullAccess ? 'fullaccess' : sandboxOff ? 'owner-bypass' : 'phase-one-required',
     };
 }

package/dist/core/{protected-paths.js → permission/protected-paths.js}

@@ -1,6 +1,6 @@
 import fs from 'fs';
 import path from 'path';
-import { resolveRoot } from '../paths.js';
+import { resolveRoot } from '../../paths.js';
 const H_CLASS_RELATIVE_PATTERNS = [
     /^daemon\.json$/,
     /^agents\/defaults\.json$/,
@@ -28,13 +28,13 @@ const H_CLASS_RELATIVE_PATTERNS = [
     /^data\/outbox(?:\/|$)/,
     /^data\/handoff(?:\/|$)/,
     /^agents\/[^/]+\/sessions(?:\/|$)/,
-    /^agents\/[^/]+\/data\/(?:channels(?:\/|$)|handoff(?:\/|$)|outbox\.jsonl(?:_|__|\.tmp-.*)?$|contact-audit\.jsonl$)/,
+    /^agents\/[^/]+\/data\/(?:channels(?:\/|$)|handoff(?:\/|$)|(?:outbox|activity-outbox)\.jsonl(?:_|__|\.tmp-.*)?$|contact-audit\.jsonl$)/,
 ];
 const H_CLASS_REFERENCE_PATTERNS = [
     /(?:^|[^A-Za-z0-9_.-])daemon\.json(?=$|[^A-Za-z0-9_.-])/,
     /(?:^|[^A-Za-z0-9_.-])agents[\\/](?:defaults\.json|[^/\\\s"']+[\\/](?:(?:config|contact)\.json|contact-operations\.jsonl|relations[\\/][^/\\\s"']+[\\/]config\.json))(?=$|[\s"';&|<>)},])/,
     /(?:^|[^A-Za-z0-9_.-])(?:backups[\\/]config|\.snapshots|CA|(?:AIDs|aids)[\\/][^/\\\s"']+[\\/](?:cert|keys|private))(?:[\\/]|$|[\s"';&|<>)},])/,
-    /(?:^|[/\\\s"'=<>])(?:\.device_id|\.env|\.seed(?:\.[^/\\\s"']*)?|\.migrated-[^/\\\s"']*|\.lock|daemon\.pid|data[\\/](?:causation-aun\.json(?:_|__)?|sessions|contact-book-audit\.jsonl|feishu-seen-[^/\\\s"']+\.jsonl|[a-z0-9_-]+-greeted-[^/\\\s"']+\.jsonl|message-queue\.json(?:_|__|\.tmp-[^/\\\s"']*)?|daemon[\\/](?:message-queue\.json(?:_|__|\.tmp-[^/\\\s"']*)?|control|migrations)|channel-state|instance[\\/]control\.token|outbox|handoff)|agents[\\/][^/\\\s"']+[\\/](?:sessions|data[\\/](?:channels|handoff|outbox\.jsonl|contact-audit\.jsonl)))(?:[\\/]|$|[\s"';&|<>)},])/,
+    /(?:^|[/\\\s"'=<>])(?:\.device_id|\.env|\.seed(?:\.[^/\\\s"']*)?|\.migrated-[^/\\\s"']*|\.lock|daemon\.pid|data[\\/](?:causation-aun\.json(?:_|__)?|sessions|contact-book-audit\.jsonl|feishu-seen-[^/\\\s"']+\.jsonl|[a-z0-9_-]+-greeted-[^/\\\s"']+\.jsonl|message-queue\.json(?:_|__|\.tmp-[^/\\\s"']*)?|daemon[\\/](?:message-queue\.json(?:_|__|\.tmp-[^/\\\s"']*)?|control|migrations)|channel-state|instance[\\/]control\.token|outbox|handoff)|agents[\\/][^/\\\s"']+[\\/](?:sessions|data[\\/](?:channels|handoff|(?:outbox|activity-outbox)\.jsonl|contact-audit\.jsonl)))(?:[\\/]|$|[\s"';&|<>)},])/,
     /(?:^|[/\\\s"'=<>])data[\\/]triggers(?:[\\/]|$|[\s"';&|<>)},])/,
     /(?:^|[/\\\s"'=<>])(?:[^/\\\s"']+\.json_|[^/\\\s"']+\.json\.migrated|defaults_\d+\.json)(?=$|[\s"';&|<>)},])/,
 ];
@@ -287,6 +287,7 @@ export function getHClassSandboxPatterns(root = resolveRoot()) {
         path.join('agents', '*', 'data', 'channels', '**'),
         path.join('agents', '*', 'data', 'handoff', '**'),
         path.join('agents', '*', 'data', 'outbox.jsonl*'),
+        path.join('agents', '*', 'data', 'activity-outbox.jsonl*'),
         path.join('agents', '*', 'data', 'contact-audit.jsonl'),
     ];
     return entries.map(entry => path.join(absoluteRoot, entry));
@@ -369,6 +370,7 @@ export function getExistingHClassMaskTargets(root = resolveRoot()) {
             addExistingTarget(targets, path.join(agentRoot, 'data', 'channels'));
             addExistingTarget(targets, path.join(agentRoot, 'data', 'handoff'));
             addExistingTarget(targets, path.join(agentRoot, 'data', 'outbox.jsonl'));
+            addExistingTarget(targets, path.join(agentRoot, 'data', 'activity-outbox.jsonl'));
             addExistingTarget(targets, path.join(agentRoot, 'data', 'contact-audit.jsonl'));
         }
     }
@@ -435,12 +437,22 @@ export function buildCodexHClassFilesystemRules(root = resolveRoot()) {
 export function buildCodexProtectedFilesystemRules(root = resolveRoot(), options = {}) {
     const lClassRules = {};
     const lClassAccess = options.denyLClassRead ? 'deny' : 'read';
+    // Codex's Linux sandbox expands glob deny rules into per-file mount targets.
+    // When an outer H-class guard has already mounted the L-class directory
+    // read-only, that expansion can race with the mount and fail before the
+    // command starts (for example while creating triggers/history.jsonl).
+    // Directory-level deny is sufficient for the policy bridge and avoids the
+    // nested bwrap per-file projection. Callers on platforms without that
+    // outer guard retain the historical expansion by default.
+    const expandLClassReadDeny = options.expandLClassReadDeny ?? true;
     for (const target of getExistingLClassReadOnlyTargets(root)) {
         if (target.kind === 'directory') {
-            if (options.denyLClassRead || path.basename(target.path) === 'triggers') {
+            if (!expandLClassReadDeny || options.denyLClassRead || path.basename(target.path) === 'triggers') {
                 lClassRules[target.path] = lClassAccess;
             }
-            lClassRules[path.join(target.path, '**')] = lClassAccess;
+            if (expandLClassReadDeny || !options.denyLClassRead) {
+                lClassRules[path.join(target.path, '**')] = lClassAccess;
+            }
         }
         else {
             lClassRules[target.path] = lClassAccess;

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

@@ -3,7 +3,8 @@ 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',
+    'echo', 'pwd', 'ls', 'cat', 'grep', 'rg', 'find', 'sed', 'head', 'sort', 'git', 'wc', 'stat', 'lstat', 'awk',
+    'bash', 'sh',
 ]);
 const FIND_MUTATING_PRIMARY_RE = /^-(?:delete|exec|execdir|ok|okdir|fprint|fprint0|fprintf|fls)$/;
 const RG_PROCESS_SPAWNING_OPTION_RE = /^(?:--pre|--hostname-bin|--pre-glob|--search-zip)(?:=|$)/;
@@ -113,6 +114,22 @@ function exact(value) {
 function recursive(value) {
     return { value, access: 'recursive' };
 }
+function isLiteralGitPathspec(value) {
+    // Git pathspec magic and wildcards can expand a seemingly harmless token to
+    // protected files elsewhere in the repository. The readonly diagnostic
+    // capability accepts only a literal path or directory scope.
+    return !!value
+        && !value.startsWith('-')
+        && !value.startsWith(':')
+        && !/[\0*?[\\]/.test(value);
+}
+function isLikelyGitPath(value) {
+    // Before `--`, Git accepts both revisions and pathspecs. Only classify
+    // tokens with an unmistakable path shape here; bare names such as `HEAD`
+    // and `main` remain revision selectors and do not become filesystem scope.
+    return isLiteralGitPathspec(value)
+        && (value === '.' || value === '..' || value.includes('/') || value.startsWith('.') || /\.[A-Za-z0-9_-]+$/.test(value));
+}
 function parseOptionsAndPaths(args, valueOptions, recursiveOptions = new Set()) {
     const paths = [];
     let optionsEnded = false;
@@ -472,9 +489,10 @@ function analyzeSort(args) {
 /**
  * Git metadata queries do not expose file contents and their output paths are
  * controlled by the repository, not by arbitrary shell operands. Keep this
- * deliberately small: status and read-only diff summaries are the patterns
- * used for workspace diagnostics. Mutating subcommands and pathspecs remain
- * unproven so the normal H-class checks still apply.
+ * deliberately small: status, bounded diff summaries, pickaxe log queries,
+ * and blame are the patterns used for workspace diagnostics. Mutating
+ * subcommands and unrecognised options remain unproven so normal H/L checks
+ * still apply.
  */
 function analyzeGit(args) {
     if (args.length === 0)
@@ -502,6 +520,7 @@ function analyzeGit(args) {
     }
     if (subcommand === 'diff') {
         let sawSummary = false;
+        let noIndex = false;
         let optionsEnded = false;
         const paths = [];
         const allowedFlags = new Set([
@@ -518,17 +537,152 @@ function analyzeGit(args) {
                 if (arg === '--stat' || arg === '--shortstat' || arg === '--numstat'
                     || arg === '--name-only' || arg === '--name-status')
                     sawSummary = true;
+                if (arg === '--no-index')
+                    noIndex = true;
                 if (!allowedFlags.has(arg) && !/^[0-9a-f]{7,64}$/.test(arg))
                     return null;
                 continue;
             }
-            // Revisions are safe literals; pathspecs after -- are bounded exact reads.
-            if (optionsEnded)
-                paths.push({ value: arg, access: 'exact' });
-            else if (!/^[0-9A-Za-z._~^/:-]+$/.test(arg))
+            // A Git pathspec may name a directory or wildcard scope, so model it as
+            // recursive even when the token itself is literal. This keeps `-- .`
+            // from bypassing nested protected paths.
+            if (optionsEnded) {
+                if (!isLiteralGitPathspec(arg))
+                    return null;
+                paths.push(recursive(arg));
+            }
+            else if (noIndex) {
+                if (!isLiteralGitPathspec(arg))
+                    return null;
+                // `--no-index` compares two filesystem paths directly, so both
+                // operands must participate in workspace/H-class checks.
+                paths.push(recursive(arg));
+            }
+            else {
+                if (!/^[0-9A-Za-z._~^/:-]+$/.test(arg))
+                    return null;
+                if (isLikelyGitPath(arg))
+                    paths.push(recursive(arg));
+            }
+        }
+        if (!sawSummary)
+            return null;
+        if (noIndex && paths.length !== 2)
+            return null;
+        return paths;
+    }
+    if (subcommand === 'log') {
+        let optionsEnded = false;
+        let sawSearch = false;
+        const paths = [];
+        const valueOptions = new Set([
+            '-S', '-G', '--grep', '--author', '--committer', '--since', '--after', '--until', '--before',
+            '--format', '--pretty', '--max-count', '-n', '--skip', '--decorate-refs',
+        ]);
+        const allowedFlags = new Set([
+            '--all', '--branches', '--tags', '--remotes', '--oneline', '--no-patch', '--no-decorate', '--decorate',
+            '--follow', '--pickaxe-all', '--pickaxe-regex', '--reverse', '--topo-order', '--date-order',
+            '--author-date-order', '--first-parent', '--no-merges', '--merges', '--stat', '--shortstat',
+            '--name-only', '--name-status', '--no-renames', '--no-ext-diff', '--no-textconv', '--no-color',
+            '--color=never',
+        ]);
+        for (let index = 1; index < args.length; index++) {
+            const arg = args[index];
+            if (!optionsEnded && arg === '--') {
+                optionsEnded = true;
+                continue;
+            }
+            if (optionsEnded) {
+                if (!isLiteralGitPathspec(arg))
+                    return null;
+                paths.push(recursive(arg));
+                continue;
+            }
+            if (arg.startsWith('-')) {
+                const option = arg.split('=', 1)[0];
+                if (arg === '-S' || arg === '-G' || /^-[SG].+/.test(arg)) {
+                    sawSearch = true;
+                    if (arg.length === 2) {
+                        if (++index >= args.length)
+                            return null;
+                    }
+                    continue;
+                }
+                if (valueOptions.has(option)) {
+                    if (!arg.includes('=') && !arg.startsWith('-S') && !arg.startsWith('-G')) {
+                        if (++index >= args.length)
+                            return null;
+                    }
+                    continue;
+                }
+                if (!allowedFlags.has(arg) && !/^(?:[0-9A-Fa-f]{7,64}|HEAD(?:~[0-9]+)?|[A-Za-z0-9._/-]+\.\.\.?)$/.test(arg))
+                    return null;
+                continue;
+            }
+            // Revisions before `--` are metadata selectors, never filesystem paths.
+            if (!/^[A-Za-z0-9._~^/:@+-]+$/.test(arg))
+                return null;
+        }
+        return sawSearch && paths.length > 0 ? paths : null;
+    }
+    if (subcommand === 'blame') {
+        let optionsEnded = false;
+        let sawPath = false;
+        const paths = [];
+        const valueOptions = new Set(['-L', '--abbrev', '--date', '--ignore-rev']);
+        const pathValueOptions = new Set(['--ignore-revs-file', '--contents']);
+        const allowedFlags = new Set([
+            '--porcelain', '--line-porcelain', '--incremental', '--root', '--show-email', '--show-number',
+            '--show-name', '--reverse', '--progress', '--score-debug', '--encoding', '--no-progress',
+        ]);
+        for (let index = 1; index < args.length; index++) {
+            const arg = args[index];
+            if (!optionsEnded && arg === '--') {
+                optionsEnded = true;
+                continue;
+            }
+            if (optionsEnded) {
+                if (!isLiteralGitPathspec(arg) || sawPath)
+                    return null;
+                paths.push(exact(arg));
+                sawPath = true;
+                continue;
+            }
+            if (arg.startsWith('-')) {
+                const option = arg.split('=', 1)[0];
+                if (option === '-L' || option === '-C') {
+                    // `-L` takes a line range; `-C` is a repeatable flag with an
+                    // optional score and therefore must not consume the following path.
+                    if (option === '-L' && !arg.includes('=') && arg.length === 2
+                        && ++index >= args.length)
+                        return null;
+                    continue;
+                }
+                if (pathValueOptions.has(option)) {
+                    const value = arg.includes('=') ? arg.slice(arg.indexOf('=') + 1) : args[++index];
+                    if (!value)
+                        return null;
+                    paths.push(exact(value));
+                    continue;
+                }
+                if (valueOptions.has(option)) {
+                    if (!arg.includes('=') && ++index >= args.length)
+                        return null;
+                    continue;
+                }
+                if (!allowedFlags.has(arg))
+                    return null;
+                continue;
+            }
+            // The common diagnostic form is `git blame <path>`. Keep one literal
+            // path operand; callers that need a revision should use `-- <path>` so
+            // the boundary is unambiguous to the policy parser.
+            if (sawPath || !isLiteralGitPathspec(arg))
                 return null;
+            paths.push(exact(arg));
+            sawPath = true;
         }
-        return sawSummary ? paths : null;
+        return paths.length === 1 ? paths : null;
     }
     return null;
 }
@@ -574,6 +728,99 @@ function analyzeStat(args) {
     }
     return paths.length > 0 ? paths : null;
 }
+function analyzeAwk(args) {
+    let index = 0;
+    while (index < args.length && args[index].startsWith('-')) {
+        const option = args[index];
+        if (option === '--') {
+            index++;
+            break;
+        }
+        if (option === '-F') {
+            if (++index >= args.length)
+                return null;
+            index++;
+            continue;
+        }
+        if (option.startsWith('-F') && !option.startsWith('--') && option.length > 2) {
+            index++;
+            continue;
+        }
+        if (option === '-v' || option === '--assign') {
+            if (++index >= args.length)
+                return null;
+            index++;
+            continue;
+        }
+        if (option.startsWith('-v') && !option.startsWith('--') && option.length > 2) {
+            index++;
+            continue;
+        }
+        if (option === '--field-separator') {
+            if (++index >= args.length)
+                return null;
+            index++;
+            continue;
+        }
+        if (option.startsWith('--field-separator=') || option.startsWith('--assign=')) {
+            index++;
+            continue;
+        }
+        return null;
+    }
+    const program = args[index++];
+    // Permit the common formatting/filtering form while excluding awk's
+    // execution, file-redirection and shell escape features.
+    if (!program || !/^\{[\s\S]*\}$/.test(program)
+        || /\b(?:system|getline|close|nextfile)\b|(?:>>?|\|)|\b(?:delete|exit)\b/.test(program)
+        || /(^|[^=!<>])=([^=]|$)/.test(program))
+        return null;
+    const paths = args.slice(index).filter(value => value !== '-').map(exact);
+    return paths;
+}
+/**
+ * `bash -n`/`sh -n` only parses a script and never executes it.  Treat the
+ * script operands as exact reads, but keep every other shell option and
+ * nested command fail-closed.  This is intentionally narrower than allowing
+ * arbitrary `bash -c`, which would re-introduce an opaque shell carrier.
+ */
+function analyzeShellSyntaxCheck(args) {
+    if (args.length < 2)
+        return null;
+    let index = 0;
+    let sawNoExec = false;
+    while (index < args.length && args[index].startsWith('-') && args[index] !== '-') {
+        const option = args[index++];
+        if (option === '--') {
+            // The increment above already consumed the delimiter; the following
+            // token is the script path, not another option.
+            break;
+        }
+        if (option === '-n' || option === '--noexec') {
+            sawNoExec = true;
+            continue;
+        }
+        // `-n` may be combined with other bash flags, but only when the whole
+        // cluster is made of harmless parser flags. Do not accept flags that can
+        // select an inline command, source files, or alter execution semantics.
+        if (/^-[A-Za-z]*n[A-Za-z]*$/.test(option)
+            && !/[cCeEirsSx]/.test(option.replace(/^-/, ''))) {
+            sawNoExec = true;
+            continue;
+        }
+        return null;
+    }
+    if (!sawNoExec || index >= args.length)
+        return null;
+    const paths = [];
+    for (; index < args.length; index++) {
+        const value = args[index];
+        if (!value || value === '-' || value.startsWith('-'))
+            return null;
+        paths.push(exact(value));
+    }
+    return paths;
+}
 function analyzeCommand(argv) {
     const executable = normalizeExecutable(argv[0]);
     if (!executable)
@@ -623,6 +870,13 @@ function analyzeCommand(argv) {
             pathOperands = analyzeStat(args);
             accessKind = 'metadata';
             break;
+        case 'awk':
+            pathOperands = analyzeAwk(args);
+            break;
+        case 'bash':
+        case 'sh':
+            pathOperands = analyzeShellSyntaxCheck(args);
+            break;
     }
     if (!pathOperands)
         return null;

package/dist/core/permission/sandbox-runtime.js

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { resolveCommandPath } from '../../utils/cross-platform.js';
-import { getExistingHClassMaskTargets, getExistingLClassReadOnlyTargets, isSameOrDescendant, } from '../protected-paths.js';
+import { getExistingHClassMaskTargets, getExistingLClassReadOnlyTargets, isSameOrDescendant, } from './protected-paths.js';
 import { resolveRoot } from '../../paths.js';
 let cachedBubblewrapPath;
 let sandboxInitializationCircuit;
@@ -9,6 +9,7 @@ let sandboxCircuitNoticeAt = 0;
 export const SANDBOX_INITIALIZATION_FAILED = 'sandbox_initialization_failed';
 export const SANDBOX_INITIALIZATION_COOLDOWN_MS = 5 * 60 * 1000;
 export const SANDBOX_CIRCUIT_NOTICE_INTERVAL_MS = 60 * 1000;
+const SANDBOX_DIAGNOSTIC_TARGET_LIMIT = 256;
 /** Open a process-wide fail-closed circuit after a confirmed host bootstrap failure. */
 export function recordSandboxInitializationFailure(error, stderr = [], now = Date.now()) {
     const detail = createSandboxInitializationError(error, stderr).message.slice(0, 512);
@@ -218,6 +219,163 @@ function pushMaskedDirectory(args, candidate) {
         return;
     args.push('--tmpfs', candidate);
 }
+function decodeMountInfoPath(value) {
+    // mountinfo escapes whitespace, backslashes, and newlines as octal bytes.
+    return value.replace(/\\([0-7]{3})/g, (_match, octal) => {
+        const code = Number.parseInt(octal, 8);
+        return Number.isNaN(code) ? _match : String.fromCharCode(code);
+    });
+}
+function readMountInfoForPaths(paths, priorityPaths = []) {
+    if (process.platform !== 'linux' || paths.length === 0)
+        return [];
+    let contents;
+    try {
+        contents = fs.readFileSync('/proc/self/mountinfo', 'utf8');
+    }
+    catch (error) {
+        return [`mountinfo unavailable: ${error instanceof Error ? error.message : String(error)}`];
+    }
+    const wanted = paths.map(candidate => path.resolve(candidate));
+    const priority = priorityPaths.map(candidate => path.resolve(candidate));
+    const matches = [];
+    for (const [order, line] of contents.split(/\r?\n/).filter(Boolean).entries()) {
+        const mountPointField = line.split(' - ', 1)[0]?.split(' ')[4];
+        if (!mountPointField)
+            continue;
+        const mountPoint = path.resolve(decodeMountInfoPath(mountPointField));
+        if (!wanted.some(target => isSameOrDescendant(target, mountPoint)
+            || isSameOrDescendant(mountPoint, target)))
+            continue;
+        const isPriority = priority.some(target => target === mountPoint);
+        const isPriorityAncestor = !isPriority && priority.some(target => isSameOrDescendant(target, mountPoint));
+        matches.push({ line, score: isPriority ? 0 : isPriorityAncestor ? 1 : 2, order });
+    }
+    return matches
+        .sort((left, right) => left.score - right.score || left.order - right.order)
+        .slice(0, 32)
+        .map(match => match.line);
+}
+function snapshotSandboxPath(candidate) {
+    const resolved = path.resolve(candidate);
+    try {
+        const stat = fs.lstatSync(resolved);
+        let kind = 'other';
+        if (stat.isFile())
+            kind = 'file';
+        else if (stat.isDirectory())
+            kind = 'directory';
+        else if (stat.isSymbolicLink())
+            kind = 'symlink';
+        let realpath;
+        try {
+            realpath = fs.realpathSync(resolved);
+        }
+        catch { }
+        return {
+            path: resolved,
+            exists: true,
+            kind,
+            dev: stat.dev,
+            ino: stat.ino,
+            mode: stat.mode & 0o7777,
+            uid: stat.uid,
+            gid: stat.gid,
+            nlink: stat.nlink,
+            size: stat.size,
+            mtimeMs: stat.mtimeMs,
+            ctimeMs: stat.ctimeMs,
+            ...(realpath ? { realpath } : {}),
+        };
+    }
+    catch (error) {
+        const code = error.code;
+        return {
+            path: resolved,
+            exists: false,
+            ...(code ? { error: code } : { error: error instanceof Error ? error.message : String(error) }),
+        };
+    }
+}
+/** Capture the host-side state used to construct an H-class guard. */
+export function collectSandboxGuardDiagnostics(root = resolveRoot()) {
+    const absoluteRoot = path.resolve(root);
+    const candidates = [
+        path.join(absoluteRoot, 'data', 'causation-aun.json'),
+        path.join(absoluteRoot, 'data', 'causation-aun.json_'),
+        path.join(absoluteRoot, 'data', 'causation-aun.json__'),
+    ];
+    let targets = [];
+    try {
+        targets = getExistingHClassMaskTargets(absoluteRoot).map(target => target.path);
+    }
+    catch { }
+    // Keep the causation file and its atomic-write sidecars first. The full H
+    // target list can grow with the number of agents and must not turn every
+    // launch into an unbounded log payload.
+    const paths = [...new Set([...candidates, ...targets])];
+    const selectedPaths = paths.slice(0, SANDBOX_DIAGNOSTIC_TARGET_LIMIT);
+    return {
+        root: absoluteRoot,
+        targetCount: paths.length,
+        targetsTruncated: paths.length > selectedPaths.length,
+        targets: selectedPaths.map(snapshotSandboxPath),
+        mountInfo: readMountInfoForPaths(selectedPaths, candidates),
+    };
+}
+/** Reduce path and mount diagnostics to metadata suitable for INFO logs. */
+export function summarizeSandboxGuardDiagnostics(diagnostics) {
+    let existingTargetCount = 0;
+    let missingTargetCount = 0;
+    const targetKindCounts = {};
+    for (const target of diagnostics.targets) {
+        if (!target.exists) {
+            missingTargetCount += 1;
+            continue;
+        }
+        existingTargetCount += 1;
+        const kind = target.kind ?? 'unknown';
+        targetKindCounts[kind] = (targetKindCounts[kind] ?? 0) + 1;
+    }
+    return {
+        root: diagnostics.root,
+        targetCount: diagnostics.targetCount,
+        targetsTruncated: diagnostics.targetsTruncated,
+        existingTargetCount,
+        missingTargetCount,
+        targetKindCounts,
+        mountInfoCount: diagnostics.mountInfo.length,
+    };
+}
+/** Keep the exact mount portion of a bwrap argv while summarizing child argv. */
+export function summarizeBubblewrapArgs(args) {
+    const separator = args.indexOf('--');
+    const mountArgs = [...args.slice(0, separator >= 0 ? separator : args.length)];
+    const child = separator >= 0 ? args.slice(separator + 1) : [];
+    return {
+        mountArgs,
+        ...(child[0] ? { childCommand: child[0] } : {}),
+        childArgCount: Math.max(0, child.length - 1),
+    };
+}
+/** Keep only argument counts and option names for routine INFO logs. */
+export function summarizeBubblewrapArgsForLog(args) {
+    const separator = args.indexOf('--');
+    const mountArgs = args.slice(0, separator >= 0 ? separator : args.length);
+    const child = separator >= 0 ? args.slice(separator + 1) : [];
+    const mountOptionCounts = {};
+    for (const arg of mountArgs) {
+        if (!arg.startsWith('--'))
+            continue;
+        mountOptionCounts[arg] = (mountOptionCounts[arg] ?? 0) + 1;
+    }
+    return {
+        mountArgCount: mountArgs.length,
+        mountOptionCounts,
+        ...(child[0] ? { childCommand: child[0] } : {}),
+        childArgCount: Math.max(0, child.length - 1),
+    };
+}
 function appendRuntimeBackedEtcFiles(args) {
     if (process.platform !== 'linux' || !fs.existsSync('/run'))
         return;