Scheduler Agent Management Guide

Monitor the automation runners (gissue schedulers and similar background agents) registered per project (CSN): online/offline status, run status and history, and live logs — all from one admin screen.

🕐 Go to Scheduler Agent Management →

📋 Overview

Scheduler Agent Management shows every automation agent registered against the currently selected project (CSN) — for example gissue's hourly scheduler and interactive Claude Code sessions. Unlike /admin/catquest (which visualizes giip issues as cats), this screen is an operations dashboard for the agents that run automation jobs: is each agent alive, is its current run healthy, and where can I read its logs.

🎨 Status colors

Two independent status signals are shown per agent — don't confuse them.

Identity status (small dot next to the agent name)

Reflects whether the agent process itself is reachable (tSchedulerAgent.status), independent of any single run.

Color	Status	Meaning
🟢 Green	online	Agent is reachable and reporting in
🔴 Red	error	Agent reported an error state
⚪ Gray (slate-400)	offline	Agent is not currently reachable
⚪ Light gray (slate-300)	unknown	No status reported yet

Run status (badge in the Status column)

Reflects the most recent scheduler run (currentStatus), plus a stale detector.

Color	Label shown	Condition	Meaning
🟢 Green	RUNNING	currentStatus = RUNNING and not stale	Currently executing normally
🔴 Red	STALE	currentStatus = RUNNING and isStale = true	Marked running but heartbeat has gone quiet too long — looks like a hung/zombie run
🟠 Orange	STALE	currentStatus = STALE (explicit)	Backend flagged the run itself as stale
⚪ Gray	ENDED	currentStatus = ENDED	Finished (success or a controlled stop)
⚪ Gray	(raw value)	anything else / no run yet	Unknown / no data

In the Run History modal (see below), a completed run can also show FAILED in red — a run that ended with an error, distinct from an ENDED (clean finish) or a stale/timed-out run.

🔍 Screen layout

1. Header

• Back arrow (←) to /admin/catquest.
• Refresh: reloads the agent list for the current CSN.

2. Open Interactive Sessions

A separate card (only shown when at least one exists) listing active claude_interactive_session agents — i.e. interactive Claude Code sessions currently registered as running on a host. Each row shows the session name, host, last-communication time, and an "Open session" link when a session URL was registered in the agent's capabilities.

3. Agent list (table)

One row per scheduler agent, with:

• Name — identity-status dot, agent name, OS/agent-type/version badges, lssn (linked server), a truncated capabilities summary, and the last recorded error (if any).
• Host — hostIdentifier.
• Windows Task — the Windows Task Scheduler task name that runs this agent, if applicable.
• Project — project name.
• Active — ON/OFF badge (isActive).
• Last Comm — last heartbeat/communication timestamp.
• Status — the run-status badge described above, plus the current phase text if one is reported.

A stats footer totals Processed / Skipped / Failed counts across all listed agents.

4. Run History

Below the table, a "View History" card lists every agent again; clicking History on a row opens a modal listing that agent's recent runs — execution mode, status (including FAILED), start/end time, duration, processed/skipped/failed counts, phase, and a summary.

5. Live Log Viewer

A two-pane live tailing view:

• Left (agent → stream tree): agents are grouped, each expandable to its known log streams (a stream is identified by streamKey, has a streamType, and a rotation generation number). An agent shows online/offline based on how recently it last communicated.
• Right (log stream card): once you pick a stream, its recent log lines are shown and refreshed for live tailing.

💡 Notes

• This is an admin screen. Access requires AdminGuard clearance (uLevel ≥ 70).
• The agent list, run history, and log catalog are all scoped to the session's current CSN — switch project from the top navigation to inspect a different project's agents.
• Loading data requires an authenticated session (AK token); if requests start failing with an auth error, log in again and press Refresh.
• This page is a distinct tool from /admin/catquest — reaching it via the CatQuest screen's navigation does not mean it shares CatQuest's cat-visualization data or audience.

Troubleshooting

Symptom	Cause	Resolution
"Authentication required" error	No AK/session token found	Log in again, then reload the page.
Agent list is empty	No scheduler agents registered for this CSN, or wrong project selected	Confirm the correct project (CSN) is selected in the top navigation.
A row shows STALE in red while you know the job is idle	The agent stopped sending heartbeats mid-run (isStale = true) without transitioning to ENDED — likely a crashed/killed process	Check the agent host directly; once it restarts and reports again, the badge updates.
Live Log Viewer shows "No streams yet."	The agent hasn't registered any log streams yet, or hasn't produced output since the catalog last refreshed	Wait for the agent's next run, or confirm the agent process is actually writing logs.
"Open session" link missing under Open Interactive Sessions	No sessionUrl was included in that agent's registered capabilities	Nothing to open — the interactive session didn't register a reachable URL.

---

Version: 1.0 Last updated: 2026-08-29 Source file: giipv3/public/help/catquest-schedulers.en.md