pum-agent 0.2.0-beta.4 → 0.2.2-beta.1

package/README.md

@@ -23,7 +23,7 @@ pum
 PUM opens the login panel automatically on the first start.
 
 > [!WARNING]
-> PUM can read, write, and delete files. PUM can also run commands and supervised trigger processes. Check mode can verify or ask about these operations, but it is not a sandbox. Start PUM only inside a workspace where these actions are acceptable.
+> PUM can read, write, and delete files. Check mode adds deterministic policy checks and can enforce native Bash isolation on supported Linux and Windows hosts. Other tools, extensions, and external triggers still run in the PUM process boundary described below. Review the safeguards and prerequisites before using untrusted workspaces.
 
 ## See PUM in action
 
@@ -46,7 +46,7 @@ The following screens are real OpenTUI renders captured through `tmux`. A local
 - **Prompt control:** Steer active work, answer model questionnaires, use an ownership-aware message cache, attach clipboard images, and resume sessions with metadata-rich history.
 - **External triggers:** Supervise background commands such as `gh run watch` and automatically wake the exact target agent when they exit.
 - **Provider choice:** Search the providers exposed by pi, or add an OpenAI-compatible custom endpoint.
-- **Optional safeguards:** Use strict, balanced, or ask Check mode for `bash`, `edit`, `apply_patch`, and external-trigger process proposals.
+- **Optional safeguards:** Use strict, balanced, or ask Check mode, plus native Bash sandboxing through Bubblewrap or Windows CreateProcessInSandbox when available.
 - **Terminal-first appearance:** Nine themes, semantic color overrides, Unicode glyphs, and optional animation.
 
 PUM uses [pi](https://github.com/earendil-works/pi) for the agent loop and [OpenTUI](https://github.com/anomalyco/opentui) for rendering.
@@ -60,7 +60,22 @@ PUM uses [pi](https://github.com/earendil-works/pi) for the agent loop and [Open
 
 Linux and macOS are the primary environments. Windows CI checks the code and Windows path behavior. Native Windows TUI operation remains provisional because it has not been fully validated in a Windows terminal.
 
-On Windows, install Git for Windows. Ensure that `bash.exe` is in `PATH` or remains in its standard location. Use Windows Terminal with PowerShell. Do not use PowerShell ISE.
+On Linux, native Bash sandboxing requires Bubblewrap (`bwrap`) and working unprivileged user namespaces. PUM probes a minimal sandbox launch; finding the executable alone is not sufficient. On Arch Linux, install the prerequisite separately with `sudo pacman -S --needed bubblewrap`.
+
+On Windows, install Git for Windows. Ensure that `bash.exe` is in `PATH` or remains in its standard location. Use Windows Terminal with PowerShell. Do not use PowerShell ISE. Native Bash sandboxing uses the optional alpha `@microsoft/mxc-sdk` package and requires its `base-container` CreateProcessInSandbox tier. PUM deliberately rejects the SDK's AppContainer+DACL fallback because it can modify host ACLs.
+
+### Terminal title
+
+PUM sets a compact terminal title such as `Pum · working · 2 subagents`. The title reports overall activity and counts only starting or running subagents. PUM clears the title during graceful shutdown.
+
+Windows Terminal and common Linux terminal emulators accept the title through OpenTUI. Inside `tmux`, PUM sets the active pane title. To copy that pane title to the outer terminal title, add this configuration:
+
+```tmux
+set -g set-titles on
+set -g set-titles-string '#T'
+```
+
+Keep `allow-set-title` enabled so applications can update the pane title. A `tmux` configuration can replace or suppress application titles. PUM cannot override that server policy.
 
 ## Install and start
 
@@ -129,7 +144,7 @@ Set `PUM_DIR` to override PUM's complete configuration and data directory. Run `
 | `Ctrl+C` | Clear the selected non-empty draft; on an empty draft, press twice to quit |
 | `?` | Show all controls when the prompt is empty |
 
-Useful commands include `/login`, `/history`, `/triggers`, `/clear`, `/compress`, and `/worktree`.
+Useful commands include `/login`, `/history`, `/triggers`, `/check-path`, `/clear`, `/compress`, and `/worktree`.
 
 ### Copy transcript text
 
@@ -205,16 +220,36 @@ Trigger events target one exact main or retained child session. A missing sessio
 Select a Check mode profile in `Ctrl+P`. It applies to `bash`, `edit`, `apply_patch`, and external-trigger process execution:
 
 - **Strict:** Run deterministic hard rules, then require a clear verifier approval.
-- **Balanced:** Block deterministic hard-rule or suspicious findings. Allow ordinary complete project-local calls. Verifier review is non-blocking unless the verifier returns explicit `UNSAFE`.
+- **Balanced:** Block deterministic hard-rule or suspicious findings. Allow ordinary complete project-local calls and explicit non-sensitive external reads. Verifier review is non-blocking unless the verifier returns explicit `UNSAFE`.
 - **Ask:** Show the approval popup for every checked call that passes hard rules, unless an exact session or project approval already matches. A verifier `SAFE`, unclear, error, or unavailable result still requires approval.
 
-Every active profile hard-blocks project escape, escaping links, credential access, privilege escalation, persistence, remote-script execution, destructive Git operations, and broad deletion. These hard blocks cannot be overridden and do not open the popup. An explicit verifier `UNSAFE` verdict also blocks without a popup. The only exception is a deterministic match for direct main-agent `npm publish` or `npm dist-tag add`. The verifier category does not control this exception. The exception still requires explicit popup approval. Managed subagents cannot use the exception.
+Every active profile hard-blocks external writes, location changes, execution operands, ambiguous path access, escaping links, credential access, privilege escalation, persistence, remote-script execution, destructive Git operations, and broad deletion. Balanced permits only explicit, deterministically classified, non-sensitive external reads. These hard blocks cannot be overridden and do not open the popup. An explicit verifier `UNSAFE` verdict also blocks without a popup. The only exception is a deterministic match for direct main-agent `npm publish` or `npm dist-tag add`. The verifier category does not control this exception. The exception still requires explicit popup approval. Managed subagents cannot use the exception.
+
+Use `/check-path list`, `/check-path add <directory>`, `/check-path remove <directory>`, or `/check-path clear` to manage up to 16 additional directory roots for the current launch project. Bash, edit, and external-trigger checks can use these roots; `apply_patch` remains project-local. Added roots are canonicalized and remain subject to credential, traversal, symlink or junction, broad-deletion, and other hard blocks.
 
 For `edit` and `apply_patch`, PUM validates the complete proposed change before any mutation. Review data includes the unified diff, changed paths, line counts, sensitivity flags, project containment, and full-content SHA-256. Invalid, stale, malformed, escaping, or incompletely analyzed input blocks the call. Patch length alone does not block a valid Balanced call.
 
 Ask mode can allow an exact call once, for the current session, or for the current project. Approvals match the authoritative main or child identity, tool, verifier model, project, and canonical complete input. Chat text is not approval. Use **Clear approvals** in Settings to remove project approvals.
 
-The verifier uses a structured decision schema. One unclear response can receive one adjudication under the shared 15-second watchdog. Strict blocks malformed replies, errors, aborts, and timeouts. Balanced allows a fully validated call after an unclear, unavailable, failed, or timed-out review. Balanced still blocks explicit verifier `UNSAFE`, aborts, deterministic suspicious findings, malformed structures, and incomplete analysis. Ask requires the popup after hard rules for verifier `SAFE`, unclear, error, and unavailable results. Check mode is off by default and is not a sandbox.
+The verifier uses a structured decision schema. One unclear response can receive one adjudication under the shared 15-second watchdog. Strict blocks malformed replies, errors, aborts, and timeouts. Balanced allows a fully validated call after an unclear, unavailable, failed, or timed-out review. Balanced still blocks explicit verifier `UNSAFE`, aborts, deterministic suspicious findings, malformed structures, and incomplete analysis. Ask requires the popup after hard rules for verifier `SAFE`, unclear, error, and unavailable results. Check mode is off by default.
+
+#### Native Bash sandbox
+
+The **Sandbox** setting has three modes:
+
+- **Auto:** Enforce the platform sandbox for Bash when available. If probing fails, retain deterministic Check mode and show one process-local warning that is not written to session context.
+- **Require:** Block checked Bash calls unless native enforcement is available.
+- **Off:** Do not sandbox Bash. Check mode policy and approval behavior remain unchanged.
+
+Check mode **Off** always uses pi's normal unsandboxed Bash backend. For an active Check mode, PUM recomputes the sandbox policy from the exact approved command, authoritative working directory, configured additional roots, and deterministic access analysis. Model input cannot supply policy fields.
+
+The project and configured additional roots are writable. Explicit Balanced external reads are mounted read-only. PUM configuration and common credential paths are denied, and credential-shaped or process-injection environment variables are removed. A private temporary directory is supplied for the command. Safe pi metadata such as `PI_PROVIDER`, `PI_MODEL`, and `PI_REASONING_LEVEL` remains available; session paths and identifiers are withheld.
+
+Network access is denied unless deterministic analysis recognizes an approved network operation. Bubblewrap's host-network mode is all-or-nothing and is **not domain-filtered**. Windows similarly grants or withholds the SDK's broad network capabilities; it does not provide hostname allowlists.
+
+The override uses pi's `createBashTool` implementation and custom Bash operations, preserving streaming, truncation, full-output files, rendering, timeout messages, abort handling, shell configuration, and child-tree cleanup. Only Bash commands are routed through this backend. PUM does not sandbox the TUI/model process itself.
+
+External triggers preserve direct executable/argument boundaries and continue to use deterministic Check mode, but they are not routed through the native sandbox in this release. The trigger manager's synchronous spawn boundary does not carry the exact approved policy object into execution; silently recomputing a second process policy there would weaken approval identity. Trigger output, environment, limits, and process supervision remain unchanged.
 
 Verifier prompts stay bounded. For an oversized Balanced review, PUM sends complete validation metadata, counts, findings, and SHA-256 digests. PUM does not send a raw prefix or suffix as if it were complete. Strict and Ask keep their fail-closed oversized-input behavior.
 
@@ -252,7 +287,7 @@ Set `PUM_DIR` to override the complete PUM data directory.
 | `auth.json` | Provider credentials and custom-provider keys |
 | `models.json` | Custom endpoints and model metadata; submitted keys are not stored here |
 | `settings.json` | Model and thinking level managed by pi |
-| `pum.json` | Theme, animation, search, writing, explanation, and check settings |
+| `pum.json` | Theme, animation, search, writing, explanation, Check mode, sandbox, and subagent settings |
 | `theme.json` | Optional semantic color overrides |
 | `history.json` | Prompt history by working directory |
 | `prompt-stash.json` | Stashed prompts by working directory |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pum-agent",
-  "version": "0.2.0-beta.4",
+  "version": "0.2.2-beta.1",
   "description": "A compact terminal coding agent powered by pi and OpenTUI.",
   "license": "MIT",
   "type": "module",
@@ -60,7 +60,8 @@
     "ws": "^8.21.3"
   },
   "optionalDependencies": {
-    "@mariozechner/clipboard": "0.3.9"
+    "@mariozechner/clipboard": "0.3.9",
+    "@microsoft/mxc-sdk": "^0.7.0"
   },
   "devDependencies": {
     "@types/bun": "^1.3.14",

package/src/app.tsx

@@ -22,6 +22,7 @@ import {
   checkPathsForProject,
   MAX_ACTIVE_SUBAGENTS,
   MIN_ACTIVE_SUBAGENTS,
+  SANDBOX_MODES,
   saveSettings,
   WORKING_RULE_ANIMATION_MODES,
   type PumSettings,
@@ -81,7 +82,7 @@ import {
   removePendingImage,
   type PendingImage,
 } from "./image-paste";
-import type { SubagentManager } from "./subagents/manager";
+import { countActiveSubagents, type SubagentManager } from "./subagents/manager";
 import type { SpawnPreviewManager } from "./subagents/spawn-preview";
 import { SpawnPreviewPopup } from "./subagents/spawn-preview-popup";
 import { recallNewestQueuedUserMessage } from "./queue-recall";
@@ -119,6 +120,7 @@ import {
   type TriggerAction,
   type TriggerManagerLike,
 } from "./triggers/popup";
+import type { TerminalTitleController } from "./terminal-title";
 
 type Stream = { kind: "assistant" | "thinking"; text: string } | null;
 type Transcript = { lines: Line[]; stream: Stream; pending: PendingLine[] };
@@ -344,6 +346,10 @@ export function App({
   checkApprovalStore,
   triggerManager,
   messageCacheController,
+  terminalTitle,
+  startupWarnings = [],
+  onSandboxModeChange,
+  sandboxWarningSource,
 }: {
   session: AgentSession;
   modelRuntime: ModelRuntime;
@@ -365,16 +371,24 @@ export function App({
   checkApprovalStore?: CheckApprovalStore;
   triggerManager?: TriggerManagerLike;
   messageCacheController?: MessageCacheController;
+  terminalTitle?: TerminalTitleController;
+  /** Visible process-local warnings. These lines never enter pi session context. */
+  startupWarnings?: readonly string[];
+  onSandboxModeChange?: (mode: NonNullable<PumSettings["sandboxMode"]>) => void;
+  sandboxWarningSource?: { subscribeWarnings(listener: (warning: string) => void): () => void };
 }) {
   const cwd = process.cwd();
   const [session, setSession] = useState(initialSession);
   const [tx, setTx] = useState<Transcript>(() => ({
     // A resumed session already holds messages; show them instead of a blank pane.
-    lines: replayEntries(
-      initialSession.sessionManager.buildContextEntries(),
-      cwd,
-      initial.showThinking,
-    ),
+    lines: [
+      ...replayEntries(
+        initialSession.sessionManager.buildContextEntries(),
+        cwd,
+        initial.showThinking,
+      ),
+      ...startupWarnings.map((text): Line => ({ kind: "text", role: "system", text })),
+    ],
     stream: null,
     pending: [],
   }));
@@ -436,6 +450,7 @@ export function App({
   const syntaxStyle = useMemo(() => buildSyntaxStyle(theme), [theme]);
   const animations = settings.animations && supportsTrueColor();
   const agents = subagentManager.getAgents();
+  const activeSubagentCount = countActiveSubagents(agents);
   const activeAgent = activeAgentId
     ? agents.find((agent) => agent.id === activeAgentId)
     : undefined;
@@ -553,6 +568,7 @@ export function App({
   };
   // The event subscription is set up once, so it reads the toggle via a ref.
   const showThinkingRef = useRef(initial.showThinking);
+  const startupWarningsRef = useRef([...startupWarnings]);
   const sessionRef = useRef(session);
   sessionRef.current = session;
   const loginControllerRef = useRef<LoginController | null>(null);
@@ -794,6 +810,10 @@ export function App({
       return pending ? resolvePendingDelivery(value, pending.id) : value;
     });
 
+  useEffect(() => sandboxWarningSource?.subscribeWarnings((warning) => {
+    append({ kind: "text", role: "system", text: warning });
+  }), [sandboxWarningSource]);
+
   useEffect(() => checkApprovalCoordinator?.subscribe((request) => {
     setCheckApproval(request);
     setCheckApprovalDecision("allowOnce");
@@ -818,6 +838,13 @@ export function App({
     [subagentManager],
   );
 
+  useEffect(() => {
+    terminalTitle?.update({
+      working: busy || activeSubagentCount > 0,
+      activeSubagentCount,
+    });
+  }, [terminalTitle, busy, activeSubagentCount]);
+
   useEffect(() => spawnPreviewManager?.subscribe(() => {
     setSpawnPreviewRevision((revision) => revision + 1);
   }), [spawnPreviewManager]);
@@ -865,8 +892,13 @@ export function App({
       .catch((error) => append({ kind: "text", role: "error", text: String(error) }));
     setThinkingLevel(session.agent.state.thinkingLevel as ThinkingLevel);
     setModelId(session.agent.state.model.id);
+    const visibleStartupWarnings = startupWarningsRef.current;
+    startupWarningsRef.current = [];
     setTx({
-      lines: replayEntries(session.sessionManager.buildContextEntries(), cwd, showThinkingRef.current),
+      lines: [
+        ...replayEntries(session.sessionManager.buildContextEntries(), cwd, showThinkingRef.current),
+        ...visibleStartupWarnings.map((text): Line => ({ kind: "text", role: "system", text })),
+      ],
       stream: null,
       pending: [],
     });
@@ -1029,6 +1061,7 @@ export function App({
     if (patch.explanationStrength !== undefined) {
       setExplanationStrength(patch.explanationStrength);
     }
+    if (patch.sandboxMode !== undefined) onSandboxModeChange?.(patch.sandboxMode);
     if (patch.checkMode !== undefined || patch.checkModel !== undefined || patch.checkPaths !== undefined) {
       setCheckModeConfig({
         profile: next.checkMode,
@@ -1519,6 +1552,12 @@ export function App({
     update({ checkMode: CHECK_MODE_PROFILES[(index + step + CHECK_MODE_PROFILES.length) % CHECK_MODE_PROFILES.length]! });
   };
 
+  const stepSandboxMode = (step: number) => {
+    const current = settings.sandboxMode ?? "auto";
+    const index = SANDBOX_MODES.indexOf(current);
+    update({ sandboxMode: SANDBOX_MODES[(index + step + SANDBOX_MODES.length) % SANDBOX_MODES.length]! });
+  };
+
   const rowActions: Record<SettingRowId, { step?: (n: number) => void; enter?: () => void }> = {
     theme: { step: stepTheme },
     providers: { enter: openLogin },
@@ -1528,6 +1567,7 @@ export function App({
     writingStyle: { step: stepWritingStyle },
     explanationStrength: { step: stepExplanationStrength },
     checkMode: { step: stepCheckMode },
+    sandboxMode: { step: stepSandboxMode },
     checkModel: { enter: () => {
       setModelQuery("");
       setModelSearchFocused(false);
@@ -1575,6 +1615,7 @@ export function App({
     writingStyle: `‹ ${settings.writingStyle} ›`,
     explanationStrength: `‹ ${settings.explanationStrength} ›`,
     checkMode: `‹ ${settings.checkMode} ›`,
+    sandboxMode: `‹ ${settings.sandboxMode ?? "auto"} ›`,
     checkModel: `${settings.checkModel} ›`,
     checkPaths: `${checkPathsForProject(settings, cwd).length} additional · /check-path ›`,
     clearCheckApprovals: "clear ›",
@@ -2236,7 +2277,7 @@ export function App({
           busy={visibleBusy}
           elapsedSec={visibleElapsedSec}
           agentCount={agents.length}
-          runningAgentCount={agents.filter((agent) => agent.status === "running" || agent.status === "starting").length}
+          runningAgentCount={activeSubagentCount}
           maxActiveAgentCount={settings.maxActiveSubagents}
           activeAgentName={activeAgent?.name}
         />

package/src/check-mode.ts

@@ -262,12 +262,13 @@ export async function prepareCheck(
         cwd: input.cwd,
         projectCwd: cwd,
         allowedPaths: additionalPaths,
+        protectedPaths: [AGENT_DIR],
         profile,
       });
     } else {
       const command = input && typeof input === "object" ? (input as { command?: unknown }).command : undefined;
       if (typeof command !== "string") return { block: "Bash safety check requires a complete command string or process proposal" };
-      policy = analyzeCheckPolicy({ command, cwd, profile, allowedPaths: additionalPaths });
+      policy = analyzeCheckPolicy({ command, cwd, profile, allowedPaths: additionalPaths, protectedPaths: [AGENT_DIR] });
     }
     bash = policy.analysis;
     if (!bash.complete || bash.truncated || !bash.syntaxBalanced) {
@@ -316,6 +317,7 @@ export async function prepareCheck(
       decision: policy.decision,
       reason: policy.reason,
       findings: policy.findings,
+      accesses: policy.accesses,
     } : undefined,
     shell: processProposal ? undefined : bash,
     process: processProposal ? {
@@ -379,6 +381,7 @@ export async function prepareCheck(
         substitutionCount: bash.substitutions.length,
         mutationIntent: bash.mutationIntent,
         errors: bash.errors,
+        accesses: policy?.accesses,
       } : undefined,
       process: processProposal ? {
         source: processProposal.source,

package/src/check-mutation.ts

@@ -1,9 +1,15 @@
 import { generateUnifiedPatch } from "@earendil-works/pi-coding-agent";
 import { createHash } from "node:crypto";
 import { lstat, readFile, realpath } from "node:fs/promises";
-import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { basename, dirname, relative, resolve, sep } from "node:path";
 import { previewApplyPatch } from "./apply-patch";
 import type { CheckedToolName } from "./check-approvals";
+import {
+  canonicalPathIdentityAllowMissing,
+  isPathInsideOrSame,
+  pathIdentity,
+  pathsHaveSameIdentity,
+} from "./platform";
 
 export type MutationSensitivity = {
   executable: boolean;
@@ -66,11 +72,6 @@ function windowsAbsolute(path: string): boolean {
   return /^[A-Za-z]:[\\/]/.test(path) || /^\\\\/.test(path) || /^\/\//.test(path);
 }
 
-function insideRoot(root: string, path: string): boolean {
-  const rel = relative(root, path);
-  return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
-}
-
 async function validateEditPath(
   cwd: string,
   inputPath: string,
@@ -83,23 +84,34 @@ async function validateEditPath(
   const projectRoot = await realpath(cwd);
   const roots = await Promise.all([projectRoot, ...allowedPaths].map((path) => realpath(path)));
   const absolute = resolve(projectRoot, inputPath);
-  const root = roots.sort((first, second) => second.length - first.length)
-    .find((candidate) => candidate === absolute || insideRoot(candidate, absolute));
+  const sortedRoots = roots.sort((first, second) => second.length - first.length);
+  let root = sortedRoots.find((candidate) => isPathInsideOrSame(candidate, absolute));
+  if (!root) {
+    let targetIdentity: string;
+    try {
+      targetIdentity = await canonicalPathIdentityAllowMissing(absolute);
+    } catch {
+      throw new Error(`Edit path is outside the allowed Check mode paths: ${inputPath}`);
+    }
+    root = sortedRoots.find((candidate) => isPathInsideOrSame(pathIdentity(candidate), targetIdentity));
+  }
   if (!root) throw new Error(`Edit path is outside the allowed Check mode paths: ${inputPath}`);
+  const canonical = await realpath(absolute);
 
-  let component = root;
-  const rel = relative(root, absolute);
-  for (const part of rel.split(sep).filter(Boolean)) {
-    component = resolve(component, part);
+  let component = absolute;
+  while (true) {
     const metadata = await lstat(component);
     if (metadata.isSymbolicLink()) throw new Error(`Edit path contains an escaping link or junction: ${inputPath}`);
+    if (await pathsHaveSameIdentity(component, root)) break;
+    const parent = dirname(component);
+    if (parent === component) throw new Error(`Edit path is outside the allowed Check mode paths: ${inputPath}`);
+    component = parent;
   }
-  const canonical = await realpath(absolute);
-  if (!insideRoot(root, canonical)) throw new Error(`Edit path resolves outside the project: ${inputPath}`);
+  if (!isPathInsideOrSame(root, canonical)) throw new Error(`Edit path resolves outside the project: ${inputPath}`);
   const metadata = await lstat(absolute);
   if (!metadata.isFile()) throw new Error(`Edit path is not a file: ${inputPath}`);
-  const display = projectRoot === absolute || insideRoot(projectRoot, absolute)
-    ? relative(projectRoot, absolute).split(sep).join("/")
+  const display = isPathInsideOrSame(projectRoot, canonical)
+    ? relative(projectRoot, canonical).split(sep).join("/")
     : absolute;
   return { root, absolute, display, mode: metadata.mode };
 }

package/src/check-paths.ts

@@ -1,8 +1,13 @@
 import { lstat, realpath } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { dirname, resolve } from "node:path";
 import { AGENT_DIR } from "./config";
 import { isCredentialSensitivePath } from "./check-policy";
+import {
+  canonicalPathIdentityAllowMissing,
+  isPathInsideOrSame,
+  pathIdentity,
+} from "./platform";
 import {
   checkPathsForProject,
   MAX_CHECK_PATHS_PER_PROJECT,
@@ -39,11 +44,6 @@ export function parseCheckPathCommand(input: string): CheckPathCommand | undefin
   return { action: action[1] as "add" | "remove", path };
 }
 
-function insideOrSame(parent: string, candidate: string): boolean {
-  const rel = relative(parent, candidate);
-  return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
-}
-
 async function canonicalDirectory(input: string, cwd: string): Promise<string> {
   const absolute = resolve(cwd, input);
   const canonical = await realpath(absolute);
@@ -57,10 +57,10 @@ async function canonicalDirectory(input: string, cwd: string): Promise<string> {
     realpath(AGENT_DIR).catch(() => resolve(AGENT_DIR)),
     realpath(homedir()).catch(() => resolve(homedir())),
   ]);
-  if (insideOrSame(canonical, agentDirectory) || insideOrSame(agentDirectory, canonical)) {
+  if (isPathInsideOrSame(canonical, agentDirectory) || isPathInsideOrSame(agentDirectory, canonical)) {
     throw new Error("Check path cannot contain or enter PUM's configuration directory");
   }
-  if (insideOrSame(canonical, homeDirectory)) {
+  if (isPathInsideOrSame(canonical, homeDirectory)) {
     throw new Error("Check path cannot contain the home directory");
   }
   return canonical;
@@ -68,7 +68,7 @@ async function canonicalDirectory(input: string, cwd: string): Promise<string> {
 
 async function removalIdentity(input: string, cwd: string): Promise<string> {
   const absolute = resolve(cwd, input);
-  return realpath(absolute).catch(() => absolute);
+  return canonicalPathIdentityAllowMissing(absolute);
 }
 
 export async function applyCheckPathCommand(
@@ -102,10 +102,13 @@ export async function applyCheckPathCommand(
     : await removalIdentity(command.path, cwd);
   const project = await realpath(cwd);
   if (command.action === "add") {
-    if (canonical === project || insideOrSame(project, canonical)) {
+    if (isPathInsideOrSame(project, canonical)) {
       throw new Error("The directory is already inside the project boundary");
     }
-    if (paths.includes(canonical)) throw new Error(`Check path is already allowed: ${canonical}`);
+    const identity = pathIdentity(canonical);
+    if (paths.some((path) => pathIdentity(path) === identity)) {
+      throw new Error(`Check path is already allowed: ${canonical}`);
+    }
     if (paths.length >= MAX_CHECK_PATHS_PER_PROJECT) {
       throw new Error(`Check mode allows at most ${MAX_CHECK_PATHS_PER_PROJECT} additional paths per project`);
     }
@@ -117,7 +120,8 @@ export async function applyCheckPathCommand(
     };
   }
 
-  const index = paths.indexOf(canonical);
+  const identity = pathIdentity(canonical);
+  const index = paths.findIndex((path) => pathIdentity(path) === identity);
   if (index < 0) throw new Error(`Check path is not configured: ${canonical}`);
   const nextPaths = paths.filter((_path, candidate) => candidate !== index);
   return {