@naswerks/periscope 1.0.0 → 1.0.1

package/src/host/transcript-fs.ts

@@ -0,0 +1,110 @@
+/**
+ * The local JSONL mirror: the store's effects, on a real disk.
+ *
+ * It lives here for the one reason everything else in this directory does: it names `node:fs`.
+ * The rules worth testing (which key becomes which record, what a missing transcript returns, what
+ * a corrupt line does) are in `persistence/store.ts` and are proven without a disk. This file is
+ * the part that cannot be, so it is small and it is the only place a path is built.
+ *
+ * The root is a jail, and the token is escaped before it gets here. A project key is
+ * caller-supplied and may contain anything, separators included; `transcriptToken` percent-encodes
+ * each segment so a key cannot introduce one. This checks containment anyway, because a jail that
+ * relies on its caller having escaped correctly is a jail with one lock on the outside.
+ */
+import { mkdir, readFile, readdir, rm, stat, appendFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+
+import type { StoreEffects } from '../persistence/store.js';
+import { isContainedBy, normalizePath, requireAbsolute } from '../core/paths.js';
+
+/** File-backed effects rooted at one directory. The root must be absolute. */
+export function nodeStoreEffects(root: string): StoreEffects {
+  const absolute = requireAbsolute(root);
+  if (!absolute.ok) {
+    throw new Error(`the transcript root must be absolute: ${absolute.refusal.detail}`);
+  }
+  const rootPath = normalizePath(absolute.value);
+
+  const pathFor = (token: string): string => {
+    const candidate = normalizePath(resolve(rootPath, `${token}.jsonl`));
+    if (!isContainedBy(candidate, rootPath)) {
+      // Unreachable through `transcriptToken`, which escapes every segment. Kept because the day it
+      // becomes reachable is the day somebody writes a second token function.
+      throw new Error(`refusing a transcript path outside the store root: ${token}`);
+    }
+    return candidate;
+  };
+
+  return {
+    async appendTo(token: string, text: string): Promise<void> {
+      const file = pathFor(token);
+      await mkdir(dirname(file), { recursive: true });
+      // A real append, not a read-modify-write: a transcript reaches megabytes and batches arrive
+      // throughout a turn, so rewriting per batch would cost the square of the session's length.
+      await appendFile(file, text, 'utf8');
+    },
+
+    async readAll(token: string): Promise<string | null> {
+      try {
+        return await readFile(pathFor(token), 'utf8');
+      } catch (error) {
+        // A transcript that was never written is `null`, and that is distinct from a read that
+        // failed — the store contract turns the first into "nothing was ever stored" and must not
+        // be handed it for a permission error.
+        if (isMissing(error)) return null;
+        throw error;
+      }
+    },
+
+    async list(projectKey: string) {
+      const scope = pathFor(encodeURIComponent(projectKey)).replace(/\.jsonl$/, '');
+      let names: string[];
+      try {
+        names = await readdir(scope);
+      } catch (error) {
+        if (isMissing(error)) return [];
+        throw error;
+      }
+
+      const found: { token: string; sessionId: string; mtime: number }[] = [];
+      for (const name of names) {
+        if (!name.endsWith('.jsonl')) continue;
+        const encodedId = name.slice(0, -'.jsonl'.length);
+        const stats = await stat(join(scope, name));
+        found.push({
+          token: `${encodeURIComponent(projectKey)}/${encodedId}`,
+          sessionId: decodeURIComponent(encodedId),
+          // Floored: the contract asks for integer epoch milliseconds and a fractional source here
+          // would not compare equal to a summary's own stamp.
+          mtime: Math.floor(stats.mtimeMs),
+        });
+      }
+      return found;
+    },
+
+    async remove(token: string): Promise<void> {
+      await rm(pathFor(token), { force: true });
+    },
+
+    async subkeys(projectKey: string, sessionId: string): Promise<readonly string[]> {
+      // A session's subagent transcripts live under a directory named for the session, beside its
+      // own file. Absent means it never spawned one, which is not an error.
+      const scope = pathFor(`${encodeURIComponent(projectKey)}/${encodeURIComponent(sessionId)}`).replace(
+        /\.jsonl$/,
+        '',
+      );
+      try {
+        return (await readdir(scope))
+          .filter((name) => name.endsWith('.jsonl'))
+          .map((name) => decodeURIComponent(name.slice(0, -'.jsonl'.length)));
+      } catch (error) {
+        if (isMissing(error)) return [];
+        throw error;
+      }
+    },
+  };
+}
+
+function isMissing(error: unknown): boolean {
+  return typeof error === 'object' && error !== null && (error as { code?: string }).code === 'ENOENT';
+}

package/src/host/wire-request.ts

@@ -0,0 +1,285 @@
+/**
+ * The one place a controller's `session_new.request` becomes a local `SessionRequest`.
+ *
+ * Why it is a file and not four lines in the dispatcher: everything crossing here arrived from
+ * off-box and was validated only as JSON. The codec's job is to keep malformed bytes out, and it
+ * says so; an empty `cwd`, an empty `text` and a non-ISO `at` all pass it. So a value that is
+ * well-formed JSON and meaningless to the SDK reaches this line, and there are exactly two things to
+ * do with one: refuse it by name before a process exists, or hand it to `query()` and let the
+ * failure arrive later wearing a spawn error's clothes. This file is the first of those.
+ *
+ * What it narrows and what it deliberately does not, because the split is a judgement worth
+ * stating rather than a gap. It narrows every value with a closed set this package can see (the
+ * three setting sources, the plugin type, the thinking discriminator) because an unrecognised value
+ * there silently does nothing, which is the failure mode with no symptom. It does not re-validate
+ * the MCP server configs: that union is large, versioned with the SDK, and re-stating it here would
+ * be a second copy that can disagree with the first. Those are shape-checked and handed on, and the
+ * SDK is their validator.
+ *
+ * Nothing here can produce `sessionStore`, `sessionStoreFlush`, `spawn`, `onStderr` or `hooks`.
+ * They have no JSON form, so the wire type has no member for them and this file has nothing to read.
+ * That is the boundary, and it is structural rather than a check somebody remembered to write.
+ */
+import type { JsonObject, SessionNewRequest } from '../control/frames.js';
+import type { Result } from '../core/result.js';
+import { ok, refuse } from '../core/result.js';
+import type { SessionRequest } from '../sessions/registry.js';
+import type { SpawnEnvPolicy } from '../sessions/spawn-env.js';
+import type {
+  McpServerConfig,
+  PermissionMode,
+  SdkPluginConfig,
+  SettingSource,
+  ThinkingConfig,
+} from './agent-process.js';
+import type { SessionConfigure } from '../control/frames.js';
+
+/** What a controller may ask for, minus the two the composer supplies itself. */
+export type ComposableRequest = Omit<SessionRequest, 'cwd' | 'hooks'>;
+
+/**
+ * The three tiers the SDK understands, as data.
+ *
+ * Restated here rather than derived because the SDK ships them as a bare string union with no
+ * runtime value to read — so this is the one place a copy is unavoidable. `wire-request.test.ts`
+ * asserts each member against the shipped `sdk.d.ts`, the same way the permission pin does, so the
+ * copy cannot quietly drift from what it copies.
+ */
+export const SETTING_SOURCES: readonly SettingSource[] = ['user', 'project', 'local'];
+
+/** The thinking shapes the SDK declares, by discriminator. Same argument as above. */
+export const THINKING_TYPES: readonly string[] = ['adaptive', 'enabled', 'disabled'];
+
+/** The SDK's effort levels, by name. An unknown level is refused, never dropped. */
+export const EFFORT_LEVELS: readonly string[] = ['low', 'medium', 'high', 'xhigh', 'max'];
+
+/** The SDK's permission modes, by name (protocol v6, CLI parity). */
+export const PERMISSION_MODES: readonly string[] = [
+  'default',
+  'acceptEdits',
+  'bypassPermissions',
+  'plan',
+  'dontAsk',
+  'auto',
+];
+
+/**
+ * The one mode under which a granting gate and loaded operator settings are NOT two authorities: the
+ * mode already allows everything the grant would, and a hook deny survives every mode. Named here, in
+ * the one module that holds the vocabulary, so nothing else has to spell the mode.
+ */
+export function isBypassMode(mode: string | null | undefined): boolean {
+  return mode === PERMISSION_MODES[2];
+}
+
+/** What a `session_configure` frame asked for, narrowed to the SDK's own types. */
+export interface SessionConfigureChange {
+  readonly model?: string | null;
+  readonly permissionMode?: PermissionMode;
+  readonly thinking?: ThinkingConfig;
+}
+
+/**
+ * Narrow a `session_configure` payload. Same discipline as `readSessionRequest`: a value the SDK does
+ * not declare is REFUSED by name — a mode nobody recognises must never become "the default" silently.
+ */
+export function readSessionConfigure(payload: SessionConfigure): Result<SessionConfigureChange> {
+  const change: { model?: string | null; permissionMode?: PermissionMode; thinking?: ThinkingConfig } = {};
+  if (payload.model !== null) change.model = payload.model;
+  if (payload.permissionMode !== null) {
+    if (!PERMISSION_MODES.includes(payload.permissionMode)) {
+      return refuse<SessionConfigureChange>(
+        'frame-malformed',
+        `permissionMode is ${JSON.stringify(payload.permissionMode)}; the modes this SDK declares are ` +
+          `${PERMISSION_MODES.join(', ')}`,
+      );
+    }
+    change.permissionMode = payload.permissionMode as PermissionMode;
+  }
+  if (payload.thinking !== null) {
+    const type = payload.thinking['type'];
+    if (typeof type !== 'string' || !THINKING_TYPES.includes(type)) {
+      return refuse<SessionConfigureChange>(
+        'frame-malformed',
+        `thinking.type is ${JSON.stringify(type)}; the shapes this SDK declares are ${THINKING_TYPES.join(', ')}`,
+      );
+    }
+    change.thinking = payload.thinking as unknown as ThinkingConfig;
+  }
+  return ok(change);
+}
+
+/**
+ * Turn a controller's request into a local one, or refuse it by name.
+ *
+ * `null` in means "every default", which is byte-for-byte the behaviour before this payload grew —
+ * so a controller that sends nothing new is unaffected by any of this.
+ */
+export function readSessionRequest(request: SessionNewRequest | null): Result<ComposableRequest> {
+  if (request === null) return ok({});
+
+  const composed: Record<string, unknown> = {};
+
+  if (request.resume !== null) composed['resume'] = request.resume;
+  if (request.fork !== null) composed['fork'] = request.fork;
+  if (request.includePartialMessages !== null) {
+    composed['includePartialMessages'] = request.includePartialMessages;
+  }
+  if (request.forwardSubagentText !== null) composed['forwardSubagentText'] = request.forwardSubagentText;
+  if (request.strictMcpConfig !== null) composed['strictMcpConfig'] = request.strictMcpConfig;
+  if (request.model !== null) composed['model'] = request.model;
+  // Handed on as the SDK's own option type. A string, a list of strings and a preset object are all
+  // legal, so there is no closed set to check and inventing one would refuse valid requests.
+  if (request.systemPrompt !== null) composed['systemPrompt'] = request.systemPrompt;
+
+  if (request.settingSources !== null) {
+    // A tier nobody declared is refused, not dropped. Dropping it would start a session the
+    // controller believes loads its project settings, silently without them — and the permission
+    // rules it expected to be in force would simply not be. Nothing would say so.
+    const unknown = request.settingSources.filter(
+      (source) => !(SETTING_SOURCES as readonly string[]).includes(source),
+    );
+    if (unknown.length > 0) {
+      return refuse<ComposableRequest>(
+        'frame-malformed',
+        `settingSources names ${unknown.map((source) => `"${source}"`).join(', ')}, which this host ` +
+          `does not know — the tiers are ${SETTING_SOURCES.join(', ')}. Refused rather than ignored: a ` +
+          `session started without a tier its controller asked for runs with permission rules nobody ` +
+          `told it were absent`,
+      );
+    }
+    composed['settingSources'] = [...request.settingSources] as SettingSource[];
+  }
+
+  if (request.plugins !== null) {
+    const plugins: SdkPluginConfig[] = [];
+    for (const plugin of request.plugins) {
+      // Same argument as the tiers: the SDK supports exactly one plugin type today, and a value it
+      // does not recognise loads nothing while looking like it asked for something.
+      if (plugin.type !== 'local') {
+        return refuse<ComposableRequest>(
+          'frame-malformed',
+          `a plugin declares type "${plugin.type}"; this host passes only "local" plugins to the agent`,
+        );
+      }
+      plugins.push({
+        type: 'local',
+        path: plugin.path,
+        ...(plugin.skipMcpDiscovery === null ? {} : { skipMcpDiscovery: plugin.skipMcpDiscovery }),
+      });
+    }
+    composed['plugins'] = plugins;
+  }
+
+  if (request.thinking !== null) {
+    const type = request.thinking['type'];
+    if (typeof type !== 'string' || !THINKING_TYPES.includes(type)) {
+      return refuse<ComposableRequest>(
+        'frame-malformed',
+        `thinking.type is ${JSON.stringify(type)}; the shapes this SDK declares are ` +
+          `${THINKING_TYPES.join(', ')}`,
+      );
+    }
+    composed['thinking'] = request.thinking;
+  }
+
+  if (request.effort !== null) {
+    if (!EFFORT_LEVELS.includes(request.effort)) {
+      return refuse<ComposableRequest>(
+        'frame-malformed',
+        `effort is ${JSON.stringify(request.effort)}; the levels this SDK declares are ${EFFORT_LEVELS.join(', ')}`,
+      );
+    }
+    composed['effort'] = request.effort;
+  }
+
+  if (request.permissionMode !== null) {
+    // The lane that was closed, opened by name (protocol v6). Narrowed like every other member: an
+    // unknown mode is refused, never dropped and never defaulted.
+    if (!PERMISSION_MODES.includes(request.permissionMode)) {
+      return refuse<ComposableRequest>(
+        'frame-malformed',
+        `permissionMode is ${JSON.stringify(request.permissionMode)}; the modes this SDK declares are ` +
+          `${PERMISSION_MODES.join(', ')}`,
+      );
+    }
+    composed['permissionMode'] = request.permissionMode;
+  }
+
+  if (request.env !== null) {
+    const policy: SpawnEnvPolicy = {
+      ...(request.env.extraAllowedKeys === null
+        ? {}
+        : { extraAllowedKeys: [...request.env.extraAllowedKeys] }),
+      ...(request.env.extraDeniedKeys === null ? {} : { extraDeniedKeys: [...request.env.extraDeniedKeys] }),
+      ...(request.env.extraEnv === null ? {} : { extraEnv: { ...request.env.extraEnv } }),
+    };
+    composed['env'] = policy;
+  }
+
+  if (request.mcpServers !== null) {
+    const servers = readMcpServers(request.mcpServers);
+    if (!servers.ok) return refuse<ComposableRequest>(servers.refusal.reason, servers.refusal.detail);
+    composed['mcpServers'] = servers.value;
+  }
+
+  return ok(composed as ComposableRequest);
+}
+
+/**
+ * Shape-check the server map. Each value must be an object; beyond that the SDK is the validator.
+ *
+ * See this file's header for why the config union is not re-stated here.
+ */
+function readMcpServers(servers: JsonObject): Result<Record<string, McpServerConfig>> {
+  const read: Record<string, McpServerConfig> = {};
+  for (const [name, config] of Object.entries(servers)) {
+    if (name === '') {
+      return refuse<Record<string, McpServerConfig>>(
+        'mcp-descriptor-invalid',
+        'an MCP server was declared under an empty name; a tool reaches the model as ' +
+          '`mcp__{server}__{tool}` and an unnamed server has no reachable tools',
+      );
+    }
+    if (typeof config !== 'object' || config === null || Array.isArray(config)) {
+      return refuse<Record<string, McpServerConfig>>(
+        'mcp-descriptor-invalid',
+        `MCP server "${name}" is declared as ${config === null ? 'null' : typeof config}, not an object`,
+      );
+    }
+    read[name] = config as unknown as McpServerConfig;
+  }
+  return ok(read);
+}
+
+/**
+ * Merge the controller's servers with the ones this host registers itself.
+ *
+ * A colliding name is refused rather than resolved, and either precedence would have been wrong.
+ * Letting the controller win lets a remote peer replace the host's OWN tool server — the one that
+ * carries the host's identity into every call — with something it supplies. Letting the host win
+ * silently discards a registration the controller believes it made, and its tools then simply do not
+ * exist, with nothing anywhere saying why. So the pair is refused, before any process exists, naming
+ * the server both sides claimed.
+ */
+export function mergeMcpServers(
+  fromController: Readonly<Record<string, McpServerConfig>> | undefined,
+  fromHost: Readonly<Record<string, McpServerConfig>> | null,
+): Result<Readonly<Record<string, McpServerConfig>> | null> {
+  if (fromHost === null) return ok(fromController ?? null);
+  if (fromController === undefined) return ok(fromHost);
+
+  const collisions = Object.keys(fromHost).filter((name) =>
+    Object.prototype.hasOwnProperty.call(fromController, name),
+  );
+  if (collisions.length > 0) {
+    return refuse<Readonly<Record<string, McpServerConfig>> | null>(
+      'mcp-descriptor-invalid',
+      `MCP server ${collisions.map((name) => `"${name}"`).join(', ')} is declared by both this host ` +
+        `and the controller. Refused rather than resolved: letting the controller win replaces this ` +
+        `host's own tool server, and letting the host win discards a registration the controller ` +
+        `believes it made. Rename one`,
+    );
+  }
+  return ok({ ...fromHost, ...fromController });
+}

package/src/host/workspace-fs.ts

@@ -0,0 +1,90 @@
+/**
+ * The real effects the workspace providers run on: the filesystem, and `git`.
+ *
+ * Why they live here and the providers do not: `src/host/` is the only directory allowed to touch
+ * the machine, pinned by pins/host-boundary.test.ts, and a provider is mostly DECISIONS: which argv
+ * a git call gets, whether a directory is reused or made, what a release does. Splitting them puts
+ * the decisions where they can be tested with no disk and no repository — which is what turns "never
+ * hard-reset an existing branch" into a unit test instead of a rule only a lost branch could prove.
+ *
+ * `execFile`, never `exec`. `exec` runs its argument through a shell, so every branch name and
+ * path in it becomes an injection site — and branch names arrive from a caller this package does not
+ * control. `execFile` takes an argv array and spawns the program directly, with no shell to quote
+ * for and nothing to escape.
+ */
+import { execFile } from 'node:child_process';
+import { mkdir, readdir, rm, stat } from 'node:fs/promises';
+
+import type { CommandEffects, WorkspaceEffects } from '../workspace/provider.js';
+
+/** The filesystem half, on `node:fs/promises`. */
+export const nodeWorkspaceEffects: WorkspaceEffects = {
+  async makeDirectory(path: string): Promise<void> {
+    await mkdir(path, { recursive: true });
+  },
+  async exists(path: string): Promise<boolean> {
+    try {
+      await stat(path);
+      return true;
+    } catch {
+      // Any failure to stat is treated as absent. The caller's next act either creates it — which
+      // reports its own error — or attaches to it, so a stat that failed for a different reason
+      // surfaces as a named provisioning refusal rather than being swallowed here.
+      return false;
+    }
+  },
+  async removeDirectory(path: string): Promise<void> {
+    await rm(path, { recursive: true, force: true });
+  },
+  async listDirectories(path: string): Promise<string[]> {
+    try {
+      const entries = await readdir(path, { withFileTypes: true });
+      return entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort();
+    } catch (error) {
+      // A root that does not exist yet has no workspaces in it; anything else is the caller's refusal.
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+      throw error;
+    }
+  },
+};
+
+/**
+ * 60 seconds. Long enough for a cold worktree creation on a loaded machine; short enough that a git
+ * call which will never return does not hold a session's provisioning open indefinitely.
+ */
+const DEFAULT_COMMAND_TIMEOUT_MS = 60_000;
+
+/**
+ * Running a program with an argv array.
+ *
+ * It rejects on a non-zero exit, and that is load-bearing rather than conventional. The worktree
+ * provider probes for a branch by running `rev-parse --verify` and reading the FAILURE as "this
+ * branch does not exist" — so an implementation that resolved with an empty string on a non-zero
+ * exit would report every branch as existing, and the provider would attach where it should create.
+ * The safe direction, but silently wrong, and it would look like it worked.
+ */
+export function nodeCommandEffects(timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS): CommandEffects {
+  return {
+    run(program: string, args: readonly string[], cwd: string): Promise<string> {
+      return new Promise<string>((resolve, reject) => {
+        execFile(
+          program,
+          [...args],
+          { cwd, timeout: timeoutMs, windowsHide: true },
+          (error, stdout, stderr) => {
+            if (error !== null) {
+              // stderr carries git's own message, which is the only text that says WHY. Dropping it
+              // leaves a refusal reading "command failed" with nothing to act on.
+              reject(new Error(`${program} ${args.join(' ')} failed: ${stderr.trim() || error.message}`));
+              return;
+            }
+            resolve(stdout.trim());
+          },
+        );
+      });
+    },
+  };
+}

package/src/host/workspace-trust.ts

@@ -0,0 +1,92 @@
+/**
+ * Whether a working directory is one the agent CLI considers trusted. Read, never written.
+ *
+ * The trap this exists for: in an untrusted workspace the CLI silently voids the permission rules
+ * in `.claude/settings.json` — *"Ignoring 1 permissions.allow entry … this workspace has not been
+ * trusted"* — and that sentence is a STDERR LINE, not an error. Nothing in the SDK's type surface
+ * models trust at all. A host that provisions working directories programmatically will therefore
+ * create untrusted ones by default and never be told.
+ *
+ * Why this module reads and does not write: granting trust
+ * means writing `hasTrustDialogAccepted: true` into the user's own `~/.claude.json`, a file every
+ * running CLI rewrites, so a host that grants is racing them for user-global state it does not own.
+ * It would also remove the SYMPTOM rather than the SILENCE, and silence is the actual failure: a
+ * host that reports the condition works on a machine where granting is impossible — a read-only
+ * home, a container, another user's account — and one that grants does not.
+ *
+ * What replaces it: this package depends on no settings file (`settingSources: []` reads none, so
+ * there are no rules for an untrusted workspace to void), and where a caller opts back in, the
+ * condition is REPORTED. The permission authority is the in-process hook, which the evidence shows
+ * fires regardless of allow rules — depending on the rules instead would mean depending on the one
+ * mechanism proven to be silently voidable.
+ */
+import { readFileSync } from 'node:fs';
+
+import { normalizePath } from '../core/paths.js';
+
+export type WorkspaceTrust =
+  /** The config records this directory as trusted. */
+  | 'trusted'
+  /** The config was read and this directory is either absent from it or recorded as untrusted. */
+  | 'untrusted'
+  /** No config, or one that could not be read. NOT the same as untrusted — see below. */
+  | 'unknown';
+
+/**
+ * The stderr line the CLI emits when it drops rules for this reason, as a matcher.
+ *
+ * Deliberately loose: it matches the stable part of a message whose wording the CLI owns, so a
+ * reworded prefix or a different rule count still trips it. A matcher that is too precise here fails
+ * open, which is the direction that reproduces the original silence.
+ */
+const UNTRUSTED_STDERR = /has not been trusted/i;
+
+export function isUntrustedWorkspaceWarning(line: string): boolean {
+  return UNTRUSTED_STDERR.test(line);
+}
+
+/** Where the CLI keeps per-directory trust. Separate from the settings files. */
+export function trustConfigPath(homeDir: string): string {
+  return `${normalizePath(homeDir)}/.claude.json`;
+}
+
+/**
+ * Read the recorded trust for `cwd`.
+ *
+ * Comparison is normalized and case-insensitive because the recorded keys are whatever absolute
+ * path the CLI was started with — `C:\x` and `c:/x` are the same directory on Windows and would
+ * otherwise read as two.
+ *
+ * `unknown` is a third answer and not a synonym for untrusted. A config that cannot be read
+ * supports no claim, and reporting "untrusted" for it would state a fact about the user's machine
+ * that was never observed.
+ */
+export function readWorkspaceTrust(configPath: string, cwd: string): WorkspaceTrust {
+  let raw: string;
+  try {
+    raw = readFileSync(configPath, 'utf8');
+  } catch {
+    return 'unknown';
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return 'unknown';
+  }
+
+  const projects = (parsed as { projects?: unknown }).projects;
+  if (typeof projects !== 'object' || projects === null) return 'unknown';
+
+  const wanted = normalizePath(cwd).toLowerCase();
+  for (const [recordedPath, entry] of Object.entries(projects as Record<string, unknown>)) {
+    if (normalizePath(recordedPath).toLowerCase() !== wanted) continue;
+    const accepted = (entry as { hasTrustDialogAccepted?: unknown }).hasTrustDialogAccepted;
+    return accepted === true ? 'trusted' : 'untrusted';
+  }
+
+  // The file exists and lists projects; this one is simply not among them. That IS an observation:
+  // a directory the CLI has never been trusted in.
+  return 'untrusted';
+}