[tamnd]

Closes #131.

The help lists exit 8 as "transport failure, the bytes did not arrive". One command returned it. cli/download.go:157 was the only errs.KindNetwork in the tree, so every other command that could not reach Common Crawl exited 1, which is the code for anything at all.

index.commoncrawl.org has been refusing connections for two days, so this was easy to see: crawls latest, search, and get all exited 1 with "connect: connection refused", indistinguishable from a bad crawl ID or a malformed pattern.

The change

The retry loop in ccrawl/client.go marks its exhaustion with ErrTransport when the last failure came from the transport rather than from a status the server sent. cli classifies that as errs.KindNetwork.

An exhausted 503 stays exit 1. The server was there and said no, and telling a supervisor otherwise sends it into a loop against a source that is up and refusing.

errs.KindOf walks the error chain, so classifying once at the point the transport gives up reaches the CLI, HTTP, and MCP surfaces together. ccrawl still does not import the framework: it exports a plain sentinel and cli does the classifying.

It is applied where commands are registered rather than in 34 handlers: handle over kit.Handle, and addCmd/addCmdUnder over AddCommand/AddCommandUnder, which walk the Sub tree. TestEveryHandlerIsClassified walks the source and fails on a registration that goes around them, since kit builds its cobra tree privately and a test cannot ask the binary what it registered. It counts 53 classified registrations today.

Measured against the live outage

command	exit	why
crawls latest	8	connect: connection refused
crawls list	8	connect: connection refused
search example.com/*	8	connect: connection refused
get example.com	8	connect: connection refused
paths bogus	8	connect: connection refused
rank host	2	expected at least 1 argument
rank top --graph nope-2020 -n 1	1	Rank table HTTP 404
download warc -n 1 --source s3	8	no AWS credentials
rank host wikipedia.org	0
paths warc -c CC-MAIN-2025-05	0

Before the change the first five were all 1.

The two unit tests on the ccrawl side use a closed port and a permanent 503 rather than the outage, so they keep working once Common Crawl comes back.

Docs

The exit codes reference named download as the only source of 8. It now describes what 8 means for every command, shows the outage as it looks from the shell, and carries a supervisor snippet that backs off on 8 and stops on anything else. The one thing that stays scoped to download is that it reports any download failure as a transport failure, --source s3 without credentials included.

Checks

gofmt, go vet, go test ./..., golangci-lint (0 issues), scripts/docs-drift.sh, scripts/coverage.sh all clean. cli coverage 52.4 to 52.6.