Skip to content

docs(sandboxes): document file read refusal codes - #237

Open
kinghrothgar wants to merge 2 commits into
mainfrom
VOL-1911/sandbox-file-read-codes
Open

kinghrothgar wants to merge 2 commits into
mainfrom
VOL-1911/sandbox-file-read-codes

Conversation

@kinghrothgar

Copy link
Copy Markdown
Contributor

Tracking

Why

  • a Sandbox file read of a missing or unreadable path answered 503; Hosting now answers it with a coded client error, and the guide should list those codes

Summary

  • document sandbox_file_not_found (404), sandbox_file_unreadable (400) and sandbox_file_too_large (413) for POST /sandbox-sessions/{id}/files/read in content/platform/guides/sandboxes.md
  • note that sessions on images built before the codes still answer 503

Verification

  • node scripts/lint-docs.mjs content/platform/guides
  • merge when the Hosting change reaches production

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

AI review: 1 P0-P2 finding(s)

Reviewed 2adf0ce. Run log

Documents Sandbox file-read error codes and legacy-image behavior. This is a low-risk documentation change, but the new recovery advice does not work for all listed cases.

🟡 P2

  • content/platform/guides/sandboxes.md:591 Scope the copy workaround to files the session user can read (also reported as: "Copy such a file with an exec command" can't work for an unreadable file, a directory, or a socket)

Not checked: The AI review read the diff, the code, and the PR's text; it ran no tests or builds and read nothing outside this repository.

  • Whether production Hosting's files/read endpoint returns these statuses and codes, and 503 for sessions on older images, before this merges, as the release-timing rule in spec/writing.md requires.
  • Whether the owner and hard-link checks really apply only to cloud sessions and not local mode, as the paragraph says; the listing table at line 783 states them without that limit.
  • Confirm that production Hosting and released sandbox images provide the documented status/code mappings and legacy-image behavior before publishing, as spec/writing.md requires.

Push a fix, or have a collaborator with write access (including the PR author) add the ai-review-override label to accept 2adf0ce as is. An override also needs a human review.

Failing round 1 of 3 since this PR was last marked ready for review. If 3 rounds in a row find P0-P2 problems, the AI review moves the PR back to draft for the author to re-assess the approach.

Human review: not needed

A directory, symbolic link, socket, or other special file at the path returns
`400` with code `sandbox_file_unreadable`, as does a file the session user can't
read and, in a cloud session, a file another user owns or one with more than one
hard link. Copy such a file to a new one with an exec command, then read the

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: "Copy such a file with an exec command" can't work for an unreadable file, a directory, or a socket

The paragraph lists several cases: directories, symbolic links, sockets and other special files, a file the session user can't read, and (in a cloud session) a file another user owns or one with more than one hard link. It then says "Copy such a file to a new one with an exec command, then read the copy." Line 580 says exec commands run as the session user. So cp fails with permission denied on a file that user can't read, and copying a directory or socket doesn't produce a regular file to read. The advice only works for the readable cases: a file another user owns, a file with more than one hard link, and a symlink to a regular file. Fix: say which cases the copy advice is for, for example "Copy a file another user owns or one with more than one hard link…". For a file the session user owns with its read bit clear, suggest chmod u+r.

Found by claude-opus-5-5

A directory, symbolic link, socket, or other special file at the path returns
`400` with code `sandbox_file_unreadable`, as does a file the session user can't
read and, in a cloud session, a file another user owns or one with more than one
hard link. Copy such a file to a new one with an exec command, then read the

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 P2: Scope the copy workaround to files the session user can read

The preceding list includes files the session user cannot read, but exec commands run as that same user, so copying those files also fails with a permission error. Copying a directory or socket likewise does not produce readable regular-file content. Restrict this workaround to readable file content and provide separate guidance for permission failures and non-file paths.

Found by gpt-6.1-sol

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant