An upload lands in session:/, the directory the session works in, which for a local session is the checkout, and says so; a path whose prefix names no mount is refused with the prefixes there are¶
Decision 896 · accepted · 2026-10-13 · issue #620
620 found two things beside each other. /upload and fs.upload said a file went into¶
"the session's own mount", and for a session on a pod that is true: session:/ is the
session's own directory, erased with it. For a local session session:/ is the person's
checkout, so an uploaded file lands in the working tree, where git add -A picks it up,
another session in the same checkout sees it, and erasing the session leaves it. And a
path with a prefix that is no mount (scratch:/plan.md before the scratchpad existed, or
plans:/plan.md) was taken as a relative path, which on Linux wrote a directory literally
named plans:.
Kept in the checkout, and said. The choice was between that and a session-private
area, as the scratchpad's documents have (Decision 870). The private area loses: an upload
is a file the person hands the session to work with, and the session works in
session:/; a file elsewhere would be one the agent's file tools and its commands reach by
another name, and for a local session the person's file was already on the same machine.
What was wrong was the sentence, not the place. So /upload's help (and with it the command
reference, which is written from the same table) and PROTOCOL.md's fs.upload say where the
file lands for each kind of session, and what that means in a checkout. A file the person
does not want in the checkout is one they do not upload to a local session.
An unknown prefix is refused. A path that begins with a word of two or more letters,
digits, dashes or underscores, then a colon, then a slash or nothing, is a prefix. One
that names none of session:, team:<name>, org:, skills: and scratch: is
{:unknown_mount, word}, and the sentence names the ones there are. It is refused in
Troupe.Mounts, so fs.upload, fs.read, fs.list and every file tool refuse it alike.
A colon later in a name (notes:2026.md) and a Windows drive letter (C:/) are not
prefixes, and resolve as they did.
Proof. mounts_test.exs (an unknown prefix refused with the sentence; a colon in a
name and a drive letter not taken for one) and files_test.exs (fs.upload to
plans:/plan.md is forbidden, names session:/ and scratch:/, and writes nothing).
Governs: apps/troupe_core/lib/troupe/mounts.ex, apps/troupe_core/lib/troupe/workspace.ex, apps/troupe_core/lib/troupe/tool.ex, apps/troupe_core/lib/troupe/commands.ex, apps/troupe_gateway/lib/troupe/gateway/dispatch.ex, clients/tui/lib/troupe/ui/tui/server.ex