From 7ed9e115416c3b78b6fc7beaf690f02be58227c5 Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Tue, 27 Oct 2026 22:26:16 -0400 Subject: [PATCH 1/4] =?UTF-8?q?=E2=9C=A8=20dashboard:=20stream=20Job=20pod?= =?UTF-8?q?=20logs=20in=20the=20terminal=20pane=20for=20sandbox.runtime:?= =?UTF-8?q?=20job=20agents?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Agents with sandbox.runtime: job run each kick as a Kubernetes Job in another pod, so there is no tmux session in the hive pod and the ▶ terminal (ttyd) waited forever on "tmux session not created yet". For a job-runtime agent the SPA now routes ▶ terminal to a read-only viewer at /terminal/job/{name} whose /stream endpoint follows the newest Job pod's log through the kubejob launcher's existing in-cluster client and pods/log RBAC, polls while the pod is Pending, prints the container exit code at the end, and between kicks (completed Jobs are deleted at once) shows the last persisted sandbox transcript — which now ends with an "exit code: N" line — or a clear "no sandbox run yet" state. - crux/kubejob: LatestPod / PodStatus / StreamLog over the plain HTTP client, plus LineFilterWriter. - crux/sandbox: shared naming helpers (LaunchName, WorkspaceDir, LatestTranscript, TranscriptExitCode) used by the executor and the dashboard so neither hard-codes the other's layout. - pkg/dashboard: /terminal/job routes under the existing /terminal handoff + role check; agent status gains sandboxRuntime. - RBAC unchanged: sandbox-job-rbac.yaml already grants pods/log. Fixes #14798 Signed-off-by: Andrew Anderson --- .../added-14798-job-runtime-terminal.md | 1 + src/crux/agent/manager_sandbox.go | 6 +- src/crux/agent/sandbox_executor.go | 33 +- src/crux/agent/sandbox_executor_test.go | 19 + src/crux/agent/sandbox_workspace.go | 2 +- src/crux/kubejob/podlog.go | 291 +++++++++++ src/crux/kubejob/podlog_test.go | 362 +++++++++++++ src/crux/sandbox/naming.go | 141 ++++++ src/crux/sandbox/naming_test.go | 92 ++++ src/docs/api-reference.md | 2 + src/docs/sandbox-isolation.md | 4 +- .../testutil/dashboard_import_allowlist.txt | 2 + src/pkg/dashboard/job_terminal.go | 389 ++++++++++++++ src/pkg/dashboard/job_terminal_test.go | 475 ++++++++++++++++++ src/pkg/dashboard/server.go | 8 + src/pkg/dashboard/static/index.html | 25 +- src/pkg/dashboard/status_builder.go | 12 + src/pkg/dashboard/terminal_proxy.go | 4 + 18 files changed, 1833 insertions(+), 35 deletions(-) create mode 100644 src/changelog.d/added-14798-job-runtime-terminal.md create mode 100644 src/crux/kubejob/podlog.go create mode 100644 src/crux/kubejob/podlog_test.go create mode 100644 src/crux/sandbox/naming.go create mode 100644 src/crux/sandbox/naming_test.go create mode 100644 src/pkg/dashboard/job_terminal.go create mode 100644 src/pkg/dashboard/job_terminal_test.go diff --git a/src/changelog.d/added-14798-job-runtime-terminal.md b/src/changelog.d/added-14798-job-runtime-terminal.md new file mode 100644 index 0000000000..5c2702dae2 --- /dev/null +++ b/src/changelog.d/added-14798-job-runtime-terminal.md @@ -0,0 +1 @@ +- The dashboard's **▶ terminal** now works for agents with `sandbox.runtime: job` ([#14798](https://github.com/hivecommons/hive/issues/14798)). Those kicks run as a Kubernetes Job in another pod, so there was no tmux session to attach and the pane waited forever. For a job-runtime agent the link now opens a read-only viewer at `/terminal/job/` that streams the newest Job pod's log through the launcher's existing in-cluster client and `pods/log` RBAC: it follows the pod while the kick runs (waiting while it is `Pending`), prints the container exit code when it ends, and between kicks shows the last run's persisted sandbox transcript — which now ends with an `exit code: N` line — or a clear "no sandbox run yet" state. Podman-sandboxed and tmux agents are unchanged. diff --git a/src/crux/agent/manager_sandbox.go b/src/crux/agent/manager_sandbox.go index 5272cc1e74..fdde479d21 100644 --- a/src/crux/agent/manager_sandbox.go +++ b/src/crux/agent/manager_sandbox.go @@ -4,7 +4,6 @@ import ( "context" "errors" "fmt" - "path/filepath" "strings" "time" @@ -178,10 +177,7 @@ func (m *Manager) startSandboxKickLocked(agent *AgentProcess, message string) er } func (m *Manager) sandboxWorkspaceDirLocked() string { - if strings.TrimSpace(m.sandboxConfig.WorkspaceDir) != "" { - return m.sandboxConfig.WorkspaceDir - } - return filepath.Join(m.workDir, "sandbox") + return sandbox.WorkspaceRoot(m.sandboxConfig.WorkspaceDir, m.workDir) } func (m *Manager) tieredSandboxMinterLocked(tier string) pushbroker.TokenMinter { diff --git a/src/crux/agent/sandbox_executor.go b/src/crux/agent/sandbox_executor.go index a0beead391..946f33d202 100644 --- a/src/crux/agent/sandbox_executor.go +++ b/src/crux/agent/sandbox_executor.go @@ -9,6 +9,7 @@ import ( "os" "os/exec" "path/filepath" + "strconv" "strings" "time" @@ -24,7 +25,7 @@ const ( DefaultSandboxKickTimeout = 45 * time.Minute defaultSandboxNetworkMode = sandbox.NetworkModeRestricted sandboxPromptRelPath = ".hive/kick-prompt.txt" - sandboxTranscriptRelPath = ".hive/sandbox-transcript.log" + sandboxTranscriptRelPath = sandbox.TranscriptRelPath // The sandboxed agent may leave the PR title and body it wants in the // workspace; the executor (which alone can open the PR) picks them up. sandboxPRTitleRelPath = ".hive/pr-title.txt" @@ -197,7 +198,7 @@ func (e *SandboxExecutor) Run(ctx context.Context, spec SandboxKickSpec) (Sandbo defer cancel() sres, runErr := e.launcher().Run(runCtx, sandbox.LaunchSpec{ Image: spec.Image, - Name: "hive-" + sanitizeBranchPart(spec.Agent) + "-sandbox", + Name: sandbox.LaunchName(spec.Agent), Workspace: workspace, WorkspaceMount: sandbox.DefaultWorkspaceMount, WorkDir: sandbox.DefaultWorkspaceMount, @@ -426,6 +427,11 @@ func writeTranscript(path string, res sandbox.Result) error { b.WriteString(res.Stdout) b.WriteString("\n\nstderr:\n") b.WriteString(res.Stderr) + // Trailing status line, read back by the dashboard's job-runtime + // terminal pane once the Job pod is gone (hivecommons/hive#14798). + b.WriteString("\n\n" + sandbox.TranscriptExitPrefix) + b.WriteString(strconv.Itoa(res.ExitCode)) + b.WriteString("\n") return os.WriteFile(path, []byte(b.String()), 0o660) } @@ -636,28 +642,7 @@ func (e *SandboxExecutor) branchName(agentName string) string { return "hive/" + sanitizeBranchPart(agentName) + "/" + e.now().Format("20060102150405") } -func sanitizeBranchPart(s string) string { - s = strings.TrimSpace(strings.ToLower(s)) - var b strings.Builder - lastDash := false - for _, r := range s { - ok := (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') - if ok { - b.WriteRune(r) - lastDash = false - continue - } - if !lastDash { - b.WriteByte('-') - lastDash = true - } - } - out := strings.Trim(b.String(), "-") - if out == "" { - return "agent" - } - return out -} +func sanitizeBranchPart(s string) string { return sandbox.AgentSlug(s) } func shellQuote(s string) string { return "'" + strings.ReplaceAll(s, "'", "'\"'\"'") + "'" diff --git a/src/crux/agent/sandbox_executor_test.go b/src/crux/agent/sandbox_executor_test.go index ce2f41db90..5c9fcec8d8 100644 --- a/src/crux/agent/sandbox_executor_test.go +++ b/src/crux/agent/sandbox_executor_test.go @@ -160,6 +160,25 @@ func TestSandboxExecutorWorkspacePrepSanitizesCredentials(t *testing.T) { if res.Workspace == "" || res.Report == nil || res.TranscriptPath == "" { t.Fatalf("result missing collected artifacts: %+v", res) } + // The workspace and transcript follow the shared sandbox naming so the + // dashboard's job-runtime terminal pane can find them by agent name + // (hivecommons/hive#14798), and the transcript ends with the exit code. + if want := sandbox.WorkspaceDir(root, "scanner", time.Unix(1, 0).UnixNano()); res.Workspace != want { + t.Fatalf("workspace = %q, want %q", res.Workspace, want) + } + if latest, ok := sandbox.LatestTranscript(root, "scanner"); !ok || latest != res.TranscriptPath { + t.Fatalf("LatestTranscript = %q, %v; want %q", latest, ok, res.TranscriptPath) + } + transcript, err := os.ReadFile(res.TranscriptPath) + if err != nil { + t.Fatal(err) + } + if code, ok := sandbox.TranscriptExitCode(string(transcript)); !ok || code != 0 { + t.Fatalf("transcript exit code = %d, %v; transcript:\n%s", code, ok, transcript) + } + if !strings.HasPrefix(string(transcript), "stdout:\ndone\n") { + t.Fatalf("transcript body changed shape:\n%s", transcript) + } for _, env := range runner.envs { for _, pair := range env { if strings.HasPrefix(pair, "GITHUB_TOKEN=") { diff --git a/src/crux/agent/sandbox_workspace.go b/src/crux/agent/sandbox_workspace.go index 2665a4da16..43620b2898 100644 --- a/src/crux/agent/sandbox_workspace.go +++ b/src/crux/agent/sandbox_workspace.go @@ -32,7 +32,7 @@ func (e *SandboxExecutor) prepareWorkspace(ctx context.Context, spec *SandboxKic if strings.TrimSpace(spec.Stage) != "" { return e.prepareRunStageWorkspace(ctx, spec) } - workspace := filepath.Join(spec.WorkspaceDir, sanitizeBranchPart(spec.Agent)+"-"+fmt.Sprint(e.now().UnixNano())) + workspace := sandbox.WorkspaceDir(spec.WorkspaceDir, spec.Agent, e.now().UnixNano()) repoURL := fmt.Sprintf("https://github.com/%s/%s.git", spec.Org, spec.Repo) authArgs, cleanupAuth, err := e.cloneAuthArgs(ctx, spec.Org+"/"+spec.Repo, spec.WorkspaceDir) if err != nil { diff --git a/src/crux/kubejob/podlog.go b/src/crux/kubejob/podlog.go new file mode 100644 index 0000000000..130f20565a --- /dev/null +++ b/src/crux/kubejob/podlog.go @@ -0,0 +1,291 @@ +package kubejob + +import ( + "bufio" + "context" + "encoding/json" + "errors" + "fmt" + "io" + "net/http" + "net/url" + "strings" + "time" +) + +// Read-only observation of a kick's pod, for the dashboard's terminal pane +// (hivecommons/hive#14798). A sandbox.runtime: job agent has no tmux session +// in the hive pod, so the only thing an operator can watch is the Job pod's +// log. These helpers reuse the launcher's in-cluster client, token and +// namespace discovery, and need nothing beyond the pods / pods/log get+list +// the launcher already requires (deploy/k8s/sandbox-job-rbac.yaml). They +// never create, delete or exec. + +// Pod phases as the API reports them in status.phase. +const ( + PodPhasePending = "Pending" + PodPhaseRunning = "Running" + PodPhaseSucceeded = "Succeeded" + PodPhaseFailed = "Failed" +) + +// ExitCodeUnknown is reported for a container that has not terminated yet +// or whose status could not be read. +const ExitCodeUnknown = exitCodeUnknown + +// PodInfo is the subset of a kick pod's status the terminal pane shows. +type PodInfo struct { + Name string + Job string + Phase string + Created time.Time + // Terminated is true once the kick container has exited; ExitCode is + // then its exit code, else ExitCodeUnknown. + Terminated bool + ExitCode int + // Waiting carries the kick container's waiting reason (ImagePullBackOff, + // ContainerCreating, …) while it has not started, else "". + Waiting string +} + +// Finished reports whether the pod can produce no more log output. +func (p PodInfo) Finished() bool { + return p.Terminated || p.Phase == PodPhaseSucceeded || p.Phase == PodPhaseFailed +} + +// AgentLabelValue returns the hive.kubestellar.io/agent label the launcher +// stamps on a Job and its pod for the given LaunchSpec.Name. The sandbox +// executor names its launches "hive--sandbox"; callers that only know +// the agent name build the launch name the same way and pass it here. +func AgentLabelValue(launchName string) string { + return sanitizeLabel(launchName) +} + +// AgentLabelSelector is the selector that finds every pod this launcher +// created for a launch name — the managed-by label keeps out any other +// workload an operator may have labelled with the same agent key. +func AgentLabelSelector(launchName string) string { + return fmt.Sprintf("%s=%s,%s=%s", managedByLabel, managedByValue, agentLabel, AgentLabelValue(launchName)) +} + +// LatestPod returns the most recently created pod the launcher made for +// launchName, or ok=false when there is none in the namespace. A successful +// Job is deleted by Run as soon as it completes, so "none" is the normal +// state between kicks; a failed Job's pod stays until its TTL. +func (l *Launcher) LatestPod(ctx context.Context, launchName string) (PodInfo, bool, error) { + ns, err := l.namespace() + if err != nil { + return PodInfo{}, false, err + } + path := fmt.Sprintf("/api/v1/namespaces/%s/pods?labelSelector=%s", ns, url.QueryEscape(AgentLabelSelector(launchName))) + raw, err := l.do(ctx, http.MethodGet, path, nil) + if err != nil { + return PodInfo{}, false, err + } + var list struct { + Items []json.RawMessage `json:"items"` + } + if err := json.Unmarshal(raw, &list); err != nil { + return PodInfo{}, false, fmt.Errorf("kubejob: decoding pod list: %w", err) + } + var latest PodInfo + found := false + for _, item := range list.Items { + info, err := parsePod(item) + if err != nil { + continue + } + if !found || info.Created.After(latest.Created) { + latest, found = info, true + } + } + return latest, found, nil +} + +// PodStatus re-reads one pod, typically after a followed log stream has +// ended, to learn the kick container's exit code. +func (l *Launcher) PodStatus(ctx context.Context, pod string) (PodInfo, error) { + ns, err := l.namespace() + if err != nil { + return PodInfo{}, err + } + raw, err := l.do(ctx, http.MethodGet, fmt.Sprintf("/api/v1/namespaces/%s/pods/%s", ns, url.PathEscape(pod)), nil) + if err != nil { + return PodInfo{}, err + } + info, err := parsePod(raw) + if err != nil { + return PodInfo{}, fmt.Errorf("kubejob: decoding pod: %w", err) + } + return info, nil +} + +// parsePod reads the fields PodInfo needs off a core/v1 Pod object. +func parsePod(raw []byte) (PodInfo, error) { + var p struct { + Metadata struct { + Name string `json:"name"` + Labels map[string]string `json:"labels"` + CreationTimestamp string `json:"creationTimestamp"` + } `json:"metadata"` + Status struct { + Phase string `json:"phase"` + ContainerStatuses []struct { + Name string `json:"name"` + State map[string]struct { + ExitCode int `json:"exitCode"` + Reason string `json:"reason"` + } `json:"state"` + } `json:"containerStatuses"` + } `json:"status"` + } + if err := json.Unmarshal(raw, &p); err != nil { + return PodInfo{}, err + } + if p.Metadata.Name == "" { + return PodInfo{}, errors.New("pod has no name") + } + info := PodInfo{ + Name: p.Metadata.Name, + Job: p.Metadata.Labels[jobLabelKey], + Phase: p.Status.Phase, + ExitCode: ExitCodeUnknown, + } + if ts, err := time.Parse(time.RFC3339, p.Metadata.CreationTimestamp); err == nil { + info.Created = ts + } + for _, cs := range p.Status.ContainerStatuses { + if cs.Name != containerName { + continue + } + if term, ok := cs.State[stateTerminated]; ok { + info.Terminated = true + info.ExitCode = term.ExitCode + } + if wait, ok := cs.State["waiting"]; ok { + info.Waiting = wait.Reason + } + } + return info, nil +} + +// StreamLog copies the kick container's log to w as the API server sends it. +// With follow the connection stays open until the container exits or ctx +// ends; without it the log read so far is returned and the call ends. Output +// is forwarded a line at a time so the caller can filter it (the dashboard +// scrubs credentials before anything reaches a browser). Bounded by ctx, not +// by the launcher's per-request timeout: a followed stream is expected to +// outlive any single API call. +func (l *Launcher) StreamLog(ctx context.Context, pod string, follow bool, w io.Writer) error { + ns, err := l.namespace() + if err != nil { + return err + } + client, err := l.client() + if err != nil { + return err + } + server := l.APIServer + if server == "" { + server = DefaultAPIServer + } + q := url.Values{} + q.Set("container", containerName) + q.Set("limitBytes", fmt.Sprint(maxLogBytes)) + if follow { + q.Set("follow", "true") + } + path := fmt.Sprintf("/api/v1/namespaces/%s/pods/%s/log?%s", ns, url.PathEscape(pod), q.Encode()) + req, err := http.NewRequestWithContext(ctx, http.MethodGet, server+path, nil) + if err != nil { + return err + } + if tok := l.token(); tok != "" { + req.Header.Set("Authorization", "Bearer "+tok) + } + resp, err := client.Do(req) + if err != nil { + return err + } + defer func() { _ = resp.Body.Close() }() + if resp.StatusCode < 200 || resp.StatusCode >= 300 { + body, _ := io.ReadAll(io.LimitReader(resp.Body, 4096)) + return fmt.Errorf("GET %s: HTTP %d: %s", path, resp.StatusCode, apiMessage(body)) + } + rd := bufio.NewReader(resp.Body) + for { + line, err := rd.ReadString('\n') + if line != "" { + if _, werr := io.WriteString(w, line); werr != nil { + return werr + } + } + if err != nil { + if errors.Is(err, io.EOF) { + return nil + } + if ctx.Err() != nil { + return ctx.Err() + } + return err + } + } +} + +// FlushWriter is implemented by writers that can push buffered output to +// their consumer; StreamLog's callers use it to deliver each line as it +// arrives rather than when the response ends. +type FlushWriter interface { + io.Writer + Flush() +} + +// LineFilterWriter applies fn to each complete line written through it and +// flushes the destination after every line, so a followed log reaches a +// browser as it is produced. Partial trailing lines are buffered until their +// newline arrives (or Close is called). +type LineFilterWriter struct { + Dst io.Writer + Fn func(string) string + buf strings.Builder +} + +func (w *LineFilterWriter) Write(p []byte) (int, error) { + w.buf.Write(p) + for { + s := w.buf.String() + i := strings.IndexByte(s, '\n') + if i < 0 { + return len(p), nil + } + line := s[:i+1] + w.buf.Reset() + w.buf.WriteString(s[i+1:]) + if err := w.emit(line); err != nil { + return 0, err + } + } +} + +// Close writes any buffered partial line. +func (w *LineFilterWriter) Close() error { + if w.buf.Len() == 0 { + return nil + } + line := w.buf.String() + w.buf.Reset() + return w.emit(line) +} + +func (w *LineFilterWriter) emit(line string) error { + if w.Fn != nil { + line = w.Fn(line) + } + if _, err := io.WriteString(w.Dst, line); err != nil { + return err + } + if f, ok := w.Dst.(FlushWriter); ok { + f.Flush() + } + return nil +} diff --git a/src/crux/kubejob/podlog_test.go b/src/crux/kubejob/podlog_test.go new file mode 100644 index 0000000000..8e58b118f6 --- /dev/null +++ b/src/crux/kubejob/podlog_test.go @@ -0,0 +1,362 @@ +package kubejob + +import ( + "bytes" + "context" + "errors" + "io" + "net/http" + "net/http/httptest" + "net/url" + "strings" + "sync" + "testing" + "time" +) + +// podLogAPI is a fake API server for the read-only pod observation path: a +// scripted pod list, one pod object, and a log that is delivered in chunks +// (each flushed) so a followed stream can be observed line by line. +type podLogAPI struct { + mu sync.Mutex + pods string // JSON list body + pod string // JSON pod body + logChunks []string + logStatus int + selectors []string + followed []bool + // release, when non-nil, gates the final log chunk so a test can observe + // a followed stream mid-flight without sleeping. + release chan struct{} +} + +func (f *podLogAPI) handler(t *testing.T) http.HandlerFunc { + return func(w http.ResponseWriter, r *http.Request) { + switch { + case r.Method == http.MethodGet && strings.HasSuffix(r.URL.Path, "/pods"): + f.mu.Lock() + f.selectors = append(f.selectors, r.URL.Query().Get("labelSelector")) + body := f.pods + f.mu.Unlock() + _, _ = w.Write([]byte(body)) + case r.Method == http.MethodGet && strings.HasSuffix(r.URL.Path, "/log"): + f.mu.Lock() + f.followed = append(f.followed, r.URL.Query().Get("follow") == "true") + chunks, status, release := f.logChunks, f.logStatus, f.release + f.mu.Unlock() + if status > 0 { + w.WriteHeader(status) + _, _ = w.Write([]byte(`{"kind":"Status","message":"pods \"x\" is forbidden"}`)) + return + } + fl, _ := w.(http.Flusher) + for i, c := range chunks { + if release != nil && i == len(chunks)-1 { + select { + case <-release: + case <-r.Context().Done(): + return + } + } + _, _ = w.Write([]byte(c)) + if fl != nil { + fl.Flush() + } + } + case r.Method == http.MethodGet && strings.Contains(r.URL.Path, "/pods/"): + f.mu.Lock() + body := f.pod + f.mu.Unlock() + _, _ = w.Write([]byte(body)) + default: + t.Errorf("unexpected request %s %s", r.Method, r.URL) + w.WriteHeader(http.StatusNotFound) + } + } +} + +const ( + podRunning = `{"metadata":{"name":"hive-kick-deps-1700000000-abcde","labels":{"job-name":"hive-kick-deps-1700000000"},"creationTimestamp":"2023-11-14T22:13:20Z"},"status":{"phase":"Running","containerStatuses":[{"name":"kick","state":{"running":{}}}]}}` + podFailed = `{"metadata":{"name":"hive-kick-deps-1700000900-zzzzz","labels":{"job-name":"hive-kick-deps-1700000900"},"creationTimestamp":"2023-11-14T22:28:20Z"},"status":{"phase":"Failed","containerStatuses":[{"name":"kick","state":{"terminated":{"exitCode":3}}}]}}` + podWaiting = `{"metadata":{"name":"hive-kick-deps-1700001000-wwwww","labels":{"job-name":"hive-kick-deps-1700001000"},"creationTimestamp":"2023-11-14T22:30:00Z"},"status":{"phase":"Pending","containerStatuses":[{"name":"kick","state":{"waiting":{"reason":"ImagePullBackOff"}}}]}}` +) + +func newPodLogLauncher(srv *httptest.Server) *Launcher { + return newLauncher(srv, Options{}) +} + +func TestAgentLabelSelectorMatchesManifestLabels(t *testing.T) { + // The selector must find exactly what manifest() stamps on the pod, or + // the terminal pane will never see a running kick. + l := &Launcher{Options: Options{WorkspaceClaim: "hive-data"}} + m := l.manifest("hive", "hive-kick-deps-1", "sandbox/deps-1", specFor("/data/sandbox/deps-1")) + tmpl := m["spec"].(map[string]any)["template"].(map[string]any) + labels := tmpl["metadata"].(map[string]any)["labels"].(map[string]string) + sel := AgentLabelSelector("hive-deps-sandbox") + for _, kv := range strings.Split(sel, ",") { + k, v, _ := strings.Cut(kv, "=") + if labels[k] != v { + t.Fatalf("selector %q wants %s=%s but the manifest stamps %s=%q", sel, k, v, k, labels[k]) + } + } + if got := AgentLabelValue("Hive-Deps_Quality-sandbox"); got != "hive-deps-quality-sandbox" { + t.Fatalf("AgentLabelValue = %q", got) + } +} + +func TestLatestPodPicksNewestAndEscapesSelector(t *testing.T) { + api := &podLogAPI{pods: `{"items":[` + podRunning + `,` + podFailed + `,` + podWaiting + `]}`} + srv := httptest.NewServer(api.handler(t)) + defer srv.Close() + l := newPodLogLauncher(srv) + + info, ok, err := l.LatestPod(context.Background(), "hive-deps-sandbox") + if err != nil || !ok { + t.Fatalf("LatestPod: ok=%v err=%v", ok, err) + } + if info.Name != "hive-kick-deps-1700001000-wwwww" || info.Phase != PodPhasePending || info.Waiting != "ImagePullBackOff" { + t.Fatalf("LatestPod picked %+v, want the newest (waiting) pod", info) + } + if info.Job != "hive-kick-deps-1700001000" || info.Terminated || info.ExitCode != ExitCodeUnknown || info.Finished() { + t.Fatalf("unexpected pod info %+v", info) + } + api.mu.Lock() + sel := api.selectors[0] + api.mu.Unlock() + if sel != AgentLabelSelector("hive-deps-sandbox") { + t.Fatalf("selector not round-tripped through query escaping: %q", sel) + } + if _, err := url.ParseQuery("labelSelector=" + url.QueryEscape(sel)); err != nil { + t.Fatalf("selector not URL-safe: %v", err) + } +} + +func TestLatestPodNoneAndErrors(t *testing.T) { + api := &podLogAPI{pods: `{"items":[]}`} + srv := httptest.NewServer(api.handler(t)) + defer srv.Close() + l := newPodLogLauncher(srv) + if _, ok, err := l.LatestPod(context.Background(), "hive-deps-sandbox"); ok || err != nil { + t.Fatalf("empty list: ok=%v err=%v", ok, err) + } + + api.mu.Lock() + api.pods = `not json` + api.mu.Unlock() + if _, _, err := l.LatestPod(context.Background(), "hive-deps-sandbox"); err == nil { + t.Fatal("malformed list must be an error, not an empty pane") + } + + forbidden := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusForbidden) + _, _ = w.Write([]byte(`{"kind":"Status","message":"pods is forbidden: missing pods list"}`)) + })) + defer forbidden.Close() + if _, _, err := newPodLogLauncher(forbidden).LatestPod(context.Background(), "x"); err == nil || !strings.Contains(err.Error(), "missing pods list") { + t.Fatalf("RBAC failure must carry the API message, got %v", err) + } + + noNS := &Launcher{APIServer: srv.URL, HTTPClient: srv.Client(), NamespacePath: "/nonexistent/ns"} + if _, _, err := noNS.LatestPod(context.Background(), "x"); err == nil { + t.Fatal("missing namespace must be an error") + } +} + +func TestPodStatusReadsExitCode(t *testing.T) { + api := &podLogAPI{pod: podFailed} + srv := httptest.NewServer(api.handler(t)) + defer srv.Close() + info, err := newPodLogLauncher(srv).PodStatus(context.Background(), "hive-kick-deps-1700000900-zzzzz") + if err != nil { + t.Fatal(err) + } + if !info.Terminated || info.ExitCode != 3 || !info.Finished() || info.Phase != PodPhaseFailed { + t.Fatalf("PodStatus = %+v", info) + } + api.mu.Lock() + api.pod = `{}` + api.mu.Unlock() + if _, err := newPodLogLauncher(srv).PodStatus(context.Background(), "x"); err == nil { + t.Fatal("nameless pod must be an error") + } +} + +func TestStreamLogWithoutFollowReturnsAtEOF(t *testing.T) { + api := &podLogAPI{logChunks: []string{"line one\n", "line two\n", "tail without newline"}} + srv := httptest.NewServer(api.handler(t)) + defer srv.Close() + var out bytes.Buffer + if err := newPodLogLauncher(srv).StreamLog(context.Background(), "p", false, &out); err != nil { + t.Fatal(err) + } + if out.String() != "line one\nline two\ntail without newline" { + t.Fatalf("stream = %q", out.String()) + } + api.mu.Lock() + followed := api.followed + api.mu.Unlock() + if len(followed) != 1 || followed[0] { + t.Fatalf("follow must not be requested, got %v", followed) + } +} + +// lineRecorder is a FlushWriter that reports each flush, so a test can wait +// for a specific line to have been delivered instead of sleeping. +type lineRecorder struct { + mu sync.Mutex + buf bytes.Buffer + flushed chan string +} + +func (r *lineRecorder) Write(p []byte) (int, error) { + r.mu.Lock() + defer r.mu.Unlock() + return r.buf.Write(p) +} + +func (r *lineRecorder) Flush() { + r.mu.Lock() + s := r.buf.String() + r.mu.Unlock() + r.flushed <- s +} + +func TestStreamLogFollowDeliversLinesAsTheyArrive(t *testing.T) { + release := make(chan struct{}) + api := &podLogAPI{logChunks: []string{"starting\n", "partial", " line\n", "done\n"}, release: release} + srv := httptest.NewServer(api.handler(t)) + defer srv.Close() + + rec := &lineRecorder{flushed: make(chan string, 16)} + lw := &LineFilterWriter{Dst: rec, Fn: strings.ToUpper} + errc := make(chan error, 1) + go func() { + err := newPodLogLauncher(srv).StreamLog(context.Background(), "p", true, lw) + errc <- errors.Join(err, lw.Close()) + }() + + // Two complete lines are flushed while the server still holds the last + // chunk back: the stream is live, not buffered to the end. + wantSeq := []string{"STARTING\n", "STARTING\nPARTIAL LINE\n"} + for _, want := range wantSeq { + select { + case got := <-rec.flushed: + if got != want { + t.Fatalf("flushed %q, want %q", got, want) + } + case <-time.After(10 * time.Second): + t.Fatal("timed out waiting for a flushed line") + } + } + close(release) + if err := <-errc; err != nil { + t.Fatal(err) + } + rec.mu.Lock() + final := rec.buf.String() + rec.mu.Unlock() + if final != "STARTING\nPARTIAL LINE\nDONE\n" { + t.Fatalf("final = %q", final) + } + api.mu.Lock() + followed := api.followed + api.mu.Unlock() + if len(followed) != 1 || !followed[0] { + t.Fatalf("follow=true must be requested, got %v", followed) + } +} + +func TestStreamLogContextCancelEndsFollow(t *testing.T) { + release := make(chan struct{}) + defer close(release) + api := &podLogAPI{logChunks: []string{"starting\n", "never\n"}, release: release} + srv := httptest.NewServer(api.handler(t)) + defer srv.Close() + + rec := &lineRecorder{flushed: make(chan string, 16)} + ctx, cancel := context.WithCancel(context.Background()) + errc := make(chan error, 1) + go func() { + errc <- newPodLogLauncher(srv).StreamLog(ctx, "p", true, &LineFilterWriter{Dst: rec}) + }() + select { + case <-rec.flushed: + case <-time.After(10 * time.Second): + t.Fatal("first line never arrived") + } + cancel() + select { + case err := <-errc: + if !errors.Is(err, context.Canceled) { + t.Fatalf("err = %v, want context.Canceled", err) + } + case <-time.After(10 * time.Second): + t.Fatal("StreamLog did not return after cancel") + } +} + +func TestStreamLogErrors(t *testing.T) { + api := &podLogAPI{logStatus: http.StatusForbidden} + srv := httptest.NewServer(api.handler(t)) + defer srv.Close() + err := newPodLogLauncher(srv).StreamLog(context.Background(), "p", false, io.Discard) + if err == nil || !strings.Contains(err.Error(), "HTTP 403") || !strings.Contains(err.Error(), "forbidden") { + t.Fatalf("err = %v", err) + } + + noNS := &Launcher{APIServer: srv.URL, HTTPClient: srv.Client(), NamespacePath: "/nonexistent/ns"} + if err := noNS.StreamLog(context.Background(), "p", false, io.Discard); err == nil { + t.Fatal("missing namespace must be an error") + } + noCA := &Launcher{APIServer: srv.URL, Namespace: "hive", CAPath: "/nonexistent/ca.crt"} + if err := noCA.StreamLog(context.Background(), "p", false, io.Discard); err == nil { + t.Fatal("missing CA must be an error") + } + + failing := &LineFilterWriter{Dst: failWriter{}} + api2 := &podLogAPI{logChunks: []string{"x\n"}} + srv2 := httptest.NewServer(api2.handler(t)) + defer srv2.Close() + if err := newPodLogLauncher(srv2).StreamLog(context.Background(), "p", false, failing); err == nil { + t.Fatal("a failing destination must end the stream with an error") + } +} + +type failWriter struct{} + +func (failWriter) Write([]byte) (int, error) { return 0, errors.New("closed") } + +func TestLineFilterWriterBuffersPartialLines(t *testing.T) { + var out bytes.Buffer + w := &LineFilterWriter{Dst: &out, Fn: func(s string) string { return strings.ReplaceAll(s, "secret", "***") }} + for _, chunk := range []string{"sec", "ret one\nsec", "ret two"} { + if _, err := w.Write([]byte(chunk)); err != nil { + t.Fatal(err) + } + } + if out.String() != "*** one\n" { + t.Fatalf("before Close = %q", out.String()) + } + if err := w.Close(); err != nil { + t.Fatal(err) + } + if out.String() != "*** one\n*** two" { + t.Fatalf("after Close = %q", out.String()) + } + if err := w.Close(); err != nil { + t.Fatal("second Close must be a no-op") + } +} + +func TestParsePodDefaults(t *testing.T) { + info, err := parsePod([]byte(`{"metadata":{"name":"p"},"status":{"phase":"Succeeded"}}`)) + if err != nil { + t.Fatal(err) + } + if info.Terminated || info.ExitCode != ExitCodeUnknown || !info.Finished() || !info.Created.IsZero() { + t.Fatalf("info = %+v", info) + } + if _, err := parsePod([]byte(`nope`)); err == nil { + t.Fatal("malformed pod must be an error") + } +} diff --git a/src/crux/sandbox/naming.go b/src/crux/sandbox/naming.go new file mode 100644 index 0000000000..e7b9a8dd2f --- /dev/null +++ b/src/crux/sandbox/naming.go @@ -0,0 +1,141 @@ +package sandbox + +import ( + "os" + "path/filepath" + "sort" + "strconv" + "strings" +) + +// Shared naming between the sandbox kick executor (crux/agent) and the +// dashboard's job-runtime terminal pane (pkg/dashboard), which must find a +// kick's Job pod and persisted transcript knowing only the agent's name +// (hivecommons/hive#14798). The dashboard deliberately does not import +// crux/agent, so the conventions live here where both can reach them. + +const ( + // TranscriptRelPath is where, relative to a kick's workspace, the + // executor persists the scrubbed stdout/stderr of the run. + TranscriptRelPath = ".hive/sandbox-transcript.log" + // TranscriptExitPrefix opens the transcript's trailing "exit code: N" + // line, written after stdout and stderr. + TranscriptExitPrefix = "exit code: " + + // DefaultWorkDir is the agent manager's work directory when HIVE_WORK_DIR + // is unset; the sandbox workspace root defaults to its "sandbox" child. + DefaultWorkDir = "/data/agents" + workspaceRootSubdir = "sandbox" + launchNamePrefix = "hive-" + launchNameSuffix = "-sandbox" + fallbackSlug = "agent" +) + +// AgentSlug is the lower-case [a-z0-9-] form of an agent name used in launch +// names, Job labels, branch names and workspace directory names. +func AgentSlug(agent string) string { + s := strings.TrimSpace(strings.ToLower(agent)) + var b strings.Builder + lastDash := false + for _, r := range s { + ok := (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') + if ok { + b.WriteRune(r) + lastDash = false + continue + } + if !lastDash { + b.WriteByte('-') + lastDash = true + } + } + out := strings.Trim(b.String(), "-") + if out == "" { + return fallbackSlug + } + return out +} + +// LaunchName is the LaunchSpec.Name the executor uses for an agent's kicks: +// hive--sandbox. The kubejob launcher derives its Job name and agent +// label from it. +func LaunchName(agent string) string { + return launchNamePrefix + AgentSlug(agent) + launchNameSuffix +} + +// WorkspaceRoot resolves the directory kick workspaces are created under: +// the configured agent_sandbox.workspace_dir when set, else /sandbox, +// with workDir itself defaulting to DefaultWorkDir. The agent manager and the +// dashboard both resolve it here so they always agree on where a kick's +// transcript lives. +func WorkspaceRoot(configured, workDir string) string { + if strings.TrimSpace(configured) != "" { + return configured + } + if strings.TrimSpace(workDir) == "" { + workDir = DefaultWorkDir + } + return filepath.Join(workDir, workspaceRootSubdir) +} + +// WorkspaceDir is the per-kick workspace directory the executor creates +// under root: /-. +func WorkspaceDir(root, agent string, unixNano int64) string { + return filepath.Join(root, AgentSlug(agent)+"-"+strconv.FormatInt(unixNano, 10)) +} + +// LatestTranscript returns the newest persisted transcript for agent under +// the workspace root, by file modification time, or ok=false when the agent +// has no run with a transcript yet. +func LatestTranscript(root, agent string) (path string, ok bool) { + slug := AgentSlug(agent) + matches, err := filepath.Glob(filepath.Join(root, slug+"-*", filepath.FromSlash(TranscriptRelPath))) + if err != nil || len(matches) == 0 { + return "", false + } + type cand struct { + path string + mod int64 + } + cands := make([]cand, 0, len(matches)) + for _, m := range matches { + // "deps-*" also matches "deps-quality-": only a purely numeric + // suffix is one of THIS agent's kick directories. + dir := filepath.Base(filepath.Dir(filepath.Dir(m))) + if _, err := strconv.ParseInt(strings.TrimPrefix(dir, slug+"-"), 10, 64); err != nil { + continue + } + st, err := os.Stat(m) + if err != nil || st.IsDir() { + continue + } + cands = append(cands, cand{m, st.ModTime().UnixNano()}) + } + if len(cands) == 0 { + return "", false + } + sort.Slice(cands, func(i, j int) bool { + if cands[i].mod != cands[j].mod { + return cands[i].mod > cands[j].mod + } + return cands[i].path > cands[j].path + }) + return cands[0].path, true +} + +// TranscriptExitCode reads the trailing "exit code: N" line a transcript +// ends with. ok is false for transcripts written before the line existed or +// otherwise lacking it. +func TranscriptExitCode(transcript string) (code int, ok bool) { + trimmed := strings.TrimRight(transcript, "\n") + i := strings.LastIndexByte(trimmed, '\n') + last := trimmed[i+1:] + if !strings.HasPrefix(last, TranscriptExitPrefix) { + return 0, false + } + n, err := strconv.Atoi(strings.TrimSpace(strings.TrimPrefix(last, TranscriptExitPrefix))) + if err != nil { + return 0, false + } + return n, true +} diff --git a/src/crux/sandbox/naming_test.go b/src/crux/sandbox/naming_test.go new file mode 100644 index 0000000000..ab7e246fc0 --- /dev/null +++ b/src/crux/sandbox/naming_test.go @@ -0,0 +1,92 @@ +package sandbox + +import ( + "os" + "path/filepath" + "testing" + "time" +) + +func TestAgentSlugAndLaunchName(t *testing.T) { + cases := map[string]string{ + "deps": "deps", + "Deps Quality": "deps-quality", + "--a1_vllm.spyre--": "a1-vllm-spyre", + " ": "agent", + "": "agent", + } + for in, want := range cases { + if got := AgentSlug(in); got != want { + t.Errorf("AgentSlug(%q) = %q, want %q", in, got, want) + } + if got := LaunchName(in); got != "hive-"+want+"-sandbox" { + t.Errorf("LaunchName(%q) = %q", in, got) + } + } + if got := WorkspaceDir("/data/agents/sandbox", "Deps Quality", 1700000000000000000); got != filepath.Join("/data/agents/sandbox", "deps-quality-1700000000000000000") { + t.Fatalf("WorkspaceDir = %q", got) + } +} + +func TestWorkspaceRoot(t *testing.T) { + if got := WorkspaceRoot("/mnt/rwx/sandbox", "/data/agents"); got != "/mnt/rwx/sandbox" { + t.Fatalf("configured root must win, got %q", got) + } + if got := WorkspaceRoot("", "/work"); got != filepath.Join("/work", "sandbox") { + t.Fatalf("got %q", got) + } + if got := WorkspaceRoot(" ", ""); got != filepath.Join(DefaultWorkDir, "sandbox") { + t.Fatalf("got %q", got) + } +} + +func TestLatestTranscriptPicksNewestForTheAgentOnly(t *testing.T) { + root := t.TempDir() + write := func(dir string, mod time.Time, body string) string { + p := filepath.Join(root, dir, filepath.FromSlash(TranscriptRelPath)) + if err := os.MkdirAll(filepath.Dir(p), 0o700); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(p, []byte(body), 0o600); err != nil { + t.Fatal(err) + } + if err := os.Chtimes(p, mod, mod); err != nil { + t.Fatal(err) + } + return p + } + base := time.Date(2026, 10, 27, 12, 0, 0, 0, time.UTC) + write("deps-1", base, "old") + newest := write("deps-2", base.Add(time.Hour), "new") + write("deps-quality-3", base.Add(2*time.Hour), "other agent") + // A kick directory without a transcript yet (run in progress) is skipped. + if err := os.MkdirAll(filepath.Join(root, "deps-4", ".hive"), 0o700); err != nil { + t.Fatal(err) + } + + got, ok := LatestTranscript(root, "deps") + if !ok || got != newest { + t.Fatalf("LatestTranscript = %q, %v; want %q", got, ok, newest) + } + if _, ok := LatestTranscript(root, "nobody"); ok { + t.Fatal("agent with no runs must report ok=false") + } + if _, ok := LatestTranscript(filepath.Join(root, "missing"), "deps"); ok { + t.Fatal("missing root must report ok=false") + } +} + +func TestTranscriptExitCode(t *testing.T) { + if code, ok := TranscriptExitCode("stdout:\nhi\n\nstderr:\n\n\n" + TranscriptExitPrefix + "3\n"); !ok || code != 3 { + t.Fatalf("got %d, %v", code, ok) + } + if _, ok := TranscriptExitCode("stdout:\nhi\n\nstderr:\n"); ok { + t.Fatal("legacy transcript without the line must report ok=false") + } + if _, ok := TranscriptExitCode(TranscriptExitPrefix + "many\n"); ok { + t.Fatal("non-numeric code must report ok=false") + } + if _, ok := TranscriptExitCode(""); ok { + t.Fatal("empty transcript must report ok=false") + } +} diff --git a/src/docs/api-reference.md b/src/docs/api-reference.md index f60d744b9f..8811ea8e02 100644 --- a/src/docs/api-reference.md +++ b/src/docs/api-reference.md @@ -596,6 +596,8 @@ always resolved server-side from the validated token. | `DELETE` | `/api/hives/{id}` | Owner only | Hives Delete | `pkg/dashboard/api_contribute.go:276` | | `POST` | `/api/hives/onboard` | Dashboard auth/session | Hives Onboard | `pkg/dashboard/api_contribute.go:277` | | `GET` | `/sso` | Public | SSO | `pkg/dashboard/server.go:1592` | +| `GET` | `/terminal/job/{name}` | Terminal handoff (owner / `terminal` role) | Read-only Job pod log viewer for an agent whose effective `sandbox.runtime` is `job` ([#14798](https://github.com/hivecommons/hive/issues/14798)); the SPA's ▶ terminal link lands here instead of the ttyd tmux pane. `404` unknown agent, `409` when the agent is not a job-runtime sandbox, `503` when no config is loaded | `pkg/dashboard/job_terminal.go:91` | +| `GET` | `/terminal/job/{name}/stream` | Terminal handoff (owner / `terminal` role) | `text/plain` line stream behind the viewer: follows the newest Job pod for the agent while it runs (polls while `Pending`), ends with the container exit code, and when no pod exists shows the newest persisted sandbox transcript plus its recorded exit code, or a "no sandbox run yet" line. Secrets are scrubbed like the agent log. Same error codes as the page | `pkg/dashboard/job_terminal.go:92` | ## Hub SaaS diff --git a/src/docs/sandbox-isolation.md b/src/docs/sandbox-isolation.md index b4b4d32307..9f3957694f 100644 --- a/src/docs/sandbox-isolation.md +++ b/src/docs/sandbox-isolation.md @@ -188,7 +188,9 @@ agents: **What the operator sees.** The kick shows on the agent card like any sandboxed kick, with the runtime named in the output buffer and the audit line. The pod log is the transcript — hive collects it before the Job is deleted and archives it as the kick log, so "full log" on the card and the kick history keep working after the Job is gone — the container exit code is the sandbox exit code, and the kick timeout deletes a Job that is still running. A Job that **failed** is left in place until `ttl_seconds` (default one hour) so `kubectl describe job` and `kubectl logs` still work; a completed Job is deleted at once. Jobs carry the label `app.kubernetes.io/managed-by=hive-kubejob`. -**RBAC.** The spoke's ServiceAccount needs a Role for `batch/jobs` (create, get, list, delete) and `pods` plus `pods/log` (get, list). The standalone kustomize base ships it as `sandbox-job-rbac.yaml`, and the hub provisioner grants it to every hosted spoke as `hive-sandbox-jobs`. +**The terminal pane.** A job-runtime agent has no tmux session in the hive pod, so the dashboard's ▶ terminal does not attach ttyd for it. Instead it opens `/terminal/job/`, a read-only viewer that streams the newest Job pod's log through the same in-cluster client and RBAC the launcher already uses ([#14798](https://github.com/hivecommons/hive/issues/14798)): it follows the pod while the kick runs (waiting while the pod is `Pending`, e.g. for an accelerator node), prints the container exit code when it ends, and between kicks, when the completed Job has already been deleted, shows the last run's persisted transcript (`/.hive/sandbox-transcript.log`, which now ends with an `exit code: N` line) or a clear "no sandbox run yet" state. The pane is observation only; there is no input path into the Job. The same terminal handoff and role check as the tmux pane apply. + +**RBAC.** The spoke's ServiceAccount needs a Role for `batch/jobs` (create, get, list, delete) and `pods` plus `pods/log` (get, list); the terminal viewer needs nothing beyond that same `pods/log` grant. The standalone kustomize base ships it as `sandbox-job-rbac.yaml`, and the hub provisioner grants it to every hosted spoke as `hive-sandbox-jobs`. Hive warns at boot and on reload (`config.AgentSandboxGateWarnings`) when a job-runtime agent resolves no `workspace_claim` or names a runtime hive does not have, and refuses the kick with the same message rather than failing it after the agent is marked running. diff --git a/src/internal/testutil/dashboard_import_allowlist.txt b/src/internal/testutil/dashboard_import_allowlist.txt index ac334ce4b8..49e67caf69 100644 --- a/src/internal/testutil/dashboard_import_allowlist.txt +++ b/src/internal/testutil/dashboard_import_allowlist.txt @@ -10,7 +10,9 @@ github.com/hivecommons/hive/crux github.com/hivecommons/hive/crux/agentparse github.com/hivecommons/hive/crux/claude +github.com/hivecommons/hive/crux/kubejob github.com/hivecommons/hive/crux/paneclass +github.com/hivecommons/hive/crux/sandbox github.com/hivecommons/hive/crux/skillreg github.com/hivecommons/hive/crux/toolapprove github.com/hivecommons/hive/crux/watchdog diff --git a/src/pkg/dashboard/job_terminal.go b/src/pkg/dashboard/job_terminal.go new file mode 100644 index 0000000000..a1fb85819c --- /dev/null +++ b/src/pkg/dashboard/job_terminal.go @@ -0,0 +1,389 @@ +package dashboard + +import ( + "context" + "fmt" + "html" + "io" + "net/http" + "os" + "strings" + "time" + + "github.com/hivecommons/hive/crux/kubejob" + "github.com/hivecommons/hive/crux/sandbox" + "github.com/hivecommons/hive/pkg/config" +) + +// Job-runtime terminal (hivecommons/hive#14798). +// +// An agent with sandbox.runtime: job runs each kick as a Kubernetes Job in +// its own pod, so there is no tmux session in the hive pod for ttyd to +// attach to and the ordinary "▶ terminal" sat on "tmux session not created +// yet" until its wait expired. For those agents the SPA's terminal link +// points here instead (terminalUrl in static/index.html, keyed on the +// sandboxRuntime field of the agent status), and this page streams the kick +// pod's log read-only. +// +// Mounted UNDER /terminal on purpose: the terminal handoff code, the +// Path=/terminal assertion cookie and the terminal role check in +// authenticate() are all keyed on that prefix, so the existing openTerminal() +// flow in the SPA authenticates this page exactly as it does ttyd, with no +// second auth path to maintain. The Go 1.22 mux picks these more specific +// patterns over the "/terminal/" reverse proxy. +// +// Why the Go server rather than ttyd-tmux.sh: the hive image carries no +// kubectl (the kubejob launcher deliberately speaks to the API server over +// plain HTTP with the pod's ServiceAccount), the script runs as the +// unprivileged ttyd user with no view of hive.yaml to learn an agent's +// runtime, and streaming the pod log from Go reuses the launcher's client, +// namespace discovery and the RBAC already granted for the launcher's own +// end-of-run log read (pods, pods/log get+list in deploy/k8s/sandbox-job-rbac.yaml). +// +// Three states, each named in the first line of output so an operator never +// mistakes one for another: +// - a pod exists for the agent: its log is streamed, following while the +// kick container runs, then the exit code is reported; +// - no pod, but a persisted transcript: the last run's transcript and its +// recorded exit code (a completed Job is deleted by the launcher as soon +// as the kick finishes, so this is the normal state between kicks); +// - neither: the agent has not run yet. + +const ( + // Both live under terminalPathPrefix so the terminal handoff code, + // the Path=/terminal assertion cookie and the terminal role check all + // apply unchanged (isTerminalPath). + jobTerminalPagePath = "/terminal/job/{name}" + jobTerminalStreamPath = "/terminal/job/{name}/stream" + + // jobTerminalMarker prefixes every line this handler writes itself, so + // status lines are distinguishable from the agent's own output. + jobTerminalMarker = "── " + + // defaultJobTerminalPollInterval is how often a Pending pod (image pull, + // scheduling) is re-read before its log can be followed; the API server + // refuses a log request until the container has started. + defaultJobTerminalPollInterval = 3 * time.Second +) + +// jobPodLogReader is the slice of *kubejob.Launcher the terminal uses, so +// tests can substitute a fake without an API server. +type jobPodLogReader interface { + LatestPod(ctx context.Context, launchName string) (kubejob.PodInfo, bool, error) + PodStatus(ctx context.Context, pod string) (kubejob.PodInfo, error) + StreamLog(ctx context.Context, pod string, follow bool, w io.Writer) error +} + +// jobTerminalDeps are the test seams for the job-runtime terminal; nil +// fields take the in-cluster defaults. +type jobTerminalDeps struct { + reader jobPodLogReader + workspaceRoot string + pollInterval time.Duration + // now is used for the "written at" stamp on a persisted transcript. + now func() time.Time +} + +func (s *Server) registerJobTerminal() { + // Literal patterns (not the constants) so that + // scripts/check-api-reference-citations.sh can verify docs/api-reference.md. + s.mux.HandleFunc("GET /terminal/job/{name}", s.handleJobTerminalPage) + s.mux.HandleFunc("GET /terminal/job/{name}/stream", s.handleJobTerminalStream) +} + +func (s *Server) jobPodLogReader() jobPodLogReader { + if s.jobTerminal.reader != nil { + return s.jobTerminal.reader + } + return &kubejob.Launcher{} +} + +func (s *Server) jobTerminalWorkspaceRoot() string { + if s.jobTerminal.workspaceRoot != "" { + return s.jobTerminal.workspaceRoot + } + configured := "" + if s.deps != nil && s.deps.Config != nil { + configured = s.deps.Config.AgentSandbox.WorkspaceDir + } + // Same resolution as the agent manager (crux/agent.NewManager), whose + // work dir is HIVE_WORK_DIR or the sandbox package default. + return sandbox.WorkspaceRoot(configured, os.Getenv("HIVE_WORK_DIR")) +} + +func (s *Server) jobTerminalPollInterval() time.Duration { + if s.jobTerminal.pollInterval > 0 { + return s.jobTerminal.pollInterval + } + return defaultJobTerminalPollInterval +} + +// jobTerminalAgent resolves the path's agent and checks that its effective +// sandbox runtime is job. The status code says which precondition failed: +// 404 for an unknown agent, 409 for one that has a tmux terminal instead. +func (s *Server) jobTerminalAgent(r *http.Request) (string, int, string) { + if s.deps == nil || s.deps.Config == nil { + return "", http.StatusServiceUnavailable, "configuration unavailable" + } + name := s.resolveAgentParam(r.PathValue("name")) + cfg := s.deps.Config + agentCfg, ok := cfg.Agents[name] + if !ok { + return "", http.StatusNotFound, fmt.Sprintf("agent %q not found", name) + } + if !agentCfg.SandboxEnabled(cfg.AgentSandbox) { + return "", http.StatusConflict, fmt.Sprintf("agent %q is not sandboxed; its terminal is the tmux session at /terminal/?arg=hive-%s", name, name) + } + if rt := agentCfg.SandboxRuntime(cfg.AgentSandbox); rt != config.SandboxRuntimeJob { + return "", http.StatusConflict, fmt.Sprintf("agent %q runs sandbox kicks with runtime %q, not as a Kubernetes Job; there is no Job pod log to show", name, rt) + } + return name, http.StatusOK, "" +} + +// handleJobTerminalPage serves the viewer document: a
 the inline
+// script fills from the stream endpoint as lines arrive. The script is
+// inline because /terminal documents carry the blanket script-src
+// 'unsafe-inline' policy (securityHeaders) rather than the SPA's hash
+// allowlist; no on*= attributes are used, matching the rest of the server.
+func (s *Server) handleJobTerminalPage(w http.ResponseWriter, r *http.Request) {
+	name, code, msg := s.jobTerminalAgent(r)
+	if code != http.StatusOK {
+		http.Error(w, msg, code)
+		return
+	}
+	esc := html.EscapeString(name)
+	w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	w.Header().Set("Cache-Control", "no-store")
+	_, _ = fmt.Fprintf(w, jobTerminalPageHTML, esc, esc, esc)
+}
+
+// %s placeholders: agent (title), agent (heading), agent (stream URL path
+// segment). The stream URL is relative so the page works behind any prefix
+// the dashboard host is served at.
+const jobTerminalPageHTML = `%s — sandbox job log
+
+

▶ %s — sandbox job log

read-only: the kick runs as a Kubernetes Job in its own pod, so this is the pod's log, not a shellconnecting…
+

+
+
+`
+
+// handleJobTerminalStream writes the kick pod's log as plain text, flushed
+// line by line, with status lines prefixed by jobTerminalMarker. Everything
+// from the pod is passed through the same credential scrubber the executor
+// applies before persisting a transcript (CWE-532): the live log is the one
+// path where unscrubbed agent output could otherwise reach a browser.
+func (s *Server) handleJobTerminalStream(w http.ResponseWriter, r *http.Request) {
+	name, code, msg := s.jobTerminalAgent(r)
+	if code != http.StatusOK {
+		http.Error(w, msg, code)
+		return
+	}
+	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+	w.Header().Set("Cache-Control", "no-store")
+	// Ask intermediaries (the hub nginx, an Ingress) not to buffer the
+	// response, or a followed stream arrives all at once when the pod ends.
+	w.Header().Set("X-Accel-Buffering", "no")
+	w.WriteHeader(http.StatusOK)
+
+	out := &jobTerminalWriter{w: w}
+	ctx := r.Context()
+	reader := s.jobPodLogReader()
+
+	pod, found, err := reader.LatestPod(ctx, sandbox.LaunchName(name))
+	if err != nil {
+		out.status("cannot list Job pods for agent %q: %v", name, err)
+		out.status("hint: the hive ServiceAccount needs get+list on pods and pods/log in its own namespace (deploy/k8s/sandbox-job-rbac.yaml); showing the last persisted transcript instead")
+		s.writeJobTranscript(out, name)
+		return
+	}
+	if !found {
+		s.writeJobTranscript(out, name)
+		return
+	}
+	s.streamJobPod(ctx, out, reader, pod)
+}
+
+// streamJobPod follows a live pod, or dumps a finished one, then reports the
+// exit code. A Pending pod is re-read on a ticker until it is Running (or
+// finished, or the client leaves): the API server answers a log request for
+// a container that has not started with 400, which would otherwise end the
+// stream before the kick has produced a line.
+func (s *Server) streamJobPod(ctx context.Context, out *jobTerminalWriter, reader jobPodLogReader, pod kubejob.PodInfo) {
+	out.status("job %s · pod %s · %s", orUnknown(pod.Job), pod.Name, describePodPhase(pod))
+	if pod.Phase == kubejob.PodPhasePending && !pod.Finished() {
+		ticker := time.NewTicker(s.jobTerminalPollInterval())
+		defer ticker.Stop()
+		for pod.Phase == kubejob.PodPhasePending && !pod.Finished() {
+			select {
+			case <-ctx.Done():
+				return
+			case <-ticker.C:
+			}
+			next, err := reader.PodStatus(ctx, pod.Name)
+			if err != nil {
+				if ctx.Err() != nil {
+					return
+				}
+				out.status("waiting for pod %s to start: %v", pod.Name, err)
+				continue
+			}
+			if next.Waiting != pod.Waiting || next.Phase != pod.Phase {
+				out.status("pod %s · %s", next.Name, describePodPhase(next))
+			}
+			pod = next
+		}
+	}
+	follow := !pod.Finished()
+	scrub := &kubejob.LineFilterWriter{Dst: out, Fn: scrubLogLine}
+	err := reader.StreamLog(ctx, pod.Name, follow, scrub)
+	_ = scrub.Close()
+	if err != nil {
+		if ctx.Err() != nil {
+			return
+		}
+		out.status("log stream ended with an error: %v", err)
+	}
+	if follow {
+		// The follow ended because the container exited; re-read for the code.
+		// The request context may already be gone if the browser left; a
+		// short detached context still answers the common case.
+		statusCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+		defer cancel()
+		if next, err := reader.PodStatus(statusCtx, pod.Name); err == nil {
+			pod = next
+		}
+	}
+	if pod.Terminated {
+		out.status("kick container exited with code %d", pod.ExitCode)
+	} else {
+		out.status("pod %s · %s (exit code not reported)", pod.Name, describePodPhase(pod))
+	}
+}
+
+// writeJobTranscript is the no-pod path: the last persisted transcript with
+// its recorded exit code, or an explicit "no run yet".
+func (s *Server) writeJobTranscript(out *jobTerminalWriter, name string) {
+	root := s.jobTerminalWorkspaceRoot()
+	path, ok := sandbox.LatestTranscript(root, name)
+	if !ok {
+		out.status("no sandbox run yet for agent %q: no Job pod in the namespace and no transcript under %s. Kick the agent to start one.", name, root)
+		return
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		out.status("no Job pod for agent %q right now; its last transcript %s could not be read: %v", name, path, err)
+		return
+	}
+	written := "unknown time"
+	if st, err := os.Stat(path); err == nil {
+		written = st.ModTime().UTC().Format(time.RFC3339)
+	}
+	out.status("no Job pod for agent %q right now (a completed Job is deleted when its kick finishes); showing the last run's transcript, written %s", name, written)
+	out.status("%s", path)
+	text := string(data)
+	// The executor already scrubbed this at write time; scrubbing again is
+	// idempotent and guards transcripts written by other tooling.
+	if _, err := io.WriteString(out, scrubLogLine(strings.TrimRight(text, "\n")+"\n")); err != nil {
+		return
+	}
+	if code, ok := sandbox.TranscriptExitCode(text); ok {
+		out.status("last run exited with code %d", code)
+	} else {
+		out.status("last run's exit code was not recorded in this transcript")
+	}
+}
+
+func scrubLogLine(line string) string {
+	// Same seam the agent log pane uses (crux.RedactPaneTokens), so the Job
+	// log is redacted exactly like tmux pane output.
+	return redactTokens(line)
+}
+
+func describePodPhase(p kubejob.PodInfo) string {
+	switch {
+	case p.Terminated:
+		return fmt.Sprintf("%s (exit code %d)", orUnknown(p.Phase), p.ExitCode)
+	case p.Waiting != "":
+		return fmt.Sprintf("%s (%s)", orUnknown(p.Phase), p.Waiting)
+	default:
+		return orUnknown(p.Phase)
+	}
+}
+
+func orUnknown(s string) string {
+	if s == "" {
+		return "unknown"
+	}
+	return s
+}
+
+// jobTerminalWriter writes to the response and flushes after every write,
+// so each line reaches the browser as it is produced. It satisfies
+// kubejob.FlushWriter for LineFilterWriter.
+type jobTerminalWriter struct {
+	w http.ResponseWriter
+}
+
+func (j *jobTerminalWriter) Write(p []byte) (int, error) {
+	n, err := j.w.Write(p)
+	j.Flush()
+	return n, err
+}
+
+func (j *jobTerminalWriter) Flush() {
+	if f, ok := j.w.(http.Flusher); ok {
+		f.Flush()
+	}
+}
+
+func (j *jobTerminalWriter) status(format string, args ...any) {
+	_, _ = io.WriteString(j, jobTerminalMarker+fmt.Sprintf(format, args...)+"\n")
+}
diff --git a/src/pkg/dashboard/job_terminal_test.go b/src/pkg/dashboard/job_terminal_test.go
new file mode 100644
index 0000000000..8c4becfd59
--- /dev/null
+++ b/src/pkg/dashboard/job_terminal_test.go
@@ -0,0 +1,475 @@
+package dashboard
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/hivecommons/hive/crux/kubejob"
+	"github.com/hivecommons/hive/crux/sandbox"
+	"github.com/hivecommons/hive/pkg/config"
+)
+
+// fakeJobPodLogReader scripts the pod observation path: a (possibly absent)
+// latest pod, a sequence of PodStatus answers, and a log whose delivery can
+// be gated so a followed stream is observed mid-flight without sleeping.
+type fakeJobPodLogReader struct {
+	mu          sync.Mutex
+	pod         kubejob.PodInfo
+	found       bool
+	listErr     error
+	statuses    []kubejob.PodInfo
+	statusErr   error
+	statusCalls int
+	logLines    []string
+	logErr      error
+	followed    []bool
+	launchNames []string
+	// gate, when non-nil, is received from before the last log line is
+	// written, so the test controls when the "live" stream ends.
+	gate chan struct{}
+	// lineWritten is signalled after each log line reaches the writer.
+	lineWritten chan struct{}
+}
+
+func (f *fakeJobPodLogReader) LatestPod(_ context.Context, launchName string) (kubejob.PodInfo, bool, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.launchNames = append(f.launchNames, launchName)
+	return f.pod, f.found, f.listErr
+}
+
+func (f *fakeJobPodLogReader) PodStatus(context.Context, string) (kubejob.PodInfo, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if f.statusErr != nil {
+		return kubejob.PodInfo{}, f.statusErr
+	}
+	i := f.statusCalls
+	f.statusCalls++
+	if i >= len(f.statuses) {
+		i = len(f.statuses) - 1
+	}
+	if i < 0 {
+		return f.pod, nil
+	}
+	return f.statuses[i], nil
+}
+
+func (f *fakeJobPodLogReader) StreamLog(ctx context.Context, _ string, follow bool, w io.Writer) error {
+	f.mu.Lock()
+	f.followed = append(f.followed, follow)
+	lines, gate, logErr, written := f.logLines, f.gate, f.logErr, f.lineWritten
+	f.mu.Unlock()
+	for i, l := range lines {
+		if gate != nil && i == len(lines)-1 {
+			select {
+			case <-gate:
+			case <-ctx.Done():
+				return ctx.Err()
+			}
+		}
+		if _, err := io.WriteString(w, l); err != nil {
+			return err
+		}
+		if written != nil {
+			written <- struct{}{}
+		}
+	}
+	return logErr
+}
+
+// jobTerminalServer is apiServer with a sandboxed job-runtime agent "deps"
+// alongside the stock tmux agent "scanner", plus a podman-runtime "lint".
+func jobTerminalServer(t *testing.T, reader *fakeJobPodLogReader) (*Server, string) {
+	t.Helper()
+	s, deps := apiServer(t)
+	on := true
+	deps.Config.AgentSandbox = config.AgentSandboxConfig{Enabled: true, Image: "img"}
+	deps.Config.Agents["deps"] = config.AgentConfig{Backend: "claude", Enabled: true, Sandbox: &config.AgentSandboxOverride{Enabled: &on, Runtime: config.SandboxRuntimeJob}}
+	deps.Config.Agents["lint"] = config.AgentConfig{Backend: "claude", Enabled: true, Sandbox: &config.AgentSandboxOverride{Enabled: &on}}
+	root := t.TempDir()
+	s.jobTerminal = jobTerminalDeps{reader: reader, workspaceRoot: root, pollInterval: time.Millisecond}
+	return s, root
+}
+
+func TestJobTerminalRoutesAreUnderTerminalPrefix(t *testing.T) {
+	// The handoff code and assertion cookie are keyed on /terminal; a route
+	// elsewhere would silently lose terminal auth.
+	for _, p := range []string{jobTerminalPagePath, jobTerminalStreamPath} {
+		if !isTerminalPath(strings.ReplaceAll(p, "{name}", "deps")) {
+			t.Fatalf("%s is not a terminal path", p)
+		}
+	}
+}
+
+func TestJobTerminalRejectsNonJobAgents(t *testing.T) {
+	s, _ := jobTerminalServer(t, &fakeJobPodLogReader{})
+	cases := map[string]int{
+		"/terminal/job/nobody":         http.StatusNotFound,
+		"/terminal/job/scanner":        http.StatusConflict, // not sandboxed
+		"/terminal/job/lint":           http.StatusConflict, // podman runtime
+		"/terminal/job/nobody/stream":  http.StatusNotFound,
+		"/terminal/job/scanner/stream": http.StatusConflict,
+		"/terminal/job/lint/stream":    http.StatusConflict,
+	}
+	for path, want := range cases {
+		rec := doGet(s, path)
+		if rec.Code != want {
+			t.Errorf("%s: status = %d, want %d (%s)", path, rec.Code, want, rec.Body.String())
+		}
+	}
+	rec := doGet(s, "/terminal/job/scanner")
+	if !strings.Contains(rec.Body.String(), "/terminal/?arg=hive-scanner") {
+		t.Fatalf("a tmux agent's 409 must point at its tmux terminal: %s", rec.Body.String())
+	}
+	rec = doGet(s, "/terminal/job/lint")
+	if !strings.Contains(rec.Body.String(), `runtime "podman"`) {
+		t.Fatalf("a podman agent's 409 must name the runtime: %s", rec.Body.String())
+	}
+}
+
+func TestJobTerminalPageServesViewer(t *testing.T) {
+	s, _ := jobTerminalServer(t, &fakeJobPodLogReader{})
+	rec := doGet(s, "/terminal/job/deps")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d: %s", rec.Code, rec.Body.String())
+	}
+	if ct := rec.Header().Get("Content-Type"); !strings.HasPrefix(ct, "text/html") {
+		t.Fatalf("Content-Type = %q", ct)
+	}
+	body := rec.Body.String()
+	for _, want := range []string{"deps — sandbox job log", "'./deps/stream'", "read-only", `id="reconnect"`, "addEventListener('click'"} {
+		if !strings.Contains(body, want) {
+			t.Errorf("page missing %q", want)
+		}
+	}
+	if strings.Contains(body, " onclick=") || strings.Contains(body, " onload=") {
+		t.Fatal("inline handler attributes are closed by CSP script-src-attr elsewhere; keep the viewer consistent")
+	}
+	// Agent names are escaped into the document.
+	on := true
+	s.deps.Config.Agents[`x`] = config.AgentConfig{Enabled: true, Sandbox: &config.AgentSandboxOverride{Enabled: &on, Runtime: config.SandboxRuntimeJob}}
+	rec = doGet(s, "/terminal/job/"+strings.ReplaceAll(`x`, " ", "%20"))
+	if rec.Code == http.StatusOK && strings.Contains(rec.Body.String(), "") {
+		t.Fatal("agent name rendered unescaped")
+	}
+}
+
+func TestJobTerminalStreamNoRunYet(t *testing.T) {
+	reader := &fakeJobPodLogReader{}
+	s, root := jobTerminalServer(t, reader)
+	rec := doGet(s, "/terminal/job/deps/stream")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d", rec.Code)
+	}
+	if ct := rec.Header().Get("Content-Type"); !strings.HasPrefix(ct, "text/plain") {
+		t.Fatalf("Content-Type = %q", ct)
+	}
+	body := rec.Body.String()
+	if !strings.Contains(body, `no sandbox run yet for agent "deps"`) || !strings.Contains(body, root) {
+		t.Fatalf("no-run state must be named and locate the workspace root:\n%s", body)
+	}
+	reader.mu.Lock()
+	names := reader.launchNames
+	reader.mu.Unlock()
+	if len(names) != 1 || names[0] != sandbox.LaunchName("deps") {
+		t.Fatalf("pods must be looked up by the executor's launch name, got %v", names)
+	}
+}
+
+func writeTranscript(t *testing.T, root, agent string, unixNano int64, body string) string {
+	t.Helper()
+	p := filepath.Join(sandbox.WorkspaceDir(root, agent, unixNano), filepath.FromSlash(sandbox.TranscriptRelPath))
+	if err := os.MkdirAll(filepath.Dir(p), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(p, []byte(body), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	return p
+}
+
+func TestJobTerminalStreamShowsLastTranscriptWhenNoPod(t *testing.T) {
+	reader := &fakeJobPodLogReader{}
+	s, root := jobTerminalServer(t, reader)
+	old := writeTranscript(t, root, "deps", 1, "stdout:\nold run\n\nstderr:\n\n\n"+sandbox.TranscriptExitPrefix+"1\n")
+	newest := writeTranscript(t, root, "deps", 2, "stdout:\nbumped golang.org/x/net\ntoken ghp_abcdefghijklmnopqrstuvwxyz0123456789\n\nstderr:\n\n\n"+sandbox.TranscriptExitPrefix+"0\n")
+	// Make the ordering unambiguous regardless of filesystem timestamp
+	// resolution.
+	base := time.Date(2026, 10, 27, 12, 0, 0, 0, time.UTC)
+	if err := os.Chtimes(old, base, base); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Chtimes(newest, base.Add(time.Minute), base.Add(time.Minute)); err != nil {
+		t.Fatal(err)
+	}
+
+	body := doGet(s, "/terminal/job/deps/stream").Body.String()
+	for _, want := range []string{
+		"no Job pod for agent \"deps\" right now",
+		newest,
+		"bumped golang.org/x/net",
+		"last run exited with code 0",
+	} {
+		if !strings.Contains(body, want) {
+			t.Errorf("missing %q in:\n%s", want, body)
+		}
+	}
+	if strings.Contains(body, "old run") || strings.Contains(body, "exited with code 1") {
+		t.Fatalf("older transcript leaked into the pane:\n%s", body)
+	}
+	if strings.Contains(body, "ghp_abcdefghijklmnopqrstuvwxyz0123456789") {
+		t.Fatalf("token-shaped value reached the browser unscrubbed:\n%s", body)
+	}
+
+	// A legacy transcript without the exit line says so rather than
+	// inventing a code.
+	legacy := writeTranscript(t, root, "deps", 3, "stdout:\nlegacy\n\nstderr:\n")
+	if err := os.Chtimes(legacy, base.Add(2*time.Minute), base.Add(2*time.Minute)); err != nil {
+		t.Fatal(err)
+	}
+	body = doGet(s, "/terminal/job/deps/stream").Body.String()
+	if !strings.Contains(body, "legacy") || !strings.Contains(body, "exit code was not recorded") {
+		t.Fatalf("legacy transcript handling:\n%s", body)
+	}
+}
+
+func TestJobTerminalStreamListErrorFallsBackWithRBACHint(t *testing.T) {
+	reader := &fakeJobPodLogReader{listErr: errors.New(`GET /api/v1/namespaces/hive/pods: HTTP 403: pods is forbidden`)}
+	s, root := jobTerminalServer(t, reader)
+	writeTranscript(t, root, "deps", 1, "stdout:\nfrom disk\n\nstderr:\n\n\n"+sandbox.TranscriptExitPrefix+"2\n")
+	rec := doGet(s, "/terminal/job/deps/stream")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d", rec.Code)
+	}
+	body := rec.Body.String()
+	for _, want := range []string{"cannot list Job pods", "pods is forbidden", "sandbox-job-rbac.yaml", "from disk", "last run exited with code 2"} {
+		if !strings.Contains(body, want) {
+			t.Errorf("missing %q in:\n%s", want, body)
+		}
+	}
+}
+
+func TestJobTerminalStreamFinishedPodDumpsLogAndExitCode(t *testing.T) {
+	pod := kubejob.PodInfo{Name: "hive-kick-deps-1-abcde", Job: "hive-kick-deps-1", Phase: kubejob.PodPhaseFailed, Terminated: true, ExitCode: 3}
+	reader := &fakeJobPodLogReader{pod: pod, found: true, logLines: []string{"compiling\n", "FAIL: tests\n"}}
+	s, _ := jobTerminalServer(t, reader)
+	body := doGet(s, "/terminal/job/deps/stream").Body.String()
+	for _, want := range []string{
+		"job hive-kick-deps-1 · pod hive-kick-deps-1-abcde · Failed (exit code 3)",
+		"compiling\nFAIL: tests\n",
+		"kick container exited with code 3",
+	} {
+		if !strings.Contains(body, want) {
+			t.Errorf("missing %q in:\n%s", want, body)
+		}
+	}
+	reader.mu.Lock()
+	followed := reader.followed
+	reader.mu.Unlock()
+	if len(followed) != 1 || followed[0] {
+		t.Fatalf("a finished pod must not be followed, got %v", followed)
+	}
+}
+
+// flushRecorder records each Flush so a test can wait for a line to have
+// been pushed to the client rather than sleeping.
+type flushRecorder struct {
+	*httptest.ResponseRecorder
+	flushes chan string
+}
+
+func (f *flushRecorder) Flush() {
+	f.ResponseRecorder.Flush()
+	f.flushes <- f.Body.String()
+}
+
+func TestJobTerminalStreamFollowsRunningPodThenReportsExit(t *testing.T) {
+	running := kubejob.PodInfo{Name: "p", Job: "j", Phase: kubejob.PodPhaseRunning}
+	exited := kubejob.PodInfo{Name: "p", Job: "j", Phase: kubejob.PodPhaseSucceeded, Terminated: true, ExitCode: 0}
+	gate := make(chan struct{})
+	reader := &fakeJobPodLogReader{pod: running, found: true, logLines: []string{"step 1\n", "step 2\n"}, gate: gate, statuses: []kubejob.PodInfo{exited}}
+	s, _ := jobTerminalServer(t, reader)
+
+	rec := &flushRecorder{ResponseRecorder: httptest.NewRecorder(), flushes: make(chan string, 64)}
+	req := httptest.NewRequest(http.MethodGet, "/terminal/job/deps/stream", nil)
+	done := make(chan struct{})
+	go func() {
+		s.mux.ServeHTTP(rec, req)
+		close(done)
+	}()
+
+	// The first line is flushed to the client while the stream is still
+	// open: following, not buffering.
+	deadline := time.After(10 * time.Second)
+	for {
+		select {
+		case body := <-rec.flushes:
+			if strings.Contains(body, "step 1\n") {
+				goto release
+			}
+		case <-deadline:
+			t.Fatal("first log line never flushed while the pod was running")
+		}
+	}
+release:
+	close(gate)
+	select {
+	case <-done:
+	case <-time.After(10 * time.Second):
+		t.Fatal("handler did not finish after the pod exited")
+	}
+	body := rec.Body.String()
+	for _, want := range []string{"job j · pod p · Running", "step 1\nstep 2\n", "kick container exited with code 0"} {
+		if !strings.Contains(body, want) {
+			t.Errorf("missing %q in:\n%s", want, body)
+		}
+	}
+	reader.mu.Lock()
+	followed := reader.followed
+	reader.mu.Unlock()
+	if len(followed) != 1 || !followed[0] {
+		t.Fatalf("a running pod must be followed, got %v", followed)
+	}
+	if rec.Header().Get("X-Accel-Buffering") != "no" {
+		t.Fatal("stream must opt out of proxy buffering")
+	}
+}
+
+func TestJobTerminalStreamWaitsForPendingPod(t *testing.T) {
+	pending := kubejob.PodInfo{Name: "p", Job: "j", Phase: kubejob.PodPhasePending, Waiting: "ContainerCreating"}
+	running := kubejob.PodInfo{Name: "p", Job: "j", Phase: kubejob.PodPhaseRunning}
+	exited := kubejob.PodInfo{Name: "p", Job: "j", Phase: kubejob.PodPhaseSucceeded, Terminated: true, ExitCode: 0}
+	reader := &fakeJobPodLogReader{pod: pending, found: true, logLines: []string{"hello\n"},
+		statuses: []kubejob.PodInfo{pending, {Name: "p", Job: "j", Phase: kubejob.PodPhasePending, Waiting: "ImagePullBackOff"}, running, exited}}
+	s, _ := jobTerminalServer(t, reader)
+	body := doGet(s, "/terminal/job/deps/stream").Body.String()
+	for _, want := range []string{"Pending (ContainerCreating)", "Pending (ImagePullBackOff)", "pod p · Running", "hello\n", "kick container exited with code 0"} {
+		if !strings.Contains(body, want) {
+			t.Errorf("missing %q in:\n%s", want, body)
+		}
+	}
+	// The pending poll must not have requested logs before the pod ran.
+	reader.mu.Lock()
+	followed := reader.followed
+	reader.mu.Unlock()
+	if len(followed) != 1 || !followed[0] {
+		t.Fatalf("followed = %v", followed)
+	}
+}
+
+func TestJobTerminalStreamClientGoneStopsPendingPoll(t *testing.T) {
+	pending := kubejob.PodInfo{Name: "p", Phase: kubejob.PodPhasePending, Waiting: "ContainerCreating"}
+	reader := &fakeJobPodLogReader{pod: pending, found: true, statuses: []kubejob.PodInfo{pending}}
+	s, _ := jobTerminalServer(t, reader)
+	ctx, cancel := context.WithCancel(context.Background())
+	req := httptest.NewRequest(http.MethodGet, "/terminal/job/deps/stream", nil).WithContext(ctx)
+	rec := httptest.NewRecorder()
+	done := make(chan struct{})
+	go func() {
+		s.mux.ServeHTTP(rec, req)
+		close(done)
+	}()
+	cancel()
+	select {
+	case <-done:
+	case <-time.After(10 * time.Second):
+		t.Fatal("handler kept polling after the client went away")
+	}
+	reader.mu.Lock()
+	followed := reader.followed
+	reader.mu.Unlock()
+	if len(followed) != 0 {
+		t.Fatalf("no log request should be made for a pod that never started, got %v", followed)
+	}
+}
+
+func TestJobTerminalStreamScrubsLiveLog(t *testing.T) {
+	pod := kubejob.PodInfo{Name: "p", Phase: kubejob.PodPhaseSucceeded, Terminated: true}
+	reader := &fakeJobPodLogReader{pod: pod, found: true, logLines: []string{"auth: ghp_abcdefghijklmnopqrstuvwxyz0123456789 ok\n"}}
+	s, _ := jobTerminalServer(t, reader)
+	body := doGet(s, "/terminal/job/deps/stream").Body.String()
+	if strings.Contains(body, "ghp_abcdefghijklmnopqrstuvwxyz0123456789") {
+		t.Fatalf("live pod log reached the browser unscrubbed:\n%s", body)
+	}
+	if !strings.Contains(body, "auth: ") || !strings.Contains(body, " ok\n") {
+		t.Fatalf("scrubbing must keep the surrounding line:\n%s", body)
+	}
+}
+
+func TestJobTerminalStreamLogErrorIsReported(t *testing.T) {
+	pod := kubejob.PodInfo{Name: "p", Phase: kubejob.PodPhaseFailed, Terminated: true, ExitCode: 137}
+	reader := &fakeJobPodLogReader{pod: pod, found: true, logErr: errors.New("HTTP 403: pods/log is forbidden")}
+	s, _ := jobTerminalServer(t, reader)
+	body := doGet(s, "/terminal/job/deps/stream").Body.String()
+	if !strings.Contains(body, "log stream ended with an error: HTTP 403") || !strings.Contains(body, "exited with code 137") {
+		t.Fatalf("body:\n%s", body)
+	}
+}
+
+func TestJobTerminalDefaultsResolveInCluster(t *testing.T) {
+	s, deps := apiServer(t)
+	if _, ok := s.jobPodLogReader().(*kubejob.Launcher); !ok {
+		t.Fatal("default reader must be the kubejob launcher's in-cluster client")
+	}
+	if s.jobTerminalPollInterval() != defaultJobTerminalPollInterval {
+		t.Fatal("default poll interval")
+	}
+	t.Setenv("HIVE_WORK_DIR", "/work")
+	if got := s.jobTerminalWorkspaceRoot(); got != sandbox.WorkspaceRoot("", "/work") {
+		t.Fatalf("workspace root = %q", got)
+	}
+	deps.Config.AgentSandbox.WorkspaceDir = "/mnt/rwx/sandbox"
+	if got := s.jobTerminalWorkspaceRoot(); got != "/mnt/rwx/sandbox" {
+		t.Fatalf("configured workspace root must win, got %q", got)
+	}
+	s.deps = nil
+	rec := doGet(s, "/terminal/job/deps/stream")
+	if rec.Code != http.StatusServiceUnavailable {
+		t.Fatalf("without config: status = %d", rec.Code)
+	}
+}
+
+func TestAgentStatusExposesSandboxRuntime(t *testing.T) {
+	on := true
+	cfg := &config.Config{AgentRuntimeConfig: config.AgentRuntimeConfig{AgentSandbox: config.AgentSandboxConfig{Enabled: true, Runtime: config.SandboxRuntimeJob}}}
+	if got := effectiveSandboxRuntime(config.AgentConfig{}, cfg); got != "" {
+		t.Fatalf("non-sandboxed agent must report no runtime, got %q", got)
+	}
+	if got := effectiveSandboxRuntime(config.AgentConfig{Sandbox: &config.AgentSandboxOverride{Enabled: &on}}, cfg); got != config.SandboxRuntimeJob {
+		t.Fatalf("global runtime not inherited, got %q", got)
+	}
+	if got := effectiveSandboxRuntime(config.AgentConfig{Sandbox: &config.AgentSandboxOverride{Enabled: &on, Runtime: config.SandboxRuntimePodman}}, cfg); got != config.SandboxRuntimePodman {
+		t.Fatalf("per-agent override not honoured, got %q", got)
+	}
+}
+
+func TestStaticTerminalLinkRoutesJobRuntimeToPodLogViewer(t *testing.T) {
+	body, err := os.ReadFile("static/index.html")
+	if err != nil {
+		t.Fatal(err)
+	}
+	html := string(body)
+	for _, want := range []string{
+		"const JOB_SANDBOX_RUNTIME = 'job';",
+		"function terminalUrl(agentName, sandboxRuntime)",
+		"/terminal/job/${encodeURIComponent(agentName)}",
+		`href="${terminalUrl(a.name, a.sandboxRuntime)}"`,
+	} {
+		if !strings.Contains(html, want) {
+			t.Fatalf("static dashboard job-terminal wiring missing %q", want)
+		}
+	}
+	if strings.Contains(html, "terminalUrl(a.name)}") {
+		t.Fatal("a terminal link still ignores the agent's sandbox runtime")
+	}
+}
diff --git a/src/pkg/dashboard/server.go b/src/pkg/dashboard/server.go
index ec9e97d89f..1544769dcb 100644
--- a/src/pkg/dashboard/server.go
+++ b/src/pkg/dashboard/server.go
@@ -242,6 +242,10 @@ type Server struct {
 	// a live tmux pane.
 	captureFullLogFn func(name string) (string, error)
 
+	// jobTerminal holds the test seams for the sandbox.runtime: job
+	// terminal (job_terminal.go); zero values take in-cluster defaults.
+	jobTerminal jobTerminalDeps
+
 	kickBrainstormSendKickFn func(name, msg string) error
 	kickBrainstormRestartFn  func(ctx context.Context, name, prompt string) error
 	kickBrainstormDoneFn     func()
@@ -867,6 +871,10 @@ type FrontendAgent struct {
 	// SPA reads health from here instead of State, which is "idle" between
 	// kicks for an agent that has no session to be down.
 	SandboxRun      *FrontendSandboxRun `json:"sandboxRun,omitempty"`
+	// SandboxRuntime is the effective sandbox.runtime for a sandboxed agent
+	// ("podman" or "job"); the SPA routes "▶ terminal" to the Job pod log
+	// viewer for "job" (hivecommons/hive#14798). Empty when not sandboxed.
+	SandboxRuntime string `json:"sandboxRuntime,omitempty"`
 	LastError       string              `json:"lastError,omitempty"`
 	StallNudges     int                 `json:"stallNudges,omitempty"`
 	StallRecoveries int                 `json:"stallRecoveries,omitempty"`
diff --git a/src/pkg/dashboard/static/index.html b/src/pkg/dashboard/static/index.html
index 2f1f6c6b7d..8049225f8b 100644
--- a/src/pkg/dashboard/static/index.html
+++ b/src/pkg/dashboard/static/index.html
@@ -11159,7 +11159,7 @@ 

Where to get help

? cadenceOffAgentActionHtml(a) : ``} ${agentPowerSwitchHtml(a)} - ${sessionChip(a, '▶ terminal', `▶ terminal`)} + ${sessionChip(a, '▶ terminal', `▶ terminal`)} ${sessionChip(a, '📄 full log', `📄 full log`)} ${sessionChip(a, '📋 log text', `📋 log text`)} 🕘 past kicks @@ -20161,12 +20161,29 @@

All labels

const TTYD_PORT = 7681; const TERMINAL_ASSERTION_RENEW_PATH = '/api/terminal/assertion/renew'; const TERMINAL_HANDOFF_PATH = '/api/terminal/handoff'; - function terminalUrl(agentName) { - const session = TMUX_SESSION_PREFIX + agentName; + /* sandbox.runtime: job agents (#14798) run each kick as a Kubernetes Job + in another pod, so there is no hive- tmux session for ttyd to + attach to. Their terminal is the read-only Job pod log viewer, served + by the Go server under the same /terminal prefix so openTerminal()'s + handoff code and assertion cookie apply unchanged. */ + const JOB_SANDBOX_RUNTIME = 'job'; + function agentUsesJobTerminal(a) { + return !!a && a.sandboxRuntime === JOB_SANDBOX_RUNTIME; + } + function terminalUrl(agentName, sandboxRuntime) { const proto = window.location.protocol; const host = window.location.host; + if (sandboxRuntime === JOB_SANDBOX_RUNTIME) { + return `${proto}//${host}/terminal/job/${encodeURIComponent(agentName)}`; + } + const session = TMUX_SESSION_PREFIX + agentName; return `${proto}//${host}/terminal/?arg=${encodeURIComponent(session)}`; } + function terminalLinkTitle(a, tmuxTitle) { + return agentUsesJobTerminal(a) + ? 'Stream the log of this agent\'s sandbox Job pod (read-only: it runs as a Kubernetes Job, not a tmux session)' + : tmuxTitle; + } /* The hosted fleet has moved apex once already (hive.kubestellar.io -> hive.hivecommons.dev) and spokes are also served at vanity hostnames, so a single hardcoded suffix silently turns assertion renewal into a no-op @@ -21019,7 +21036,7 @@

All labels

const agentSpanHandle = ``; const disabledEnableBtn = isDisabled ? `` : ''; const historyLink = `🕘 past kicks`; - const liveSessionActions = `${sessionChip(a, '▶ terminal', `▶ terminal`)} ${sessionChip(a, '📄 full log', `📄 full log`)} ${historyLink}`; + const liveSessionActions = `${sessionChip(a, '▶ terminal', `▶ terminal`)} ${sessionChip(a, '📄 full log', `📄 full log`)} ${historyLink}`; const sessionActions = isPoweredOff ? `${historyLink}` : isDisabled diff --git a/src/pkg/dashboard/status_builder.go b/src/pkg/dashboard/status_builder.go index fc509023a9..ed5d91ea41 100644 --- a/src/pkg/dashboard/status_builder.go +++ b/src/pkg/dashboard/status_builder.go @@ -1155,6 +1155,7 @@ func buildAgentsWithHidden(statuses map[string]*crux.Process, cfg *config.Config OnDemand: agentCfg.OnDemand, Sandboxed: agentCfg.SandboxEnabled(cfg.AgentSandbox), SandboxRun: sandboxRun, + SandboxRuntime: effectiveSandboxRuntime(agentCfg, cfg), Session: name, State: string(proc.State), Starting: proc.Starting && proc.State != crux.StateRunning, @@ -1445,6 +1446,7 @@ func buildMissingRuntimeAgent(name string, agentCfg config.AgentConfig, cfg *con ReplicaCount: agentCfg.ReplicaCount, OnDemand: onDemand, Sandboxed: agentCfg.SandboxEnabled(cfg.AgentSandbox), + SandboxRuntime: effectiveSandboxRuntime(agentCfg, cfg), Session: name, State: string(crux.StateStopped), Busy: "idle", @@ -3469,3 +3471,13 @@ func formatSessionAge(startedAt *time.Time, now time.Time) string { } return age.Round(time.Minute).String() } + +// effectiveSandboxRuntime is the agent's resolved sandbox.runtime, or "" +// when the agent is not sandboxed (a non-sandboxed agent has a tmux +// terminal whatever the global runtime says). +func effectiveSandboxRuntime(agentCfg config.AgentConfig, cfg *config.Config) string { + if !agentCfg.SandboxEnabled(cfg.AgentSandbox) { + return "" + } + return agentCfg.SandboxRuntime(cfg.AgentSandbox) +} diff --git a/src/pkg/dashboard/terminal_proxy.go b/src/pkg/dashboard/terminal_proxy.go index f793154bef..5eeb047207 100644 --- a/src/pkg/dashboard/terminal_proxy.go +++ b/src/pkg/dashboard/terminal_proxy.go @@ -122,4 +122,8 @@ func (s *Server) registerTerminalProxy() { } s.mux.Handle("GET "+terminalPathPrefix, proxy) s.mux.Handle("GET "+terminalPathPrefix+"/", proxy) + // sandbox.runtime: job agents have no tmux session to proxy to; their + // terminal is the Job pod log viewer, served under the same prefix so the + // terminal handoff and assertion cookie apply unchanged (#14798). + s.registerJobTerminal() } From f280ceb6eb30e45c58c83348b2934869f4f78530 Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Wed, 28 Oct 2026 00:07:44 -0400 Subject: [PATCH 2/4] =?UTF-8?q?=F0=9F=8C=B1=20dashboard:=20drop=20unused?= =?UTF-8?q?=20jobTerminalDeps.now,=20move=20changelog=20fragment=20to=20re?= =?UTF-8?q?po=20root?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andrew Anderson --- .../added-14798-job-runtime-terminal.md | 0 src/pkg/dashboard/job_terminal.go | 2 -- 2 files changed, 2 deletions(-) rename {src/changelog.d => changelog.d}/added-14798-job-runtime-terminal.md (100%) diff --git a/src/changelog.d/added-14798-job-runtime-terminal.md b/changelog.d/added-14798-job-runtime-terminal.md similarity index 100% rename from src/changelog.d/added-14798-job-runtime-terminal.md rename to changelog.d/added-14798-job-runtime-terminal.md diff --git a/src/pkg/dashboard/job_terminal.go b/src/pkg/dashboard/job_terminal.go index a1fb85819c..7434279171 100644 --- a/src/pkg/dashboard/job_terminal.go +++ b/src/pkg/dashboard/job_terminal.go @@ -80,8 +80,6 @@ type jobTerminalDeps struct { reader jobPodLogReader workspaceRoot string pollInterval time.Duration - // now is used for the "written at" stamp on a persisted transcript. - now func() time.Time } func (s *Server) registerJobTerminal() { From f0b1dd0c501cde30312b47ea2a156502d44879c7 Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Wed, 28 Oct 2026 21:34:43 -0400 Subject: [PATCH 3/4] =?UTF-8?q?=F0=9F=8C=B1=20dashboard:=20rebase=20job-ru?= =?UTF-8?q?ntime=20terminal=20onto=20v5,=20cover=20transcript=20edge=20cas?= =?UTF-8?q?es?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Resolve conflicts with the sandbox-health and session-age status fields, refresh api-reference citations, and add LatestTranscript tests for the directory-skip and equal-mtime tie-break branches so crux/sandbox stays above its 98% coverage floor. Signed-off-by: Andrew Anderson --- src/crux/sandbox/naming_test.go | 38 +++++++++++++++++++++++++++++++++ src/pkg/dashboard/server.go | 14 ++++++------ 2 files changed, 45 insertions(+), 7 deletions(-) diff --git a/src/crux/sandbox/naming_test.go b/src/crux/sandbox/naming_test.go index ab7e246fc0..6649b1ef36 100644 --- a/src/crux/sandbox/naming_test.go +++ b/src/crux/sandbox/naming_test.go @@ -90,3 +90,41 @@ func TestTranscriptExitCode(t *testing.T) { t.Fatal("empty transcript must report ok=false") } } + +func TestLatestTranscriptSkipsDirectoriesAndBreaksModTimeTies(t *testing.T) { + root := t.TempDir() + mk := func(dir string) string { + p := filepath.Join(root, dir, filepath.FromSlash(TranscriptRelPath)) + if err := os.MkdirAll(filepath.Dir(p), 0o700); err != nil { + t.Fatal(err) + } + return p + } + // A directory where the transcript file should be is not a transcript; + // when it is the only candidate the agent has no run yet. + if err := os.MkdirAll(mk("deps-1"), 0o700); err != nil { + t.Fatal(err) + } + if got, ok := LatestTranscript(root, "deps"); ok { + t.Fatalf("directory must not count as a transcript, got %q", got) + } + + // Two transcripts with identical modification times: the lexically + // greater path (the later unixnano suffix) wins deterministically. + mod := time.Date(2026, 10, 27, 12, 0, 0, 0, time.UTC) + var paths []string + for _, dir := range []string{"deps-20", "deps-10"} { + p := mk(dir) + if err := os.WriteFile(p, []byte("run"), 0o600); err != nil { + t.Fatal(err) + } + if err := os.Chtimes(p, mod, mod); err != nil { + t.Fatal(err) + } + paths = append(paths, p) + } + got, ok := LatestTranscript(root, "deps") + if !ok || got != paths[0] { + t.Fatalf("LatestTranscript = %q, %v; want %q", got, ok, paths[0]) + } +} diff --git a/src/pkg/dashboard/server.go b/src/pkg/dashboard/server.go index 1544769dcb..795c2cff67 100644 --- a/src/pkg/dashboard/server.go +++ b/src/pkg/dashboard/server.go @@ -870,16 +870,16 @@ type FrontendAgent struct { // from it (sandbox_health.go). Present only for sandboxed agents; the // SPA reads health from here instead of State, which is "idle" between // kicks for an agent that has no session to be down. - SandboxRun *FrontendSandboxRun `json:"sandboxRun,omitempty"` + SandboxRun *FrontendSandboxRun `json:"sandboxRun,omitempty"` // SandboxRuntime is the effective sandbox.runtime for a sandboxed agent // ("podman" or "job"); the SPA routes "▶ terminal" to the Job pod log // viewer for "job" (hivecommons/hive#14798). Empty when not sandboxed. - SandboxRuntime string `json:"sandboxRuntime,omitempty"` - LastError string `json:"lastError,omitempty"` - StallNudges int `json:"stallNudges,omitempty"` - StallRecoveries int `json:"stallRecoveries,omitempty"` - ActionNudges int `json:"actionNudges,omitempty"` - TransientNudges int `json:"transientNudges,omitempty"` + SandboxRuntime string `json:"sandboxRuntime,omitempty"` + LastError string `json:"lastError,omitempty"` + StallNudges int `json:"stallNudges,omitempty"` + StallRecoveries int `json:"stallRecoveries,omitempty"` + ActionNudges int `json:"actionNudges,omitempty"` + TransientNudges int `json:"transientNudges,omitempty"` // SessionRssMb is the resident memory of the agent's CLI process tree // (MiB) and SessionAge how long the current CLI session has been up, // both sampled on the health tick (#14842). SessionRecycles counts From 8495dee31b5de77466fdb9b7f3ad35752a09609c Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Wed, 28 Oct 2026 22:19:38 -0400 Subject: [PATCH 4/4] =?UTF-8?q?=F0=9F=93=96=20docs:=20refresh=20api-refere?= =?UTF-8?q?nce=20citations=20after=20rebase?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andrew Anderson --- src/docs/api-reference.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/src/docs/api-reference.md b/src/docs/api-reference.md index 8811ea8e02..545be643cc 100644 --- a/src/docs/api-reference.md +++ b/src/docs/api-reference.md @@ -13,17 +13,17 @@ History point limits, timestamp cutoffs, incremental cost reads and ETag/304 beh | `GET` | `/api/version` | Dashboard auth/session | Build/version metadata; includes `upgradeMarker` (`target`, `current`, `attempts`, `maxAttempts`, `failed`, `requestedAt`, `lastError`) while a self-upgrade is in flight or has failed ([#6765](https://github.com/hivecommons/hive/issues/6765)), the hub-delivered `upgradePolicy` (`hub_managed`, `spoke_managed`, `schedule`, `schedule_hour`, `schedule_timezone`, `schedule_weekday`, `paused`, `branch`, `channel`, `target_sha`, `target_resolved`, `armed_target`, and `next_update_at` — the hub's RFC3339 ETA for the next promotion into the `stable` channel, omitted when unknown ([#10256](https://github.com/hivecommons/hive/issues/10256))) when available, and an `autoUpdate` object (`enabled`, `state` — one of `disabled`/`up_to_date`/`behind`/`retrying`/`failed`/`unknown` — `healthy`, `period`, `targetBranch`, `targetCommit`, `currentCommit`, `commitsBehind`, `lastAttemptAt`, `lastError`, `detail`, and `nextUpdateAt` — the hub's RFC3339 ETA for the next update, omitted when unknown, disabled or paused ([#10257](https://github.com/hivecommons/hive/issues/10257))) that never reports a failed or unknown update as healthy ([#6962](https://github.com/hivecommons/hive/issues/6962), [#6963](https://github.com/hivecommons/hive/issues/6963)) | `pkg/dashboard/api.go:43` | | `GET` | `/api/version/release-notes` | Dashboard auth/session | Changelog gap between two revisions: `?from=&to=` returns `{from:{sha,version?}, to:{sha,ref,version?}, sections:[{version,date,categories:{added,changed,fixed,security,deprecated}}], unreleased?, truncated, source, error?}` — the `CHANGELOG.md` release sections present at `to` and absent at `from`, newest first, plus (when `to` is not a release tag) the `changelog.d/` fragments new at `to` under an `Unreleased (in this build)` section. Fetch failures return `source: "unavailable"` with `error` rather than an error status; results are cached per (from, to) for an hour ([#11065](https://github.com/hivecommons/hive/issues/11065)) | `pkg/dashboard/api.go:44` | | `POST` | `/api/release-channel` | Owner only | Hosted spoke self-service release-channel selector; relays `stable`/`candidate`/`edge` to the hub's existing switch-branch endpoint with the spoke dashboard-token proof, and reports the requested channel as pending until the Deployment image lands | `pkg/dashboard/api.go:65` | -| `GET` | `/api/health` | Public | Basic health probe | `pkg/dashboard/server.go:1565` | -| `GET` | `/api/health/deep` | Public | Deep health probe | `pkg/dashboard/server.go:1566` | -| `GET` | `/api/livez` | Public | Kubernetes liveness probe | `pkg/dashboard/server.go:1567` | -| `GET` | `/metrics` | Registered only when `HIVE_METRICS_ENABLED`; requires `Authorization: ****** (403 if the token is unset) | Prometheus metrics | `pkg/dashboard/server.go:1573` | -| `GET` | `/api/status` | Dashboard auth/session | Dashboard aggregate status; `labelPresets[]` (`{key,label,description,labels[],states[]}`) lists the built-in label-filter presets for the Projects cards, led by `needs-human` whose `labels[]` are the effective hard-suppress labels plus `needs-signal`, the hold labels, `stage/071-needs-author` and the reporter-trust awaiting label (#12172); accepts `?fields=a,b` for top-level selection and `?omit=repos` to drop heavy sections, and honors `Accept-Encoding: gzip`; `agents[]` includes busy-pane visibility fields (`kicksUndeliverable`, `busySince`, `lastTranscriptActivity`, `condition`, `conditionMessage`) when a Working pane cannot accept kicks; a working agent also carries `agents[].run` — the live per-run line (#14576): `{since, elapsedS, costUSD, tokens, priced, tests, filesChanged}`, the estimated spend/tokens since the kick was delivered (`lastKickAt`, falling back to `busySince`) (delta of the token collector's per-agent cumulative figure; `priced:false` when the agent has none yet), the last visible test-runner result (`pass`/`fail`/empty) and the last `N files changed` git summary (`-1` when none) parsed from the captured pane; top-level `fleetRun` `{running, hourUSD, hourPriced}` is the governor strip's `running N · $X this hour` figure; `sla` (fleet) and `repos[].sla` (per repo) carry the Delivery SLA block derived from the lifecycle timeline with no extra GitHub calls: `windows.{7d,30d}.{open_to_triage,triage_to_start,start_to_pr,pr_to_merge,open_to_merge}` as `{p50_h,p95_h,n}` (hours, nearest-rank), `history[]` of up to 30 daily buckets `{day,start_to_pr_p50,pr_to_merge_p50,open_to_merge_p50,n_started,n_pr,n_merged}` persisted under `/data/sla-history.json`, `stale_in_progress[]` (`{number,repo,started_at,age_h,agent}` — issues carrying `hive/in-progress` longer than the agent claim TTL with no linked PR), `stale_count`, `merged_7d`, `claim_ttl_s` and, on the fleet block, the effective `targets` (`start_to_pr_h`, `pr_to_merge_h`, `open_to_merge_h`); `staleSince` and `repos[].countsStale` / `countsStaleSince` mark totals served from last-good figures — the previous enumeration (#13382) or the ForgeState cache's last-good counts (#13376) | `pkg/dashboard/server.go:1578` | -| `GET` | `/api/status/summary` | Dashboard auth/session | Compact agent/governor/budget status summary for pollers; honors `Accept-Encoding: gzip` | `pkg/dashboard/server.go:1579` | -| `GET` | `/api/overview/issues.csv` | Dashboard auth/session | Cached Overview issue-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1580` | -| `GET` | `/api/overview/issues.json` | Dashboard auth/session | Cached Overview issue-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1581` | -| `GET` | `/api/overview/prs.csv` | Dashboard auth/session | Cached Overview PR-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1582` | -| `GET` | `/api/overview/prs.json` | Dashboard auth/session | Cached Overview PR-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1583` | -| `GET` | `/api/events` | Dashboard auth/session | Server-sent event stream | `pkg/dashboard/server.go:1584` | +| `GET` | `/api/health` | Public | Basic health probe | `pkg/dashboard/server.go:1573` | +| `GET` | `/api/health/deep` | Public | Deep health probe | `pkg/dashboard/server.go:1574` | +| `GET` | `/api/livez` | Public | Kubernetes liveness probe | `pkg/dashboard/server.go:1575` | +| `GET` | `/metrics` | Registered only when `HIVE_METRICS_ENABLED`; requires `Authorization: ****** (403 if the token is unset) | Prometheus metrics | `pkg/dashboard/server.go:1581` | +| `GET` | `/api/status` | Dashboard auth/session | Dashboard aggregate status; `labelPresets[]` (`{key,label,description,labels[],states[]}`) lists the built-in label-filter presets for the Projects cards, led by `needs-human` whose `labels[]` are the effective hard-suppress labels plus `needs-signal`, the hold labels, `stage/071-needs-author` and the reporter-trust awaiting label (#12172); accepts `?fields=a,b` for top-level selection and `?omit=repos` to drop heavy sections, and honors `Accept-Encoding: gzip`; `agents[]` includes busy-pane visibility fields (`kicksUndeliverable`, `busySince`, `lastTranscriptActivity`, `condition`, `conditionMessage`) when a Working pane cannot accept kicks; a working agent also carries `agents[].run` — the live per-run line (#14576): `{since, elapsedS, costUSD, tokens, priced, tests, filesChanged}`, the estimated spend/tokens since the kick was delivered (`lastKickAt`, falling back to `busySince`) (delta of the token collector's per-agent cumulative figure; `priced:false` when the agent has none yet), the last visible test-runner result (`pass`/`fail`/empty) and the last `N files changed` git summary (`-1` when none) parsed from the captured pane; top-level `fleetRun` `{running, hourUSD, hourPriced}` is the governor strip's `running N · $X this hour` figure; `sla` (fleet) and `repos[].sla` (per repo) carry the Delivery SLA block derived from the lifecycle timeline with no extra GitHub calls: `windows.{7d,30d}.{open_to_triage,triage_to_start,start_to_pr,pr_to_merge,open_to_merge}` as `{p50_h,p95_h,n}` (hours, nearest-rank), `history[]` of up to 30 daily buckets `{day,start_to_pr_p50,pr_to_merge_p50,open_to_merge_p50,n_started,n_pr,n_merged}` persisted under `/data/sla-history.json`, `stale_in_progress[]` (`{number,repo,started_at,age_h,agent}` — issues carrying `hive/in-progress` longer than the agent claim TTL with no linked PR), `stale_count`, `merged_7d`, `claim_ttl_s` and, on the fleet block, the effective `targets` (`start_to_pr_h`, `pr_to_merge_h`, `open_to_merge_h`); `staleSince` and `repos[].countsStale` / `countsStaleSince` mark totals served from last-good figures — the previous enumeration (#13382) or the ForgeState cache's last-good counts (#13376) | `pkg/dashboard/server.go:1586` | +| `GET` | `/api/status/summary` | Dashboard auth/session | Compact agent/governor/budget status summary for pollers; honors `Accept-Encoding: gzip` | `pkg/dashboard/server.go:1587` | +| `GET` | `/api/overview/issues.csv` | Dashboard auth/session | Cached Overview issue-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1588` | +| `GET` | `/api/overview/issues.json` | Dashboard auth/session | Cached Overview issue-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1589` | +| `GET` | `/api/overview/prs.csv` | Dashboard auth/session | Cached Overview PR-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1590` | +| `GET` | `/api/overview/prs.json` | Dashboard auth/session | Cached Overview PR-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1591` | +| `GET` | `/api/events` | Dashboard auth/session | Server-sent event stream | `pkg/dashboard/server.go:1592` | | `GET` | `/api/swarm` | Dashboard auth/session | Current swarm status: display name, duration, active repo, expiry, persisted prep metrics when available, and idle-unlock fields. | `pkg/dashboard/swarm.go:310` | | `POST` | `/api/swarm` | Owner only | Start a 24h repo swarm for a configured repo, returning 409 when another swarm is active and 423 when a previous swarm keeps the next swarm locked until enough agents are idle unless body `{"repo":"owner/name","force":true}` is used; saves the active record before repo prep, persists prep metrics, and announces the start to Discord when configured. | `pkg/dashboard/swarm.go:311` | | `DELETE` | `/api/swarm` | Owner only | End the active swarm, score issues closed and PRs merged in the window, append it to history, and announce the result to Discord when configured. | `pkg/dashboard/swarm.go:312` | @@ -66,7 +66,7 @@ History point limits, timestamp cutoffs, incremental cost reads and ETag/304 beh | Method | Path | Auth | Purpose | Source | |---|---|---|---|---| | `GET` | `/api/style` | Public | Sanitized custom dashboard CSS | `pkg/dashboard/api.go:45` | -| `GET` | `/branding/custom.css` | Dashboard auth/session | Operator branding stylesheet override, read per request (see [branding](branding.md)) | `pkg/dashboard/server.go:1645` | +| `GET` | `/branding/custom.css` | Dashboard auth/session | Operator branding stylesheet override, read per request (see [branding](branding.md)) | `pkg/dashboard/server.go:1653` | | `GET` | `/api/snapshot/frame-ancestors` | Public | Snapshot framing allowlist | `pkg/dashboard/api.go:78` | | `GET` | `/api/snapshot` | Public | Snapshot data | `pkg/dashboard/api.go:79` | | `GET` | `/snapshot` | Public | Public read-only snapshot page | `pkg/dashboard/api.go:80` | @@ -94,9 +94,9 @@ History point limits, timestamp cutoffs, incremental cost reads and ETag/304 beh | `GET` | `/api/openrouter/models` | Dashboard auth/session | Open Router Models | `pkg/dashboard/openrouter.go:47` | | `GET` | `/api/openrouter/credit` | Dashboard auth/session | Open Router Credit | `pkg/dashboard/openrouter.go:48` | | `GET` | `/openrouter/callback` | Public | Open Router Callback | `pkg/dashboard/openrouter.go:49` | -| `POST` | `/api/github-app/recheck` | Dashboard auth/session | GitHub App Recheck | `pkg/dashboard/server.go:1585` | -| `POST` | `/api/github-app/install-clicked` | Dashboard auth/session | GitHub App Install Clicked | `pkg/dashboard/server.go:1586` | -| `GET` | `/gh-setup` | Public | GitHub App Setup Callback | `pkg/dashboard/server.go:1587` | +| `POST` | `/api/github-app/recheck` | Dashboard auth/session | GitHub App Recheck | `pkg/dashboard/server.go:1593` | +| `POST` | `/api/github-app/install-clicked` | Dashboard auth/session | GitHub App Install Clicked | `pkg/dashboard/server.go:1594` | +| `GET` | `/gh-setup` | Public | GitHub App Setup Callback | `pkg/dashboard/server.go:1595` | ## Configuration @@ -595,9 +595,9 @@ always resolved server-side from the validated token. | `POST` | `/api/hives/{id}/heartbeat` | Dashboard auth/session | Hives Heartbeat | `pkg/dashboard/api_contribute.go:275` | | `DELETE` | `/api/hives/{id}` | Owner only | Hives Delete | `pkg/dashboard/api_contribute.go:276` | | `POST` | `/api/hives/onboard` | Dashboard auth/session | Hives Onboard | `pkg/dashboard/api_contribute.go:277` | -| `GET` | `/sso` | Public | SSO | `pkg/dashboard/server.go:1592` | -| `GET` | `/terminal/job/{name}` | Terminal handoff (owner / `terminal` role) | Read-only Job pod log viewer for an agent whose effective `sandbox.runtime` is `job` ([#14798](https://github.com/hivecommons/hive/issues/14798)); the SPA's ▶ terminal link lands here instead of the ttyd tmux pane. `404` unknown agent, `409` when the agent is not a job-runtime sandbox, `503` when no config is loaded | `pkg/dashboard/job_terminal.go:91` | -| `GET` | `/terminal/job/{name}/stream` | Terminal handoff (owner / `terminal` role) | `text/plain` line stream behind the viewer: follows the newest Job pod for the agent while it runs (polls while `Pending`), ends with the container exit code, and when no pod exists shows the newest persisted sandbox transcript plus its recorded exit code, or a "no sandbox run yet" line. Secrets are scrubbed like the agent log. Same error codes as the page | `pkg/dashboard/job_terminal.go:92` | +| `GET` | `/sso` | Public | SSO | `pkg/dashboard/server.go:1600` | +| `GET` | `/terminal/job/{name}` | Terminal handoff (owner / `terminal` role) | Read-only Job pod log viewer for an agent whose effective `sandbox.runtime` is `job` ([#14798](https://github.com/hivecommons/hive/issues/14798)); the SPA's ▶ terminal link lands here instead of the ttyd tmux pane. `404` unknown agent, `409` when the agent is not a job-runtime sandbox, `503` when no config is loaded | `pkg/dashboard/job_terminal.go:88` | +| `GET` | `/terminal/job/{name}/stream` | Terminal handoff (owner / `terminal` role) | `text/plain` line stream behind the viewer: follows the newest Job pod for the agent while it runs (polls while `Pending`), ends with the container exit code, and when no pod exists shows the newest persisted sandbox transcript plus its recorded exit code, or a "no sandbox run yet" line. Secrets are scrubbed like the agent log. Same error codes as the page | `pkg/dashboard/job_terminal.go:89` | ## Hub SaaS