Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

fix(canvas): stop the file manager calling an unreachable filesystem empty

albaneselorenzoc0f4c284be24
diff --git a/CLAUDE.md b/CLAUDE.md
index 7637af0c5..ce30d05c3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -963,9 +963,12 @@ session.
(`main/ssh-fs.ts:164-176`) refuses, on the rule "a failed read is never evidence of absence". Now
disambiguated by probing the PARENT's listing instead (`classifyEmptyListing`, pure,
`lib/filesNode.ts` — the idiom `SshProjectDialog.tsx:112-125` and `file-links.ts`'s
- `makeDirListingLookup` already use), which answers `missing` / `empty` / `unknown`: an unreadable
- parent answers `unknown`, and we keep saying "empty" rather than claim a deletion we can't
- prove. **`unknown` also covers every path whose parent CANNOT answer** — a non-`/`-absolute cwd
+ `makeDirListingLookup` already use), which answers `missing` / `empty` / `unreachable` /
+ `unknown`. The parent CONTAINS the directory we are standing in, so it cannot legitimately be
+ childless: an empty parent listing means we could not see it, which is `unreachable` and gets
+ its own sentence naming both possible causes. That case used to answer `unknown` and render as
+ "This folder is empty." over a dead ControlMaster, the commonest cause of an empty remote
+ listing and the most reassuring possible lie. **`unknown` is reserved for the paths whose parent CANNOT answer** — a non-`/`-absolute cwd
(an SSH project's `remoteCwd` defaults to **`~`**, where `parentDir` is `/` and `/` has no entry
named `~`, so an empty remote HOME reported a deletion), a `.git` cwd (both listing legs strip
it on purpose), and `.`/`..` segments; a case-folded match counts as present, for the
@@ -1031,7 +1034,11 @@ session.
- **The `/`-separator assumption is a KNOWN gap, shared with `explorerCreate`** (the Explorer
drawer and canvas "New file…" already run on the same helpers) — `C:\x\y` reads as one segment.
To be closed in ONE place for both, using the core-owns-the-dialect rule `terminal/file-links.ts`
- already implements.
+ already implements. The TRAVERSAL half is closed: `newEntryPath` splits its `..` check on
+ `[\\/]` and refuses a Windows-absolute name, because a guard that reads `\` as ordinary text is
+ wrong about the machine that resolves the path. The construction half deliberately is not: on
+ POSIX a backslash is legal filename text, so the join stays `/` and `weird\name.txt` is still
+ one file. Guard on both dialects, construct in one.
- **Mobile**: N/A — *nodeterm mobile* attaches to tmux sessions over the transport protocol and
has no canvas or file-browsing concept; adding one means extending that protocol.
- **dino** (`DinoNode.tsx`) — a small self-contained T-Rex-style runner on a canvas (no PTY);
diff --git a/src/renderer/lib/filesNode.test.ts b/src/renderer/lib/filesNode.test.ts
index 7a3595228..be789bb84 100644
--- a/src/renderer/lib/filesNode.test.ts
+++ b/src/renderer/lib/filesNode.test.ts
@@ -116,15 +116,25 @@ describe('classifyEmptyListing', () => {
expect(classifyEmptyListing('/repo/docs/', parent)).toBe('empty')
})
- // "A failed read is never evidence of absence" (SshFs.readTextChecked). Under the same
- // fail-open contract an empty PARENT means unreadable-or-gone, not childless — so we learned
- // nothing and must not tell the user their folder was deleted.
- it('says unknown when the parent itself came back empty', () => {
- expect(classifyEmptyListing('/repo/docs', [])).toBe('unknown')
+ // The parent contains us, so it cannot legitimately be childless: an empty listing means we
+ // could not see it. That is real information, and reporting it as `unknown` let the node say
+ // "This folder is empty." over a dead ControlMaster, which is the commonest cause of an empty
+ // remote listing.
+ it('says unreachable when the parent itself came back empty', () => {
+ expect(classifyEmptyListing('/repo/docs', [])).toBe('unreachable')
})
- it('says unknown when the parent could not be asked at all', () => {
- expect(classifyEmptyListing('/repo/docs', null)).toBe('unknown')
+ it('says unreachable when the parent could not be asked at all', () => {
+ expect(classifyEmptyListing('/repo/docs', null)).toBe('unreachable')
+ })
+
+ // The distinction that keeps `unreachable` honest: a path whose parent could never answer is
+ // still `unknown`, so a `~` root or a `.git` cwd does not start claiming the host is down.
+ it('keeps unknown for the paths no parent listing could ever answer', () => {
+ expect(classifyEmptyListing('~', null)).toBe('unknown')
+ expect(classifyEmptyListing('~', [])).toBe('unknown')
+ expect(classifyEmptyListing('/repo/.git', [])).toBe('unknown')
+ expect(classifyEmptyListing('relative/dir', [])).toBe('unknown')
})
// Root has no parent to interrogate and always exists.
diff --git a/src/renderer/lib/filesNode.ts b/src/renderer/lib/filesNode.ts
index 41d1dc4a2..4cd750a86 100644
--- a/src/renderer/lib/filesNode.ts
+++ b/src/renderer/lib/filesNode.ts
@@ -81,7 +81,7 @@ export function displacedFilesPatch(
: { cwd: fallbackCwd }
}
-export type EmptyListingVerdict = 'empty' | 'missing' | 'unknown'
+export type EmptyListingVerdict = 'empty' | 'missing' | 'unreachable' | 'unknown'
/**
* What an EMPTY listing actually means.
@@ -98,15 +98,18 @@ export type EmptyListingVerdict = 'empty' | 'missing' | 'unknown'
* is never evidence of absence*. Instead we ask the PARENT's listing, the same way
* `SshProjectDialog` and `file-links.ts`'s `makeDirListingLookup` already answer this question.
*
- * Three answers, and the third is the point:
+ * Four answers, and the last two are the point:
* - `missing` — the parent listed real entries and ours is not among them. Only this earns the
* error state.
* - `empty` — the parent lists us, so the directory is there and simply has nothing in it.
* Root takes this too: it has no parent to ask and always exists.
- * - `unknown` — the parent itself came back empty, which under the same fail-open contract means
- * the parent is unreadable or gone rather than childless. We learned nothing, so we claim
- * nothing; the caller keeps saying "empty". Understating beats telling someone their folder
- * was deleted because a network hiccup ate one `ls`.
+ * - `unreachable` — the parent came back empty or could not be read at all. It cannot be
+ * childless, since it contains us, so this says we could not see the filesystem. We still
+ * cannot tell "the whole subtree is gone" from "the connection is down", so the verdict names
+ * the doubt instead of guessing.
+ * - `unknown` — the path SHAPE means no parent listing could ever answer (see below). Genuinely
+ * no information, so the caller keeps saying "empty". Understating beats telling someone their
+ * folder was deleted because a network hiccup ate one `ls`.
*
* Matching is by NAME, not by `dir`, deliberately: a symlinked directory can list as a non-dir
* entry depending on the leg, and mistaking one for "missing" is the false alarm this exists to
@@ -134,7 +137,15 @@ export function classifyEmptyListing(
// node pointed at one can never find itself in its parent.
if (!trimmed.startsWith('/') || name === '.' || name === '..' || name === '.git') return 'unknown'
- if (!parentEntries || parentEntries.length === 0) return 'unknown'
+ // The parent could not be read. Note it cannot legitimately be EMPTY either: it contains the
+ // directory we are standing in, so an empty listing means we could not see it, exactly as the
+ // fail-open contract allows. That is real information and it used to be thrown away as
+ // `unknown`, leaving the node saying "This folder is empty." over a dead ControlMaster, which
+ // is the most common cause of an empty remote listing and the most reassuring possible lie.
+ //
+ // We still cannot say WHICH (the whole subtree deleted, or the filesystem out of reach), so the
+ // verdict names the doubt rather than picking one.
+ if (!parentEntries || parentEntries.length === 0) return 'unreachable'
if (parentEntries.some((e) => e.name === name)) return 'empty'
// A case-insensitive filesystem (APFS, NTFS) lists a directory fine under a cwd whose case
// differs from the on-disk spelling, and `readdir` answers with the on-disk one. Treat that as
diff --git a/src/renderer/nodes/FilesNode.tsx b/src/renderer/nodes/FilesNode.tsx
index 396c7588f..6cc1cbd26 100644
--- a/src/renderer/nodes/FilesNode.tsx
+++ b/src/renderer/nodes/FilesNode.tsx
@@ -48,6 +48,14 @@ import { ContextMenu, type MenuItem } from '../components/ContextMenu'
import { isBrowserRuntime } from '../bridge/runtime'
import { canUseLocalShell } from '../lib/download'
+/**
+ * Shown when the parent listing could not be read either. It deliberately names BOTH possible
+ * causes rather than picking one: the fail-open `FsApi` contract gives an empty array for a
+ * deleted directory and for a dead ControlMaster alike, so the honest thing is to say we could
+ * not see it and let the user tell the two apart.
+ */
+const UNREACHABLE_MESSAGE = 'Could not reach this folder. It may be gone, or its filesystem may be unavailable.'
+
/** Surface a transient error the way every other node does (Canvas listens for this). */
const toast = (message: string): void => {
window.dispatchEvent(new CustomEvent('nodeterm:toast', { detail: { kind: 'error', message } }))
@@ -156,13 +164,17 @@ export function FilesNode({ id, data, selected }: NodeProps<CanvasNode>) {
try {
if (parent !== cwd) parentEntries = await fs.list(parent)
} catch {
- parentEntries = null // could not ask ⇒ claim nothing
+ parentEntries = null // could not ask, so claim nothing
}
if (!live) return
setListing({ cwd, entries: list })
- if (classifyEmptyListing(cwd, parentEntries) === 'missing') {
- setError('Could not read this folder.')
- }
+ // Only `empty` and `unknown` fall through to "This folder is empty.", and they are the two
+ // cases where that sentence is true or at least not a claim. The other two each get their
+ // own, because saying "empty" over a folder that is gone, or over a filesystem we simply
+ // could not see, is the reassuring kind of wrong.
+ const verdict = classifyEmptyListing(cwd, parentEntries)
+ if (verdict === 'missing') setError('Could not read this folder.')
+ else if (verdict === 'unreachable') setError(UNREACHABLE_MESSAGE)
})()
return () => {
live = false