A scan that constructs the paths it will read can only find what its author already knew existed

The lesson

There are two ways to find files in a store you did not write. Enumerate it — ask the directory what is in it — or construct the paths you expect and read those. They look alike in code and are opposite in kind. Enumeration can return something you did not anticipate; construction can only ever return what you already thought of.

Construction is tempting exactly where the store has a documented naming rule, because the rule makes the path derivable, and a derivable path feels like knowledge rather than a guess. It is a guess about the population, not about the encoding: the encoding may be perfectly right for every path you build and still describe two members of a set with dozens.

The damage is that this failure has no error state. A constructed path that does not exist reads identically to a store that is empty, so the surface built on top reports "nothing here" — an affirmative, plausible, wrong answer — rather than failing. Nobody investigates a quiet panel. And because the constructed roots are almost always the author's own working context, the thing works perfectly during development and is blind in exactly the situation it was built for.

A related trap sits on the other side: once you do enumerate, the directory name is often an encoding of something else, and the encoding may be lossy. Ask the found artifact what it is rather than decoding its container's name where the artifact can answer.

The failure that taught it

A monitoring panel showed which automated agents were running, reading the transcript files the agent harness writes into a per-workspace state directory. The harness encodes a workspace path into a directory name by a simple documented rule, so the panel derived the two directory names it expected — the repository root and a subdirectory inside it that could also own a session — and scanned those.

It worked. Agents launched from that repository appeared, with correct liveness, correct labels, correct grouping into fan-out runs. Every deliberate test of it passed, because every test was run from that repository.

It was reported as "the panel only tracks this one project". The state directory in fact held twenty-four workspaces, and the panel had been reading two of them. Sessions in every other checkout were not merely unlabelled or misattributed — they did not exist as far as the panel was concerned, and it drew its idle state, an explicit "resting" indicator, while other work was running. The code carried a careful comment justifying why both encodings were checked "rather than assumed", which is precisely the kind of local rigour that hides a global omission: the author had reasoned hard about which of their two candidate roots was right, and never about the set.

The fix was one line of intent — enumerate the state directory, keep the newest session per workspace — and it immediately surfaced a live session in an unrelated checkout that had been invisible the whole time.

Choosing a display name for each workspace then reproduced the same shape in miniature. The obvious source is the directory name, but the encoding replaces every path separator with a dash, so a name that legitimately contains a dash is indistinguishable from a nested path. The transcripts themselves record the real working directory, so the label is read from the file and the decoded directory name is only a fallback.

How to apply it

• When reading a store you did not write, treat "enumerate" as the default and "construct" as the exception that needs an argument. The argument has to be about the population — "there is exactly one, by construction" — not about the naming rule being reliable.
• Ask of any listing function: what would this return if the thing I am looking for were somewhere I did not think of? If the answer is "the empty list", it cannot distinguish absence from ignorance, and neither can its caller.
• Suspect any monitor that has only ever been exercised from the author's own working context. The bias is not random — a constructed search set is built from where the author was standing, which is the one place it is guaranteed to work.
• A comment explaining why a hardcoded set is complete is a signal to check, not a reason to relax. Rigour about which candidates to include reads exactly like rigour about the set being the right set.
• Where enumeration exposes container names that encode something else, prefer asking the contained artifact for the attribute over decoding the container, especially when the encoding is lossy.
• Cap what enumeration costs rather than narrowing what it looks at. A bounded read per found item, or a limit on how many are displayed, keeps a wide scan cheap; a narrow scan is cheap and wrong.