browser-debugger-cli 0.14.0 → 0.16.0

package/dist/runtime/page/userAgent.js

@@ -2,52 +2,173 @@
  * The session's user agent in headless Chrome: regular Chrome's string and
  * client hints, so sites serve the page a user sees.
  */
+import { readFileSync } from 'node:fs';
+import os from 'node:os';
+import { createLogger } from '../../ui/logging/index.js';
 import { getErrorMessage } from '../../utils/errors.js';
-/** Reads the client hints Chrome reports, renaming the HeadlessChrome brand */
-const USER_AGENT_METADATA_SCRIPT = `(async () => {
-  const data = navigator.userAgentData;
-  if (!data) return null;
-  const values = await data.getHighEntropyValues(
-    ['architecture', 'bitness', 'model', 'platformVersion', 'fullVersionList', 'wow64']
-  );
-  const rename = (list) => (list || []).map((entry) => ({
-    brand: entry.brand.replace('HeadlessChrome', 'Google Chrome'),
-    version: entry.version,
-  }));
-  return {
-    brands: rename(values.brands),
-    fullVersionList: rename(values.fullVersionList),
-    platform: values.platform,
-    platformVersion: values.platformVersion,
-    architecture: values.architecture,
-    model: values.model,
-    mobile: values.mobile,
-    bitness: values.bitness,
-    wow64: values.wow64,
-  };
-})()`;
+const log = createLogger('session');
+/** Characters Chrome picks from for its made-up ("GREASE") brand name */
+const GREASE_CHARS = [' ', '(', ':', '-', '.', '/', ')', ';', '=', '?', '_'];
+/** Versions Chrome picks from for its made-up brand */
+const GREASE_VERSIONS = ['8', '99', '24'];
+/** Positions of the made-up brand, Chromium and the browser brand, by major version */
+const BRAND_ORDERS = [
+    [0, 1, 2],
+    [0, 2, 1],
+    [1, 0, 2],
+    [1, 2, 0],
+    [2, 0, 1],
+    [2, 1, 0],
+];
+/** Client-hint platform for each `process.platform` Chrome runs on */
+const HOST_PLATFORMS = {
+    darwin: 'macOS',
+    win32: 'Windows',
+    linux: 'Linux',
+};
+/** Client-hint platform for each platform token of the user agent string */
+const USER_AGENT_PLATFORMS = [
+    [/Android/, 'Android'],
+    [/CrOS/, 'Chrome OS'],
+    [/Macintosh/, 'macOS'],
+    [/Windows/, 'Windows'],
+    [/Linux|X11/, 'Linux'],
+];
+/**
+ * Chrome's brand list for a version, built the way Chrome builds it
+ * (`GenerateBrandVersionList` in Chromium's `user_agent_utils.cc`): a
+ * made-up brand, Chromium and the browser's brand, in an order and with a
+ * made-up name and version that depend on the major version.
+ *
+ * @param major - Major version (the seed)
+ * @param chromium - Chromium version to list
+ * @param browser - Browser brand and version
+ * @param greaseSuffix - Appended to the made-up version (`.0.0.0` in full versions)
+ * @returns Brand list
+ */
+export function chromeBrandList(major, chromium, browser, greaseSuffix = '') {
+    const grease = {
+        brand: `Not${GREASE_CHARS[major % GREASE_CHARS.length]}A${GREASE_CHARS[(major + 1) % GREASE_CHARS.length]}Brand`,
+        version: `${GREASE_VERSIONS[major % GREASE_VERSIONS.length]}${greaseSuffix}`,
+    };
+    const [greaseAt, chromiumAt, browserAt] = BRAND_ORDERS[major % BRAND_ORDERS.length] ?? [0, 1, 2];
+    const list = [];
+    list[greaseAt] = grease;
+    list[chromiumAt] = { brand: 'Chromium', version: chromium };
+    list[browserAt] = browser;
+    return list;
+}
+/**
+ * The client hints regular Chrome sends, for the browser `Browser.getVersion`
+ * describes. The browser brand is Microsoft Edge when the user agent says
+ * `Edg/`, Google Chrome otherwise (Chromium and Chrome for Testing look the
+ * same over CDP). Edge's Chromium version is only known to the major
+ * version. The OS version, architecture and bitness are the host's when it
+ * runs the platform the user agent names, empty otherwise (a remote Chrome).
+ *
+ * @param version - `Browser.getVersion` product and user agent
+ * @param host - The daemon's machine
+ * @returns Metadata for `Emulation.setUserAgentOverride`
+ */
+export function regularChromeMetadata(version, host) {
+    const fullVersion = /\/([\d.]+)/.exec(version.product)?.[1] ?? '';
+    const major = Number.parseInt(fullVersion, 10) || 0;
+    const isEdge = / Edg\//.test(version.userAgent);
+    const chromiumVersion = isEdge ? `${major}.0.0.0` : fullVersion;
+    const brand = isEdge ? 'Microsoft Edge' : 'Google Chrome';
+    const platform = USER_AGENT_PLATFORMS.find(([token]) => token.test(version.userAgent))?.[1] ?? host.platform;
+    const isHost = platform === host.platform;
+    return {
+        brands: chromeBrandList(major, String(major), { brand, version: String(major) }),
+        fullVersionList: chromeBrandList(major, chromiumVersion, { brand, version: fullVersion }, '.0.0.0'),
+        fullVersion,
+        platform,
+        platformVersion: isHost ? host.platformVersion : '',
+        architecture: isHost ? host.architecture : '',
+        bitness: isHost ? host.bitness : '',
+        model: '',
+        mobile: false,
+        wow64: false,
+        formFactors: ['Desktop'],
+    };
+}
+/** First Windows build of Windows 11, which client hints report as version 13 */
+const WINDOWS_11_BUILD = 22000;
+/**
+ * The OS version Chrome reports on Linux or Windows, from `os.release()`:
+ * the kernel version's first three numbers on Linux, and on Windows `13.0.0`
+ * for Windows 11 and `10.0.0` before it (Chrome reports a Windows API
+ * version there, not the OS build).
+ *
+ * @param platform - `process.platform`
+ * @param release - `os.release()`
+ * @returns OS version, or empty when unknown
+ */
+export function releasePlatformVersion(platform, release) {
+    if (platform === 'win32') {
+        const build = Number(release.split('.')[2]);
+        if (!build)
+            return '';
+        return build >= WINDOWS_11_BUILD ? '13.0.0' : '10.0.0';
+    }
+    return /^\d+(\.\d+){0,2}/.exec(release)?.[0] ?? '';
+}
+/**
+ * The OS version as Chrome reports it: the macOS product version (from
+ * `SystemVersion.plist`, as `sw_vers` prints it), or
+ * {@link releasePlatformVersion} elsewhere.
+ *
+ * @returns OS version, or empty when unknown
+ */
+function hostPlatformVersion() {
+    if (process.platform !== 'darwin')
+        return releasePlatformVersion(process.platform, os.release());
+    try {
+        const plist = readFileSync('/System/Library/CoreServices/SystemVersion.plist', 'utf8');
+        return /<key>ProductVersion<\/key>\s*<string>([\d.]+)<\/string>/.exec(plist)?.[1] ?? '';
+    }
+    catch (error) {
+        log.debug(`macOS version unknown: ${getErrorMessage(error)}`);
+        return '';
+    }
+}
+/**
+ * The daemon's machine as client hints describe it.
+ *
+ * @returns Platform, OS version, architecture and bitness
+ */
+export function hostPlatform() {
+    const arch = process.arch;
+    return {
+        platform: HOST_PLATFORMS[process.platform] ?? '',
+        platformVersion: hostPlatformVersion(),
+        architecture: arch.startsWith('arm') ? 'arm' : 'x86',
+        bitness: arch === 'arm64' || arch === 'x64' ? '64' : '32',
+    };
+}
 /**
  * Send the user agent and client hints of regular Chrome from headless
  * Chrome: sites serve "HeadlessChrome" a different page (or a bot
  * challenge), so the page would not be the one a user sees. Not for a
  * session emulating a phone, whose emulation sets a mobile user agent.
  *
+ * The client hints are built from `Browser.getVersion` and the host
+ * ({@link regularChromeMetadata}) rather than read from the page: the page is
+ * still `about:blank`, which has no `navigator.userAgentData`, and an
+ * override without metadata empties the client hints.
+ *
  * @param cdp - CDP connection
  * @param logger - Logger for failures (the session works without it)
+ * @param known - `Browser.getVersion` result, when the caller has it
  */
-export async function hideHeadlessUserAgent(cdp, logger) {
+export async function hideHeadlessUserAgent(cdp, logger, known) {
     try {
-        const { userAgent } = (await cdp.send('Browser.getVersion'));
-        if (!userAgent.includes('HeadlessChrome'))
+        const version = known ?? (await cdp.send('Browser.getVersion'));
+        if (!version.userAgent.includes('HeadlessChrome'))
             return;
-        const metadata = (await cdp.send('Runtime.evaluate', {
-            expression: USER_AGENT_METADATA_SCRIPT,
-            awaitPromise: true,
-            returnByValue: true,
-        }));
         await cdp.send('Emulation.setUserAgentOverride', {
-            userAgent: userAgent.replace('HeadlessChrome', 'Chrome'),
-            ...(metadata.result?.value ? { userAgentMetadata: metadata.result.value } : {}),
+            userAgent: version.userAgent.replace('HeadlessChrome', 'Chrome'),
+            userAgentMetadata: regularChromeMetadata(version, hostPlatform()),
         });
     }
     catch (error) {

package/dist/session/paths.d.ts

@@ -5,6 +5,7 @@
  * (or `~/.bdg/sessions/<name>/` for a named session).
  * WHY: Single source of truth for file locations prevents path inconsistencies.
  */
+import { type DirTrustKind } from '../utils/directories.js';
 /**
  * Session file paths relative to ~/.bdg/
  * Centralized definition for all session-related files.
@@ -123,12 +124,60 @@ export declare function getDaemonSocketPath(): string;
 /**
  * Ensure the session directory exists.
  *
- * Creates ~/.bdg/ if it doesn't exist. Safe to call multiple times (idempotent).
- * A path that cannot hold a directory is refused before `mkdir`, which
- * would spin on a pseudo-filesystem ({@link makeDirectory}).
+ * Creates it, and missing parents (the base directory, `sessions/`), with
+ * mode 0700. Safe to call multiple times (idempotent). A path that cannot
+ * hold a directory is refused before `mkdir`, which would spin on a
+ * pseudo-filesystem ({@link makeDirectory}).
  *
  * @throws Error if the directory cannot be created
  */
 export declare function ensureSessionDir(): void;
+/**
+ * The session's downloads directory (whether or not it exists).
+ *
+ * @returns Absolute path, `<session dir>/downloads`
+ */
+export declare function getSessionDownloadsDir(): string;
+/**
+ * Ensure the session's downloads directory exists (mode 0700, like the
+ * session directory) and return it.
+ *
+ * @returns Absolute path, `<session dir>/downloads`
+ * @throws Error if the directory cannot be created, or a file is in its place
+ */
+export declare function ensureSessionDownloadsDir(): string;
+/** A session directory (or one above it) that cannot be trusted */
+export interface UntrustedSessionDir {
+    /** The untrusted directory */
+    dir: string;
+    /** Why, e.g. `writable by others (mode 777)` */
+    reason: string;
+    kind: DirTrustKind;
+    /** bdg owns it by convention (`~/.bdg`, `sessions/`, `sessions/<name>`) */
+    bdgOwned: boolean;
+}
+/**
+ * Check that a session directory and the directories above it up to the base
+ * directory can be trusted before a daemon is started there or its socket is
+ * connected to: another user who can write to one of them could replace the
+ * socket (and receive every command) or plant files. Each existing directory
+ * must be a real directory (not a symlink), owned by the user, and not
+ * writable by others ({@link dirTrustProblem}); group write is accepted, since
+ * under umask 002 (per-user groups) older versions created `~/.bdg` 0775.
+ * The base directory may be a symlink whose target passes the same rule
+ * ({@link chainDirProblem}). A directory owned by another uid (a bind mount,
+ * `sudo -E`) is refused.
+ *
+ * Trusted directories bdg owns (the default `~/.bdg`, `sessions/` and named
+ * session directories) that group or others can still use are tightened to
+ * 0700; a base directory chosen with `$BDG_SESSION_DIR`, or a symlinked base
+ * (opened without following links), is never changed.
+ * Missing paths are skipped (as is a path through a file, which fails on its
+ * own): {@link ensureSessionDir} creates them 0700.
+ *
+ * @param dir - Session directory (default: the selected session's)
+ * @returns The first untrusted directory and why, or null
+ */
+export declare function secureSessionDir(dir?: string): UntrustedSessionDir | null;
 export {};
 //# sourceMappingURL=paths.d.ts.map

package/dist/session/paths.js

@@ -9,7 +9,8 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { createLogger, logDebugError } from '../ui/logging/index.js';
-import { makeDirectory } from '../utils/directories.js';
+import { dirTrustProblem, makeDirectory, } from '../utils/directories.js';
+import { getErrorMessage } from '../utils/errors.js';
 const log = createLogger('session');
 /**
  * Session file paths relative to ~/.bdg/
@@ -57,12 +58,21 @@ export const SESSION_STATE_FILES = [
  * @returns Full path to the base session directory
  */
 export function getSessionBaseDir() {
-    const override = process.env[SESSION_DIR_OVERRIDE_ENV];
-    if (override && override.trim().length > 0) {
+    const override = sessionDirOverride();
+    if (override !== null) {
         return path.isAbsolute(override) ? override : path.resolve(override);
     }
     return path.join(os.homedir(), '.bdg');
 }
+/**
+ * The base session directory the user chose with `$BDG_SESSION_DIR`.
+ *
+ * @returns The variable's value, or null when unset or blank (`~/.bdg`)
+ */
+function sessionDirOverride() {
+    const override = process.env[SESSION_DIR_OVERRIDE_ENV];
+    return override && override.trim().length > 0 ? override : null;
+}
 /**
  * The selected session name (`--session` / `BDG_SESSION`), lower-cased:
  * session names are case-insensitive.
@@ -163,16 +173,178 @@ export function getSessionFilePath(fileType) {
 export function getDaemonSocketPath() {
     return getSessionFilePath('DAEMON_SOCKET');
 }
+/** Mode of the session directories bdg creates: only the user can enter them */
+const PRIVATE_DIR_MODE = 0o700;
+/** Permission bits that give group or others any access */
+const GROUP_OTHER_ACCESS = 0o077;
 /**
  * Ensure the session directory exists.
  *
- * Creates ~/.bdg/ if it doesn't exist. Safe to call multiple times (idempotent).
- * A path that cannot hold a directory is refused before `mkdir`, which
- * would spin on a pseudo-filesystem ({@link makeDirectory}).
+ * Creates it, and missing parents (the base directory, `sessions/`), with
+ * mode 0700. Safe to call multiple times (idempotent). A path that cannot
+ * hold a directory is refused before `mkdir`, which would spin on a
+ * pseudo-filesystem ({@link makeDirectory}).
  *
  * @throws Error if the directory cannot be created
  */
 export function ensureSessionDir() {
-    makeDirectory(getSessionDir());
+    makeDirectory(getSessionDir(), PRIVATE_DIR_MODE);
+}
+/** Subdirectory of a session directory that a launched Chrome downloads into */
+const DOWNLOADS_DIR = 'downloads';
+/**
+ * The session's downloads directory (whether or not it exists).
+ *
+ * @returns Absolute path, `<session dir>/downloads`
+ */
+export function getSessionDownloadsDir() {
+    return path.join(getSessionDir(), DOWNLOADS_DIR);
+}
+/**
+ * Ensure the session's downloads directory exists (mode 0700, like the
+ * session directory) and return it.
+ *
+ * @returns Absolute path, `<session dir>/downloads`
+ * @throws Error if the directory cannot be created, or a file is in its place
+ */
+export function ensureSessionDownloadsDir() {
+    const dir = getSessionDownloadsDir();
+    makeDirectory(dir, PRIVATE_DIR_MODE);
+    if (!fs.statSync(dir).isDirectory()) {
+        throw Object.assign(new Error(`${dir} is a file`), { code: 'ENOTDIR' });
+    }
+    return dir;
+}
+/** Session directories need not keep group write out (umask 002 made them 0775) */
+const SESSION_DIR_TRUST = { allowGroupWrite: true };
+/**
+ * Directories whose trust a session directory depends on: the base
+ * directory and each directory from it down to the session directory
+ * (`<base>`, `<base>/sessions`, `<base>/sessions/<name>`), or the directory
+ * alone when it is outside the base.
+ *
+ * @param dir - Session directory
+ * @returns Directories, outermost first
+ */
+function sessionDirChain(dir) {
+    const base = getSessionBaseDir();
+    const relative = path.relative(base, dir);
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        return [{ dir, bdgOwned: false, isBase: false }];
+    }
+    const chain = [{ dir: base, bdgOwned: sessionDirOverride() === null, isBase: true }];
+    let current = base;
+    for (const part of relative.split(path.sep).filter(Boolean)) {
+        current = path.join(current, part);
+        chain.push({ dir: current, bdgOwned: true, isBase: false });
+    }
+    return chain;
+}
+/**
+ * Remove group and other access from a directory of the user's (best
+ * effort). The directory is opened without following a symlink and changed
+ * through that descriptor, so a path swapped after the trust check is not
+ * affected.
+ *
+ * @param dir - Trusted directory
+ */
+function tightenDir(dir) {
+    if (process.platform === 'win32')
+        return;
+    let fd;
+    try {
+        const { O_RDONLY, O_DIRECTORY, O_NOFOLLOW } = fs.constants;
+        fd = fs.openSync(dir, O_RDONLY | O_DIRECTORY | O_NOFOLLOW);
+        const stat = fs.fstatSync(fd);
+        if (stat.uid !== process.getuid?.() || (stat.mode & GROUP_OTHER_ACCESS) === 0)
+            return;
+        fs.fchmodSync(fd, PRIVATE_DIR_MODE);
+        log.debug(`Session directory ${dir} restricted to mode 700`);
+    }
+    catch (error) {
+        log.debug(`Session directory ${dir} not restricted: ${getErrorMessage(error)}`);
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+/**
+ * Why a directory of the chain cannot be trusted. The base directory alone
+ * may be a symlink (`~/.bdg` kept with dotfiles or on another disk): its
+ * target is checked instead. `sessions/` and session directories must be
+ * real directories.
+ *
+ * @param entry - Directory of the chain
+ * @returns The problem, or null when it can be trusted
+ * @throws Error from `lstat`/`realpath` (e.g. `ENOENT`)
+ */
+function chainDirProblem(entry) {
+    const problem = dirTrustProblem(entry.dir, SESSION_DIR_TRUST);
+    if (problem?.kind !== 'symlink' || !entry.isBase)
+        return problem;
+    const target = fs.realpathSync(entry.dir);
+    const targetProblem = dirTrustProblem(target, SESSION_DIR_TRUST);
+    return (targetProblem && {
+        ...targetProblem,
+        reason: `it links to ${target}, which is ${targetProblem.reason}`,
+    });
+}
+/**
+ * Accept a trusted directory: tighten it to 0700 when bdg owns it, leave a
+ * directory the user chose as it is (noted in the debug log when group or
+ * others can use it).
+ *
+ * @param entry - Trusted directory
+ */
+function acceptTrustedDir(entry) {
+    if (entry.bdgOwned) {
+        tightenDir(entry.dir);
+        return;
+    }
+    const mode = fs.statSync(entry.dir, { throwIfNoEntry: false })?.mode ?? 0;
+    if ((mode & GROUP_OTHER_ACCESS) === 0)
+        return;
+    log.debug(`Session directory ${entry.dir} is open to group or others; left as is (chosen with ${SESSION_DIR_OVERRIDE_ENV})`);
+}
+/**
+ * Check that a session directory and the directories above it up to the base
+ * directory can be trusted before a daemon is started there or its socket is
+ * connected to: another user who can write to one of them could replace the
+ * socket (and receive every command) or plant files. Each existing directory
+ * must be a real directory (not a symlink), owned by the user, and not
+ * writable by others ({@link dirTrustProblem}); group write is accepted, since
+ * under umask 002 (per-user groups) older versions created `~/.bdg` 0775.
+ * The base directory may be a symlink whose target passes the same rule
+ * ({@link chainDirProblem}). A directory owned by another uid (a bind mount,
+ * `sudo -E`) is refused.
+ *
+ * Trusted directories bdg owns (the default `~/.bdg`, `sessions/` and named
+ * session directories) that group or others can still use are tightened to
+ * 0700; a base directory chosen with `$BDG_SESSION_DIR`, or a symlinked base
+ * (opened without following links), is never changed.
+ * Missing paths are skipped (as is a path through a file, which fails on its
+ * own): {@link ensureSessionDir} creates them 0700.
+ *
+ * @param dir - Session directory (default: the selected session's)
+ * @returns The first untrusted directory and why, or null
+ */
+export function secureSessionDir(dir = getSessionDir()) {
+    for (const entry of sessionDirChain(dir)) {
+        let problem;
+        try {
+            problem = chainDirProblem(entry);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'ENOENT' || code === 'ENOTDIR')
+                continue;
+            problem = { reason: getErrorMessage(error), kind: 'not-directory' };
+        }
+        if (problem !== null)
+            return { dir: entry.dir, ...problem, bdgOwned: entry.bdgOwned };
+        acceptTrustedDir(entry);
+    }
+    return null;
 }
 //# sourceMappingURL=paths.js.map

package/dist/session/portClaims.d.ts

@@ -30,14 +30,6 @@ export declare function readPortFile(portPath: string): number | null;
  * @returns `$BDG_PORT_REGISTRY_DIR`, else `<os temp dir>/bdg-ports-<uid>`
  */
 export declare function getPortRegistryDir(): string;
-/**
- * Whether a path is a directory the current user can trust: a real directory
- * (not a symlink), owned by the user, not writable by group or others.
- *
- * @param dir - Directory
- * @returns Why it cannot be trusted, or null if it can
- */
-export declare function untrustedDirReason(dir: string): string | null;
 /**
  * Session directories other than the selected one that bdg knows of: those of
  * this base directory, and those of any base directory found in the

package/dist/session/portClaims.js

@@ -20,7 +20,7 @@ import * as path from 'path';
 import { getSessionBaseDir, getSessionDir, listSessionDirs, sessionFilePathIn, } from './paths.js';
 import { createLogger, logDebugError } from '../ui/logging/index.js';
 import { delay } from '../utils/async.js';
-import { makeDirectory } from '../utils/directories.js';
+import { makeDirectory, untrustedDirReason } from '../utils/directories.js';
 const log = createLogger('session');
 /** Lock file guarding port selection, in the port registry (or base session) directory */
 const PORT_LOCK_FILE = 'port.lock';
@@ -33,8 +33,6 @@ const LOCK_WAIT_MS = 5000;
 /** Lock age after which its holder is assumed dead */
 const STALE_LOCK_MS = 10000;
 const LOCK_POLL_MS = 25;
-/** Permission bits that let other users write */
-const GROUP_OTHER_WRITE = 0o022;
 /**
  * Read a port number from a `port.txt` file.
  *
@@ -64,25 +62,6 @@ export function getPortRegistryDir() {
     const uid = process.getuid?.();
     return path.join(os.tmpdir(), uid === undefined ? 'bdg-ports' : `bdg-ports-${uid}`);
 }
-/**
- * Whether a path is a directory the current user can trust: a real directory
- * (not a symlink), owned by the user, not writable by group or others.
- *
- * @param dir - Directory
- * @returns Why it cannot be trusted, or null if it can
- */
-export function untrustedDirReason(dir) {
-    const stat = fs.lstatSync(dir);
-    if (!stat.isDirectory())
-        return 'not a directory';
-    const uid = process.getuid?.();
-    if (uid !== undefined && stat.uid !== uid)
-        return `owned by uid ${stat.uid}`;
-    if (process.platform !== 'win32' && (stat.mode & GROUP_OTHER_WRITE) !== 0) {
-        return `writable by others (mode ${(stat.mode & 0o777).toString(8)})`;
-    }
-    return null;
-}
 /**
  * The port registry directory, created (mode 0700) if missing, if it can be
  * trusted (see {@link untrustedDirReason}).

package/dist/session/sessionList.d.ts

@@ -11,8 +11,10 @@ import { type SessionDirEntry } from './paths.js';
  * `unresponsive`), died and left its Chrome running (`crashed`) or only
  * files (`stale`), or exited after the session ended without `bdg stop`
  * (`ended`: Chrome crashed or was closed, the page was closed, `--timeout`).
+ * `untrusted`: something listens on its socket, but its directory is not
+ * safe to use, so it is not asked.
  */
-export type RunningSessionState = 'active' | 'starting' | 'ending' | 'unresponsive' | 'crashed' | 'stale' | 'ended';
+export type RunningSessionState = 'active' | 'starting' | 'ending' | 'unresponsive' | 'crashed' | 'stale' | 'ended' | 'untrusted';
 /**
  * One session in the list.
  */
@@ -33,6 +35,8 @@ export interface RunningSessionInfo {
     endReason?: UnexpectedEndReason;
     /** When an `ended` session ended (epoch ms) */
     endedAt?: number;
+    /** Why an `untrusted` session's directory is not safe to use */
+    untrusted?: string;
 }
 /**
  * Summarize a daemon's status response.

package/dist/session/sessionList.js

@@ -7,7 +7,7 @@ import { getStatus } from '../ipc/client.js';
 import { isSessionChrome, readLiveDaemonPid } from './cleanup/staleSession.js';
 import { probeDaemonSocket } from './daemonSocket.js';
 import { readLastSessionEnd } from './lastSession.js';
-import { SESSION_STATE_FILES, getNamedSessionDir, listSessionDirs, sessionFilePathIn, } from './paths.js';
+import { SESSION_STATE_FILES, getNamedSessionDir, listSessionDirs, secureSessionDir, sessionFilePathIn, } from './paths.js';
 import { readPidFromFile } from './pid.js';
 import { readPortFile } from './portClaims.js';
 import { isValidSessionName, normalizeSessionName } from './sessionName.js';
@@ -48,6 +48,10 @@ async function describeSession(entry) {
     const probe = await probeDaemonSocket(socketPath);
     if (probe !== 'alive')
         return describeWithoutSocket(entry, probe);
+    const untrusted = secureSessionDir(dir);
+    if (untrusted) {
+        return { name, state: 'untrusted', untrusted: `${untrusted.dir}: ${untrusted.reason}` };
+    }
     try {
         const response = await getStatus(socketPath);
         if (response.status === 'ok' && response.data)