Skip to content

Autonomous development for real products. Governed agents build from specs you approve, follow the rules you set, and nothing merges until another agent proves it. Your decisions, judgement and taste are the bar that work must clear. Declare your vision and let agents build it.

docs(api): describe authenticated GUI runner reports [C7,V4]

Corey Olsonaed8f6fff2ab
diff --git a/docs/api.md b/docs/api.md
index 8ae17676..38b42c38 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -583,6 +583,10 @@ The view's own page retains its person channel. The standalone API refuses `POST
`runner add` registers machine-local SSH capacity. Optional `--node` and `--root` select absolute remote paths when Node is outside the SSH login path or runner storage needs a specific location. `runner remove <ssh-host>` removes exactly that registered runner while preserving other machine settings; it refuses an unknown host and lists the registered hosts as the next step. If that runner has active slots, removal is refused until they finish. The default storage root is `~/.pullboard-runner`; runner work shares the remote machine resource pool.
+`runner list --json` and `resources --json` report each runner's optional `gui` capability: `true` means its last authenticated worker report confirmed a logged-in GUI session, `false` means confirmed absent, and `null` (or an absent field from an older client) means unknown. A cached report also carries `guiObservedAt`, the ISO time when this controller recorded it; it does not promise the session remains open. Text output names the GUI state as yes, no, or unknown. An ordinary completed worker job supplies this report. On macOS the worker reads the execution user's `launchctl` GUI domain; unsupported systems, timeouts and ambiguous errors report unknown.
+
+A test file whose header includes `/** @pullboard-test-gui */` explicitly needs a desktop; Chrome's `--headless` arguments do not infer or waive that requirement. The gate and landing-shard routes put that file only on a remote runner whose GUI capability is confirmed `true`; false and unknown runners are excluded and work falls back to a local slot. A no-GUI inherited remote parent also hands its GUI shard to a compatible slot. At actual remote job start, after physical admission and before the project command runs, the worker checks its own GUI session again. A stale positive report cannot bypass this check: `RUNNER_GUI_SESSION_REQUIRED` retains the refused attempt and reroutes the work locally. Direct runner API callers request the same check with `metadata.gui: true`; a completed result exposes the authenticated observation as `executionCapabilities.gui`. GUI availability is separate from browser-slot capacity and from whether Chrome itself succeeds.
+
Runner storage keeps one repository object cache and creates an isolated checkout with complete history per run. A locked inventory handshake transfers only missing committed objects after scanning their blobs, paths and commit metadata, including ancestors. Historical protected paths are checked before connecting. A credential-free HTTPS origin may seed the cache at a locally known published ancestor; caller credentials are never forwarded. Cached object contents are not rescanned on every run.
Each checkout with a committed npm lockfile runs `npm ci`, including lifecycle scripts. Only npm's content cache is shared; installed dependencies and generated files stay in the fresh checkout. Other lock managers are refused. Combined command output and transport diagnostics are bounded at 64 MiB; exceeding that limit refuses the run.