relayfile tree cannot enumerate completely: depth shrinks results and nextCursor has no CLI flag

[khaliqgant]

relayfile tree cannot enumerate completely, and it fails silently

Found by an agent writing a multi-host mount skill, which needed to assert coverage of a mount rather than sample it.

1. Higher depth returns fewer rows

Increasing --depth returned a smaller row count than a shallower call on the same path. Whatever the intended semantics, that is unsound: a caller cannot use depth to widen a listing, and there is no way to tell from the output that rows were dropped. A completeness check written against tree silently under-reports.

2. The cursor exists in the payload but not on the CLI

The JSON response exposes nextCursor, so the server clearly paginates and can express "there is more". The CLI has no --cursor flag to pass it back. So a complete enumeration is expressible over the wire and impossible from the command line — the caller can see that it received a partial answer and has no way to ask for the rest.

That combination is the real defect: truncation is detectable and unresolvable.

Consequence

Any tooling that uses relayfile tree to answer "does this mount contain everything it should?" gets a confident wrong answer. That is precisely the question a health check needs to ask, and it is how a stale or partial mount reads as complete.

This is not hypothetical: the same session found the mount projection wedged — the sync daemon reporting lag=0, pending=0 and writing state continuously while projected content was hours to days old, with a GitHub issue filed at a known minute absent from the projection entirely. Coverage assertions are the defence against that, and tree cannot currently support one.

Workaround now in use

Recursive depth-1 walk plus an explicit coverage assertion, rather than a single deep tree call. Documented in the multi-host live-mount skill (AgentWorkforce/skills#94). It is correct but O(directories) round trips, which is a poor trade for a listing operation.

Asked for

1. Fix depth so a larger depth is a superset of a smaller one, or document precisely what it means and why it shrinks.
2. Add --cursor (and ideally --all) to the CLI so a caller can drain nextCursor and enumerate completely.
3. Make truncation explicit in human-readable output too — a caller should not have to parse JSON to learn the answer was partial.

Filed by Chief on behalf of the skill author. Scope is AgentWorkforce/relayfile only. Not labelled for dispatch.