add build log access: nbapi build <id>, nbshell builds log, routing triggers

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "nixbuild",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "Operator surface for the nixbuild.net remote build service. A Haiku ops agent fronts three tools and two skills: nbshell drives nixbuild's interactive admin shell non-interactively (expect+PTY, the only way — its HTTP API is read-only and plain ssh stdin yields nothing), nbapi reads the metered account's usage/builds/storage over https://api.nixbuild.net, and nb-substituters manages account substituters with a guard for nixbuild's rejection of path-style cache URLs. Skills encode the settings workflow (substituters, trusted-public-keys, ssh-keys) and the usage/cost workflow. Encodes hard-won facts: builders-use-substitutes uses the REMOTE's own substituters not the client's; Attic's path-style URL is rejected so it must be reached path-less (e.g. via a Caddy root-rewrite); the admin shell needs a real PTY (ssh -T stdin is silent, ssh -tt is rejected, shell-as-ssh-args hits the build-runner channel needing run:write).",
 	"author": {
 		"name": "oleks",

agents/ops.md

@@ -1,6 +1,6 @@
 ---
 name: ops
-description: Operate the nixbuild.net remote build service — read the metered account's usage/storage/build history, manage account settings (binary-cache substituters, trusted public keys, SSH keys), and drive the interactive admin shell non-interactively. Trigger on <!-- BEGIN ROUTING TRIGGERS -->"nixbuild", "nixbuild.net", "eu.nixbuild.net", "remote builder usage", "how much build time left", "nixbuild storage", "nixbuild billing", "add a substituter to nixbuild", "nixbuild trusted key", "register a cache on nixbuild", "nixbuild ssh key", "nixbuild settings", "nixbuild build history", "free build time", "nixbuild account"<!-- END ROUTING TRIGGERS -->. Read-mostly; settings mutations are confirmed before applying. Owns the nbshell/nbapi/nb-substituters tools and the nixbuild-settings/nixbuild-usage skills.
+description: Operate the nixbuild.net remote build service — read the metered account's usage/storage/build history, manage account settings (binary-cache substituters, trusted public keys, SSH keys), and drive the interactive admin shell non-interactively. Trigger on <!-- BEGIN ROUTING TRIGGERS -->"nixbuild", "nixbuild.net", "eu.nixbuild.net", "remote builder usage", "how much build time left", "nixbuild storage", "nixbuild billing", "add a substituter to nixbuild", "nixbuild trusted key", "register a cache on nixbuild", "nixbuild ssh key", "nixbuild settings", "nixbuild build history", "free build time", "nixbuild account", "nixbuild build log", "remote build log", "build log missing", "remote builder output", "why did the remote build fail", "nixbuild failed build", "get build output from nixbuild", "fetch nixbuild log"<!-- END ROUTING TRIGGERS -->. Read-mostly; settings mutations are confirmed before applying. Owns the nbshell/nbapi/nb-substituters tools and the nixbuild-settings/nixbuild-usage skills.
 model: haiku
 color: blue
 tools: Bash, Read, AskUserQuestion, Skill
@@ -31,15 +31,16 @@ is the #1 failure mode:
 
 # Your tools (all under `${CLAUDE_PLUGIN_ROOT}/bin`)
 
-- **`nbapi <usage|summary|builds|raw>`** — read the account over HTTP. Token
+- **`nbapi <usage|summary|builds|build|raw>`** — read the account over HTTP. Token
   from `$NIXBUILD_API_TOKEN` or `pass show infra/nixbuild/api-token`.
   - `nbapi summary` → counts, billable CPU-seconds, NAR output size.
   - `nbapi usage --from YYYY-MM-DD --to YYYY-MM-DD` → billable CPU over a range.
-  - `nbapi builds --limit N` → recent builds.
+  - `nbapi builds --limit N` → recent builds (id, status, drv path, timing).
+  - `nbapi build <id>` → single build detail including `status_message` (the failure reason).
 - **`nbshell '<cmd>' ['<cmd>' …]`** — run admin-shell commands in one session,
   output cleaned. Useful commands: `usage`, `settings <SETTING> --show`,
-  `settings substituters --add <url>`, `ssh-keys`, `tokens`, `builds`. (`exit`
+  `settings substituters --add <url>`, `ssh-keys`, `tokens`, `builds`,
-  is NOT valid — the session ends on its own.)
+  `builds log <id>` (full build output). (`exit` is NOT valid — the session ends on its own.)
 - **`nb-substituters <list|add-cache|add-key|remove|remove-key|reset>`** — a
   guarded front end for cache settings that catches the path-style-URL mistake
   (see below) before it reaches the shell.
@@ -67,6 +68,27 @@ is the #1 failure mode:
   `trusted-public-keys`. `add-cache <url> <key>` adds both; adding a cache
   without its key only works if the key is already trusted.
 
+# Fetching remote build logs
+
+When a CI build delegates to nixbuild.net, the Nix SSH remote-builder protocol
+does NOT stream build output back to the client — only the exit status propagates.
+The full log lives on nixbuild's side. To retrieve it:
+
+1. **Find the build id** — `nbapi builds --limit 5` lists recent builds with id,
+   status, and drv path. Match by drv or by failure time.
+2. **Get detail + failure reason** — `nbapi build <id>` returns the full record
+   including `status_message` (often enough to diagnose without the full log).
+3. **Get full build output** — `nbshell 'builds log <id>'` streams the complete
+   build log through the admin shell. This is the only way to see the compiler
+   output, failing test, or missing dependency.
+
+Example flow:
+```bash
+nbapi builds --limit 5                 # find the failed build id
+nbapi build <id>                       # check status_message first
+nbshell 'builds log <id>'             # full log if still unclear
+```
+
 # Procedure
 
 1. **Read requests** (usage, storage, "how much build time left", history) →

bin/nbapi

@@ -13,6 +13,7 @@
 #   nbapi usage [--from YYYY-MM-DD] [--to YYYY-MM-DD]   # billable CPU-seconds + count
 #   nbapi summary                                       # aggregated build metrics
 #   nbapi builds [--limit N]                            # recent build history
+#   nbapi build <id>                                    # single build detail + status_message
 #   nbapi raw <path>                                    # GET any API path verbatim
 #
 # Output is JSON (pretty-printed via jq when available).
@@ -77,15 +78,19 @@ builds)
 	done
 	get "/builds?limit=${limit}"
 	;;
+build)
+	[ -n "${1:-}" ] || { echo "nbapi build: need a build id" >&2; exit 2; }
+	get "/builds/$1"
+	;;
 raw)
 	[ -n "${1:-}" ] || { echo "nbapi raw: need a path" >&2; exit 2; }
 	get "$1"
 	;;
 ""|-h|--help|help)
-	sed -n '2,20p' "$0"
+	sed -n '2,21p' "$0"
 	;;
 *)
-	echo "nbapi: unknown command '$cmd' (try: usage, summary, builds, raw)" >&2
+	echo "nbapi: unknown command '$cmd' (try: usage, summary, builds, build, raw)" >&2
 	exit 2
 	;;
 esac

skills/nixbuild-usage/SKILL.md

@@ -67,8 +67,9 @@ nbapi builds --limit 20
 ```
 
 Each entry carries id, status, drv path, timing — useful to spot a runaway or
-repeatedly-failing build burning CPU. For one build's detail: `nbapi raw
+repeatedly-failing build burning CPU. For one build's detail (including
-/builds/<id>`; for a shareable web link: `nbapi raw /builds/<id>/url`.
+`status_message`): `nbapi build <id>`. For the full build log:
+`nbshell 'builds log <id>'`. For a shareable web link: `nbapi raw /builds/<id>/url`.
 
 ## Stored size