Docs: push memory limit and terminal TLS refusals in troubleshooting (#165)
git.md names the 80 MiB unpack memory limit (#162) in the push steps and gives its error a troubleshooting row. The terminal troubleshooting table explains the jail proxy's new refusals when a TLS ClientHello names another host, none, or hides it (#163). Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016q5wwBFck8JHq14gHUM2CL
Canberk Demirci authored · GitHub committed signed1 parent ffd58b3commit 7dd2e1c9e8a1acad2f872addbc02bb741952d015Browse files
2 files changed+3−1
modifiedapps/diffinery/docs/agents/terminal.md+1−0View file
| @@ -138,6 +138,7 @@ | ||
| 138 | 138 | | --- | --- | |
| 139 | 139 | | No **Give it a task** box, or `the terminal was opened without agent tasks` | The terminal was opened without **Will run agent tasks**. End it and open another with the box ticked. | |
| 140 | 140 | | `diffinery: refused a connection to <host>:443 from the task (only the hosts in /docs/agents/terminal#what-a-task-can-reach)` in the transcript | The agent or a tool it ran tried a host outside the [list](#what-a-task-can-reach). Work that needs other hosts belongs in a task with a [sandbox of its own](/docs/agents/tasks), or in the terminal itself, outside a task. | |
| 141 | +| `diffinery: refused a connection to <host>:443 from the task: its TLS ClientHello asks for <other host>` (or `names no single server, or hides it (Encrypted Client Hello)`, or `no TLS ClientHello`) | The tunnel opens only when the TLS handshake names the host the tool asked the proxy for. A tool that sends a different server name, none, or Encrypted Client Hello, or that doesn't start TLS within 10 seconds, is refused. Point the tool at the allowed host by its own name and turn off Encrypted Client Hello in it. | | |
| 141 | 142 | | `go: ... dial tcp ...` or another Go module download error | Go modules aren't reachable from a terminal task. Commit them with `go mod vendor`, or run the task in a sandbox of its own. | |
| 142 | 143 | | The task fails with "The task's jail couldn't start in this terminal's sandbox, so nothing ran." | bubblewrap couldn't start in the sandbox; the transcript has its error. Nothing ran and nothing was pushed. End the terminal, open a new one and run the task again. | |
| 143 | 144 | | The terminal's Claude Code or Codex asks you to sign in again after a task | The CLI refreshed its sign-in inside the task, on its private copy, and the provider retired the old refresh token. Sign in again in the terminal. | |
modifiedapps/diffinery/docs/repositories/git.md+2−1View file
| @@ -217,7 +217,7 @@ | ||
| 217 | 217 | |
| 218 | 218 | 1. **Authorization.** You must send a token: a push without credentials gets HTTP 401 (`authentication required`) with a `WWW-Authenticate` challenge, for public and private repositories alike, which makes Git ask for credentials and retry. Your account needs write access, your token the `write` or `admin` scope, and the repository must not be archived. Otherwise the server answers HTTP 403 (`write access required` when your role only allows reading, `this token needs the write scope` for a `read`-scoped token, or `repository is archived (read-only)`), or HTTP 404 if the account can't see the repository at all. Git shows these as `Authentication failed` or `The requested URL returned error: 403`. |
| 219 | 219 | 2. **Size check.** A push larger than 100 MB (after decompression), or one whose pack unpacks to more than 512 MiB, is refused. Git shows `remote unpack failed: push exceeds 100 MB; split it into smaller pushes`, or an HTTP error if the request is stopped before it reaches Diffinery. |
| 220 | -3. **Unpacking.** The pack is parsed and every object checked. | |
| 220 | +3. **Unpacking.** The pack is parsed and every object checked. Unpacking may hold at most 80 MiB at once; a push that needs more is refused with `pack needs more than 80 MiB of memory to unpack; split it into smaller pushes`. | |
| 221 | 221 | 4. **Push protection.** New text files are scanned for credentials such as AWS keys, GitHub and Diffinery tokens, Slack and Stripe keys, Google, Anthropic and OpenAI API keys, and private keys. If any are found, the whole push is rejected, nothing from it is stored, and the output lists each finding: |
| 222 | 222 | |
| 223 | 223 | ```text |
| @@ -338,6 +338,7 @@ | ||
| 338 | 338 | | `The requested URL returned error: 403` on push from a workflow | The job's token has no `contents: write` (`Resource not accessible by integration`). | Add `permissions: contents: write` to the workflow or job, or have an admin change the repository's default workflow permissions. | |
| 339 | 339 | | `[remote rejected] ... (refusing to allow a GitHub App to create or update workflow ...)` | A workflow's job token tried to push a change to a workflow file. | Push workflow changes with a personal or agent token instead. | |
| 340 | 340 | | `remote unpack failed: the push needs more memory than one push may use; split it into smaller pushes (...)` | Unpacking or storing this push ran out of the memory one push may use, even though it is under the size limits. Nothing from the push is kept. | Push history in steps, oldest first, as for the 100 MB limit below. The GitHub importer does this by itself. | |
| 341 | +| `remote unpack failed: pack needs more than 80 MiB of memory to unpack; split it into smaller pushes` | Unpacking would hold more than 80 MiB at once: files under 4 MiB inflated, plus about 768 bytes per object. Very many objects (well over 100,000) or many small files that compress well hit it before the size limits. See [Limits](/docs/reference/limits). | Push history in steps, oldest first, as for the 100 MB limit below. The GitHub importer does this by itself. | | |
| 341 | 342 | | `remote unpack failed: push exceeds 100 MB; split it into smaller pushes` | The pack for this push is larger than 100 MB. | Push history in steps, oldest first, for example `git push origin <older-commit>:refs/heads/main`, then later commits. Move large binaries to Git LFS. | |
| 342 | 343 | | `remote: Push refused: tree <id>: duplicate entry '<name>'` (or another reason), `remote unpack failed: fsck error: ...` and `[remote rejected] ... (fsck failed)` | A tree or `.gitmodules` file in the push fails git's `fsck` checks: an entry that is empty, `.`, `..`, a spelling of `.git`, contains `/` or appears twice, a `.gitmodules` that is a symbolic link, or a submodule whose name has `..` or whose `url` or `path` starts with `-`. Nothing from the push is kept. | Run `git fsck` locally to find the object, fix the tree or `.gitmodules` in a new commit (or rewrite the commit that added it), and push again. | |
| 343 | 344 | | `[remote rejected] ... (protected branch: required check '<name>' has not run on <sha>; ...)` | The branch requires status checks, and the commit you pushed hasn't passed them. | Push to another branch and open a pull request, or push a commit that already passed the checks. | |