Idea: LIST/GLOB — enumerate guest files without shelling out

[otaviocarvalho]

Problem

There is no primitive for directory enumeration on the guest filesystem. Clients that need to discover files must either exec a shell (ls/find), which couples clients to guest shell semantics and bypasses structured errors and accounting, or maintain client-side ledgers that drift from actual filesystem state.

Follow-up from #72: append makes segmented, append-only logs viable inside guests; enumeration is the complementary half of that workload. Our concrete case: agents write rotating segment files (seg.0.jsonl, seg.1.jsonl, …), and a host-side poller needs to enumerate segments it hasn't read. This generalizes to checkpoint discovery, temp-file cleanup passes, and any "what exists in this directory" query.

Proposal

Additive RPC (or an optional surface on the existing message set), single-directory scope for v1:

message ListFilesRequest {
  string path = 1;      // directory to list
  string pattern = 2;   // optional glob, e.g. "seg.*.jsonl"
  int32 limit = 3;      // page size
  string page_token = 4;
}
message ListFilesResponse {
  repeated FileEntry entries = 1;
  string next_page_token = 2;
}
message FileEntry {
  string name = 1;
  int64 size = 2;
  google.protobuf.Timestamp modified = 3;
  uint32 mode = 4;
}

• Deterministic ordering: entries sorted by name.
• Pagination (limit/page_token) keeps large directories bounded.
• Out of scope for v1: recursive walks; streaming/watch semantics — the fuller long-term answer for tailing workloads, but a substantially larger surface, worth discussing separately.

Alternatives considered

• Exec find/ls in the guest — rejected: shell coupling, unstructured output and errors, no accounting.
• Client-side segment ledgers — rejected: duplicate directory state, drifts from the filesystem, and must be reimplemented in every client.
• ReadFile on directories — not meaningful under current read semantics; would overload the read path.

If this fits the project's direction, I'm glad to draft the PR — proto + guest implementation + e2e test, same shape as #72.