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

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`
-  is NOT valid — the session ends on its own.)
+  `settings substituters --add <url>`, `ssh-keys`, `tokens`, `builds`,
+  `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) →