org.llm4s.agent.harness.workspace

A containerised workspace's files as a FileBackend (design §4.33): /src/a.txt is the workspace's src/a.txt, / its root. One workspace is one tenant's: an application serving several builds one backend per tenant and picks it with FileBackend.resolved (rule 8).

• '''Order.''' A mutation locks the whole workspace, files/workspace/<id> (WorkspaceLocks), as a command there does, so a batch's edits and commands apply in call order, even two paths that name one file through a link. Reads take no lock and see the workspace as it is.
• '''Replay.''' The target is Verifiable (C4). Each mutation runs ReplayGuard.verifiable under ctx.effectKey("file.write" | "file.edit" | "file.delete", path): the plan reads the file once, makes every refusal, and plans a compare-and-set against the hash it read, which the runner applies atomically under its mutation lock and replaces the file atomically. So a replayed edit that landed returns its first outcome, one that did not runs again, and one whose file another writer changed is refused.
• '''Bounds.''' Content and an edit's result at most maxFileBytes UTF-8 bytes, checked before they are sent; a read at most the runner's maxFileSize; listings at most the runner's maxDirectoryEntries, then limit. A listing the runner cut is truncated, its entries those the runner returned, sorted.
• '''Block.''' A workspace effect stays when a Block retracts its turn (rule 5).

Listings show what the runner's default exclusions (.git, node_modules, ...) leave, and skip entries whose names are not valid paths. grep reads each file whole, as text: a file that is not UTF-8 or is over the runner's size limit is skipped and the listing marked truncated.

The locks of a workspace's backends (design §4.33): a file mutation and a command alike lock the whole workspace, files/workspace/<id>, so a batch's edits and commands apply one after another in call order. A per-path key would not do: two paths can name one file through a link (/alias -> /real), and their edits must still be ordered. The key is under C3's FileBackend.LockRoot, as FileBackend.resolved requires of a resolved backend's locks.

The SandboxBackend of a containerised workspace: SandboxBackend over a WorkspaceSandboxRunner.

Runs commands in a containerised workspace, for a SandboxBackend (design §4.33). It only runs: the backend wraps every run in C4's Unverifiable guard, so a completed command replays its stored ExecResult and one that may have run is refused, never run again. A command locks files/workspace/<id> (WorkspaceLocks), so it conflicts with every file mutation in its workspace.

The runner runs a command as a program and its arguments, never through a shell, and refuses what the sandbox's command policy forbids; that refusal is a tool error. Each stream is kept to maxOutputBytes characters by the runner while it reads, and cut again by the backend. A command the runner's timeout killed is an outcome, exit code -1, recorded like any other.