terminalstatus

package

v0.37.0 Latest Latest Go to latest Published: Nov 5, 2026 License: MIT Imports: 3 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/hadron-memory/hadron-cli

Links

Open Source Insights

Documentation ¶

Overview ¶

Package terminalstatus is the `terminal-status@1` output contract of `hadron orca terminal status` (cli#1187) and the dark rule behind it.

Nothing here knows about Orca: the team health sweep (#1181) consumes the JSON this package defines and never imports a classifier, and a later terminal environment would ship its own command emitting the same contract. The closed lists below match the server's Worker.terminal reason enum (hadron-server#2771).

Index ¶

Constants
func IsDark(now time.Time, subscribed []Ticker, due []DueTick) (bool, string)
type DueTick
type Prompt
- func (p Prompt) Valid() bool
type Reason
- func (r Reason) Valid() bool
type Result
- func (r Result) MarshalJSON() ([]byte, error)
type Status
- func (s Status) Valid() bool
type Ticker

Constants ¶

View Source

const Contract = "terminal-status@1"

Contract names and versions the JSON this package marshals.

Variables ¶

This section is empty.

Functions ¶

func IsDark ¶

func IsDark(now time.Time, subscribed []Ticker, due []DueTick) (bool, string)

IsDark is true when a ticker the worker subscribes to owed it a turn at least one FASTEST-subscribed-ticker interval ago and the tick is still unanswered. Only due-wake evidence counts, so the answer is the same for a harness whose screen yields no lastTurnAt. A worker with nothing due, or no subscription, is never dark. The detail names the oldest overdue tick.

Types ¶

type DueTick ¶

type DueTick struct {
	TickerID   string
	TickerName string
	DueAt      time.Time
}

DueTick is the oldest unacknowledged tick of one ticker the server still offers the worker: its wake reason's tickDueAt (hadron-server#2790, hadron-cli#1216), per ticker even in a wake merged with a mention, a task or another ticker's tick. A turn answers and acknowledges its wake, so an old unanswered tick is the evidence that no turn happened. Neither DueWake.anchorAt (the oldest reason of any kind) nor the ticker's lastTickAt (its newest tick: with a 5-minute ticker and 5 minutes of slack never old enough, #1181) is an input.

type Prompt ¶

type Prompt string

Prompt is the terminal-level fact, separate from Status.

const (
	PromptEmpty    Prompt = "empty"
	PromptNotEmpty Prompt = "not_empty"
	PromptMenu     Prompt = "menu"
	PromptUnknown  Prompt = "unknown"
)

func (Prompt) Valid ¶

func (p Prompt) Valid() bool

Valid reports whether p is on the closed list.

type Reason ¶

type Reason string

Reason is a stable machine code, set only for Locked and Dark.

const (
	Unrecognized       Reason = "unrecognized"
	MenuOrQuestion     Reason = "menu_or_question"
	NoTurnForDueTicker Reason = "no_turn_for_due_ticker"
	NoTerminal         Reason = "no_terminal"
	BareShell          Reason = "bare_shell"
	NoAgent            Reason = "no_agent"
)

func (Reason) Valid ¶

func (r Reason) Valid() bool

Valid reports whether r is on the closed list.

type Result ¶

type Result struct {
	Worker     string
	Terminal   string
	Status     Status
	Prompt     Prompt
	Reason     *Reason
	LastTurnAt *time.Time
	CheckedAt  time.Time
	Detail     string
}

Result is one worker's terminal status, the JSON element of the contract. Detail is local only: it is never marshalled, so a sweep can never send screen text anywhere.

func (Result) MarshalJSON ¶

func (r Result) MarshalJSON() ([]byte, error)

MarshalJSON writes the documented shape: every key present, nulls for the absent ones, no detail.

type Status ¶

type Status string

Status is exactly one of busy | idle | locked | dark.

const (
	// Idle: an empty prompt, safe to push one line.
	Idle Status = "idle"
	// Busy: a turn is running.
	Busy Status = "busy"
	// Locked: the agent cannot take work for an identifiable (or, fail
	// closed, unrecognized) reason.
	Locked Status = "locked"
	// Dark: a broken state, a ticker owed this worker a turn and none came,
	// or there is no live agent terminal at all.
	Dark Status = "dark"
)

func (Status) Valid ¶

func (s Status) Valid() bool

Valid reports whether s is on the closed list.

type Ticker ¶

type Ticker struct {
	ID       string
	Name     string
	Interval time.Duration
}

Ticker is one ticker the worker is actively subscribed to.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL