@rse/ase 1.0.7 → 2.0.0

package/dst/man/ase-agent-qualifier.1

@@ -0,0 +1,214 @@
+.TH "ASE-AGENT-QUALIFIER" "1" "October 2026" "2.0.0" "Agentic Software Engineering (ASE)"
+.SH "NAME"
+\fBase-agent-qualifier\fR - Qualification Phase Agent
+.SH "SYNOPSIS"
+.P
+\fBase agent qualifier start\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB] \[lB]\fB-t\fR|\fB--tool\fR \fBclaude\fR|\fBcopilot\fR|\fBcodex\fR\[rB] \[lB]\fB-p\fR|\fB--parallel\fR \fInum\fR\[rB] \[lB]\fB-T\fR|\fB--timeout\fR \fIduration\fR\[rB] \[lB]\fB-o\fR|\fB--one-shot\fR\[rB] \[lB]\fB--agent-relay\fR \fIurl\fR\[rB] \[lB]\fB-r\fR|\fB--repo\fR \fIurl\fR\[rB] \[lB]\fB-d\fR|\fB--tempdir\fR \fIdir\fR\[rB] \[lB]\fB-m\fR|\fB--mode\fR \fBjudge\fR|\fBqualify\fR\[rB] \[lB]\fB--\fR\fIgroup\fR\fB-\fR\fIitem\fR \fIvalue\fR \[lB]...\[rB]\[rB] \[lB]\fB-f\fR|\fB--foreground\fR\[rB]
+.P
+\fBase agent qualifier status\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]
+.P
+\fBase agent qualifier log\fR \[lB]\fB-f\fR|\fB--follow\fR\[rB] \[lB]\fB-n\fR|\fB--lines\fR \fIn\fR\[rB] \[lB]\fB--name\fR \fIname\fR\[rB]
+.P
+\fBase agent qualifier stop\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]
+.SH "DESCRIPTION"
+.P
+\fBase agent qualifier\fR drives the \fBQualification\fR phase of the \fBenterprise\fR task lifecycle model (refused for any other model).
+.P
+It claims every task in the state \fBIMPLEMENTED\fR which is unassigned or assigned to the agent, which does not carry any tag \fBase-agent-qualifier\fR yet (i.e., without its verdict yet, so a task already carrying a verdict of the qualifier is never picked up again), and whose \fBAfter:\fR predecessors (and, for an explicit epic, its group members) are \fBQUALIFIED\fR or later, moves it into \fBQUALIFYING\fR, and reviews its \fBChangeset:\fR (or the configured \fBproject.task.default.changeset\fR) via the skill \fBase-repo-review\fR:
+.RS 0
+.IP \(bu 4
+\fBworktree\fR: The change set staged in its working copy, i.e., the Git worktree \fB.ase/worktree/\fR\fIid\fR of a parallel implementer if existing, else the working copy of the project.
+.IP \(bu 4
+\fBbranch:\fR\fIname\fR: The branch against its base, via \fBase-repo-review
+--branch\fR \fIname\fR.
+.IP \(bu 4
+\fBattachment:\fR\fIname\fR: The change set staged in a temporary Git worktree, detached at the \fBbase\fR commit of the attachment and removed afterwards.
+.RE 0
+.P
+The verdict \fBAPPROVE\fR resp. \fBREJECT\fR of the review (the last upper-case word after the label \fBREVIEW VERDICT\fR in the output of the successfully exited agent tool) is added as the tag \fBase-agent-qualifier:approve\fR resp. \fBase-agent-qualifier:reject\fR, while a failed or skipped review, which yields no verdict, adds the plain tag \fBase-agent-qualifier\fR.
+.P
+In the default mode \fBjudge\fR, the task is then put back into \fBIMPLEMENTED\fR for a human decision, while in mode \fBqualify\fR, it is put into \fBQUALIFIED\fR on the verdict \fBAPPROVE\fR, into \fBDECLINED\fR on the verdict \fBREJECT\fR, and back into \fBIMPLEMENTED\fR without a verdict. In both modes, the task is unassigned afterwards.
+.P
+On an interrupt, a task being processed is put back, untagged and with its previous assignee, into \fBIMPLEMENTED\fR. See \fBase-agent\fR(1) for the common mechanics of all agents.
+.SH "OPTIONS"
+.RS 0
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show usage information of \fBase agent qualifier\fR (or of the given sub-command) only.
+.RE 0
+.P
+All other options belong to the sub-commands (see \fBCOMMANDS\fR).
+.SH "COMMANDS"
+.RS 0
+.IP \(bu 4
+\fBase agent qualifier start\fR \[lB]\fIoptions\fR\[rB]: Start the qualifier agent in the background, logging into \fB.ase/agent/\fR\fIname\fR\fB.log\fR. The agent is validated and initialized (e.g., its agent tool is looked up and the task lifecycle model is checked) before the command returns (waiting up to 30 seconds), so a failing agent is reported together with the tail of its log. An agent of the same name already running is left alone. The options are:
+.RS 4
+.IP \(bu 4
+\[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]: The name of the agent (default: \fBqualifier\fR): up to 64 letters, digits, underscores, and dashes, starting with a letter or digit, other than the name of another agent kind, \fBrelay\fR, or \fBfleet\fR. It names the agent in its log lines (also in the shared processing log attachment \fBagent\fR), the \fBAssignee:\fR of the tasks it processes, its temporary directory, and its process files \fB.ase/agent/\fR\fIname\fR\fB.yaml\fR and \fB.ase/agent/\fR\fIname\fR\fB.log\fR.
+.sp
+Agents of the kind \fBqualifier\fR under different names form a pool, competing for the same tasks and processing them in parallel to each other.
+.IP \(bu 4
+\[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB]: The headless agent tool processing the tasks: \fBclaude\fR (\fIAnthropic Claude Code CLI\fR), \fBcopilot\fR (\fIGitHub Copilot CLI\fR), or \fBcodex\fR (\fIOpenAI Codex CLI\fR) (default: \fB$ASE_TOOL\fR, else \fBclaude\fR). Its command has to be found in \fB$PATH\fR.
+.IP \(bu 4
+\[lB]\fB-p\fR|\fB--parallel\fR \fInum\fR\[rB]: The maximum number of tasks processed in parallel by this agent (default: \fB1\fR), a positive integer.
+.IP \(bu 4
+\[lB]\fB-T\fR|\fB--timeout\fR \fIduration\fR\[rB]: The maximum duration of processing a task (the run of the agent tool), as \fInumber\fR \fIunit\fR (without a space) with \fIunit\fR \fBs\fR (seconds), \fBm\fR (minutes), or \fBh\fR (hours) (default: \fB60m\fR). A processing exceeding it is aborted and counts as failed.
+.IP \(bu 4
+\[lB]\fB-o\fR|\fB--one-shot\fR\[rB]: Terminate the agent, instead of observing for further tasks, once a check of the task store finds no dispatchable task while the agent processes no task anymore -- intended for CI contexts like GitHub Actions, and not allowed in a fleet. A task still waiting for its predecessors at that time is left for a later run. A check of the task store failing three times in a row then terminates the agent with a non-zero exit status (instead of being retried endlessly after a growing delay).
+.IP \(bu 4
+\[lB]\fB--agent-relay\fR \fIurl\fR\[rB]: The agent relay to pass the live presence of the agent to, as \fBase://\fR\fIaddr\fR\fB:\fR\fIport\fR\[lB]\fB/\fR\fItoken\fR\[rB] resp. \fBases://\fR\fIaddr\fR\fB:\fR\fIport\fR\[lB]\fB/\fR\fItoken\fR\[rB]\[lB]\fB?insecure\fR\[rB] for HTTPS (default: the configured \fBproject.relay.url\fR, else none). See \fBAGENT RELAY\fR in \fBase-agent\fR(1).
+.IP \(bu 4
+\[lB]\fB-r\fR|\fB--repo\fR \fIurl\fR\[rB]: The Git repository to clone once into the temporary directory of the agent, where every task without a \fBworktree\fR value is processed in its own temporary Git worktree of this clone, and changed branches are pushed back to its origin (default: none, i.e., all tasks are processed in the Git working copy the agent is started in, which is hence mandatory).
+.sp
+Requires a task store not located in the working copy (i.e., not a local \fBase:\fR\fIpath\fR one). See \fBWORKING COPY, CLONES, AND WORKTREES\fR in \fBase-agent\fR(1).
+.IP \(bu 4
+\[lB]\fB-d\fR|\fB--tempdir\fR \fIdir\fR\[rB]: Create the temporary directory of the agent as the sub-directory \fIname\fR of \fIdir\fR, where \fB%p\fR is expanded to the process id of the agent, \fB%h\fR to a hash value unique to the process, and \fB%%\fR to \fB%\fR (default: a fresh, private directory below the system temporary directory). A missing \fIdir\fR is created private to the current user, while an existing \fIdir\fR has to be a directory (no symbolic link) owned by the current user.
+.IP \(bu 4
+\[lB]\fB-m\fR|\fB--mode\fR \fImode\fR\[rB]: The mode of the agent (default: \fBjudge\fR): \fBjudge\fR just adds the verdict tag and puts the task back into \fBIMPLEMENTED\fR for a human decision, while \fBqualify\fR additionally qualifies resp. declines the task by its verdict, i.e., puts it into \fBQUALIFIED\fR on the verdict \fBAPPROVE\fR, into \fBDECLINED\fR on the verdict \fBREJECT\fR, and back into \fBIMPLEMENTED\fR without a verdict. An invalid mode is an error.
+.IP \(bu 4
+\[lB]\fB--title\fR \fItext\fR\[rB]: The one-line title of the operation of the agent (at most 80 characters), shown on the task boards. Built-in: \fBReview implemented tasks and tag their verdict\fR (\fBjudge\fR) resp. \fBReview implemented tasks and decide by verdict\fR (\fBqualify\fR).
+.IP \(bu 4
+\[lB]\fB--description\fR \fItext\fR\[rB]: The brief description of the operation of the agent (about 3-6 lines, at most 600 characters, with its whitespace collapsed), shown on the task boards. Built-in: a description of the operation of the mode.
+.IP \(bu 4
+\[lB]\fB--type\fR \fBphase\fR|\fBrequest\fR\[rB]: The processing type: \fBphase\fR claims the tasks by their lifecycle status, \fBrequest\fR processes the prompt requests attached to the tasks. Generic default: \fBphase\fR. Built-in: \fBphase\fR.
+.IP \(bu 4
+\[lB]\fB--workdir\fR \fIkind\fR\[rB]: The working directory of the agent tool: \fBproject\fR, \fBsource\fR, \fBchangeset\fR, \fBchangeset-read\fR, or \fBtarget\fR. Generic default: \fBproject\fR. Built-in: \fBchangeset-read\fR.
+.IP \(bu 4
+\[lB]\fB--lifecycle\fR \fImodel\fR\[rB]: A supported task lifecycle model (\fBsolo\fR, \fBteam\fR, or \fBenterprise\fR, repeatable). Generic default: every model containing all given states, resp. all models for \fBrequest\fR and with \fB--unclaimed\fR. Built-in: \fBenterprise\fR.
+.IP \(bu 4
+\[lB]\fB--serial\fR\[rB]: Process the tasks serially only, ignoring \fB--parallel\fR. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--unclaimed\fR\[rB]: Process the tasks of the incoming states without claiming them, independent of their assignee and predecessors, and without ever changing their status and assignee (\fBphase\fR only). Built-in: not set. Not allowed, as the qualifier claims the tasks into its activity state.
+.IP \(bu 4
+\[lB]\fB--params\fR \fIname\fR\fB=\fR\fIvalue\fR\[rB]: The value of a parameter declared by the definition (repeatable). Built-in: none declared.
+.IP \(bu 4
+\[lB]\fB--state-incoming\fR \fIstate\fR\[rB]: The state of the tasks to claim (mandatory for \fBphase\fR, repeatable with \fB--unclaimed\fR only). Built-in: \fBIMPLEMENTED\fR.
+.IP \(bu 4
+\[lB]\fB--state-activity\fR \fIstate\fR\[rB]: The state of a task during its processing. Generic default: the incoming state. Built-in: \fBQUALIFYING\fR.
+.IP \(bu 4
+\[lB]\fB--state-success\fR \fIstate\fR\[rB]: The target state on success. Generic default: the incoming state. Built-in: \fBIMPLEMENTED\fR.
+.IP \(bu 4
+\[lB]\fB--state-failure\fR \fIstate\fR\[rB]: The target state on failure. Generic default: the incoming state. Built-in: \fBIMPLEMENTED\fR.
+.IP \(bu 4
+\[lB]\fB--state-phase\fR \fIstate\fR\[rB]: The phase success state, into which the skill itself can move a task. Generic default: the success state. Built-in: \fBQUALIFIED\fR.
+.IP \(bu 4
+\[lB]\fB--state-passed\fR \fIstate\fR\[rB]: The first state from which on a task has passed the phase for its \fBAfter:\fR successors. Generic default: the phase success state. Built-in: \fBQUALIFIED\fR.
+.IP \(bu 4
+\[lB]\fB--state-verdict\fR \fIVERDICT\fR\fB=\fR\fIstate\fR\[rB]: The target state per verdict (repeatable). Built-in: not set (mode \fBjudge\fR), \fBAPPROVE=QUALIFIED\fR and \fBREJECT=DECLINED\fR (mode \fBqualify\fR).
+.IP \(bu 4
+\[lB]\fB--tag-name\fR \fItag\fR\[rB]: The tag of the processed tasks (\fBase-agent-\fR\fIword\fR). Generic default: \fBase-agent-\fR\fIname\fR, resp. for \fBrequest\fR always \fBase-agent-\fR\fIrequest-name\fR. Built-in: \fBase-agent-qualifier\fR.
+.IP \(bu 4
+\[lB]\fB--tag-success\fR \fItag\fR\[rB]: The tag on success: \fItag-name\fR, \fItag-name\fR\fB:\fR\fIvalue\fR, or \fBnone\fR (\fBphase\fR only). Generic default: \fItag-name\fR. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--tag-failure\fR \fItag\fR\[rB]: The tag on failure: \fItag-name\fR, \fItag-name\fR\fB:\fR\fIvalue\fR, or \fBnone\fR (\fBphase\fR only). Generic default: \fItag-name\fR. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--tag-require\fR \fItag\fR\[rB]: A tag a claimable task has to carry (repeatable). Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--tag-exclude\fR \fItag\fR\[rB]: A tag a claimable task must not carry (repeatable). Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--tag-retry\fR\[rB]: A shorthand for \fB--tag-failure none\fR, so a failed task is claimed again after a growing delay (\fBphase\fR only). Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--assign-name\fR \fIwho\fR\[rB]: The assignee under which the tasks are claimed, held, recognized, and released, and which names the agent-owned worktrees. Generic default: the agent name. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--assign-required\fR\[rB]: Claim only the tasks explicitly assigned to \fIwho\fR of \fB--assign-name\fR (\fBphase\fR only). Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--assign-success\fR \fIwho\fR\[rB]: The assignee of a task after its successful processing: a name, \fBnone\fR, or \fBprevious\fR. Generic default: \fBnone\fR for \fBphase\fR, \fBprevious\fR for \fBrequest\fR. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--assign-failure\fR \fIwho\fR\[rB]: The assignee of a task after its failed processing: a name, \fBnone\fR, or \fBprevious\fR. Generic default: \fBnone\fR for \fBphase\fR, \fBprevious\fR for \fBrequest\fR. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--request-name\fR \fIname\fR\[rB]: The name of the processed requests (\fBrequest\fR only). Generic default: the agent name. Built-in: not set. Not allowed, as the qualifier is of type \fBphase\fR.
+.IP \(bu 4
+\[lB]\fB--request-done\fR \fIword\fR\[rB]: The word naming a processed task in the log lines (\fBrequest\fR only). Generic default: \fBprocessed\fR. Built-in: not set. Not allowed, as the qualifier is of type \fBphase\fR.
+.IP \(bu 4
+\[lB]\fB--prompt-skill\fR \fIname\fR\[rB]: The skill to invoke (mutually exclusive with \fB--prompt-text\fR and \fB--prompt-file\fR). Built-in: \fBase-repo-review\fR.
+.IP \(bu 4
+\[lB]\fB--prompt-args\fR \fItemplate\fR\[rB]: The argument template of the skill. Generic default: \fB{id}\fR for \fBphase\fR, \fB{id}: {prompt}\fR for \fBrequest\fR. Built-in: \fB{?changeset-type=branch:--branch
+{changeset-name}}\fR.
+.IP \(bu 4
+\[lB]\fB--prompt-text\fR \fItemplate\fR\[rB]: The prompt text template to invoke instead of a skill. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--prompt-file\fR \fIfile\fR\[rB]: The file with the prompt text template to invoke instead of a skill. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--prepare-run\fR \fIcmd\fR\[rB]: A shell command run in the working directory before the prompt (repeatable). Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--success-criterion\fR \fIcriterion\fR\[rB]: A success criterion: \fBexit\fR, \fBclean\fR, \fBchanged\fR, \fBverdict\fR, \fBattachment\fR, or \fBstatus\fR (repeatable). Generic default: \fBexit\fR and \fBclean\fR for \fBphase\fR, \fBclean\fR and \fBchanged\fR for \fBrequest\fR. Built-in: \fBexit\fR and \fBverdict\fR.
+.IP \(bu 4
+\[lB]\fB--success-match\fR \fIregex\fR\[rB]: A regular expression an output line has to match (repeatable). Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--verdict-label\fR \fIlabel\fR\[rB]: The label after which the verdict is given in the output. Built-in: \fBREVIEW VERDICT\fR.
+.IP \(bu 4
+\[lB]\fB--verdict-allow\fR \fIVERDICT\fR\[rB]: An accepted verdict (repeatable). Generic default: the verdicts of \fB--state-verdict\fR, else any. Built-in: \fBAPPROVE\fR and \fBREJECT\fR.
+.IP \(bu 4
+\[lB]\fB--attach-output\fR \fIkind\fR\[rB]: The kind of the attachment storing the output lines of the prompt. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--attach-expect\fR \fIspec\fR\[rB]: The attachment \[lB]\fImime-type\fR\fB;\fR\[rB]\fIkind\fR to be created or changed by the processing for the success criterion \fBattachment\fR. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--attach-skip\fR \fIspec\fR\[rB]: The attachment \[lB]\fImime-type\fR\fB;\fR\[rB]\fIkind\fR leaving a task unclaimed (\fBphase\fR only). Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--attach-changeset\fR \fIkind\fR\[rB]: The kind of the attachment \fBtext/x-diff;\fR\fIkind\fR storing the change set snapshot of the task (with \fB--workdir changeset\fR or \fBtarget\fR only). Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--finish-commit\fR\[rB]: Commit the work onto a \fBbranch:\fR changeset and publish it (with \fB--workdir changeset\fR only). Built-in: not set. Not allowed, as the qualifier works with \fB--workdir
+changeset-read\fR.
+.IP \(bu 4
+\[lB]\fB--finish-success\fR \fIcmd\fR\[rB]: A shell command run in the working directory after a successful processing. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--finish-failure\fR \fIcmd\fR\[rB]: A shell command run in the working directory after a failed processing. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB-f\fR|\fB--foreground\fR\[rB]: Run the agent in the current process instead, logging to the terminal, until it is interrupted (e.g., via \fBCTRL+C\fR) or stopped, where an agent of the same name already running is an error.
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show the usage information of the sub-command only.
+.RE 0
+.IP "" 4
+The options \fB--\fR\fIgroup\fR\fB-\fR\fIitem\fR above override the built-in definition of the mode of the agent (where an option also replaces its mutually exclusive alternatives, e.g., \fB--prompt-text\fR replaces the skill of \fB--prompt-skill\fR), while the agent keeps the identity of its kind (its runs, its presence, and its agent-owned worktrees are named after \fBqualifier\fR). See \fBase-agent-adhoc\fR(1) for their full semantics.
+.IP \(bu 4
+\fBase agent qualifier status\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]: Report whether the qualifier agent of the name \fIname\fR (default: \fBqualifier\fR) is running, as \fBagent\fR \fIname\fR\fB: running (pid\fR \fIpid\fR\fB)\fR resp. \fBagent\fR \fIname\fR\fB: not running\fR (exit status 1).
+.IP \(bu 4
+\fBase agent qualifier log\fR \[lB]\fB-f\fR|\fB--follow\fR\[rB] \[lB]\fB-n\fR|\fB--lines\fR \fIn\fR\[rB] \[lB]\fB--name\fR \fIname\fR\[rB]: Show the log \fB.ase/agent/\fR\fIname\fR\fB.log\fR of the qualifier agent of the name \fIname\fR (default: \fBqualifier\fR) run in the background, where an agent of a fleet logs into the log of the fleet instead (see \fBase-agent-fleet\fR(1)). Without a log file, an informational message is shown only. The options are:
+.RS 4
+.IP \(bu 4
+\[lB]\fB-f\fR|\fB--follow\fR\[rB]: Show the last \fIn\fR lines (default: 10) and then follow all newly appended lines, in the style of \fBtail -f\fR, until interrupted.
+.IP \(bu 4
+\[lB]\fB-n\fR|\fB--lines\fR \fIn\fR\[rB]: Show the last \fIn\fR lines only (default: all, or 10 with \fB--follow\fR).
+.IP \(bu 4
+\[lB]\fB--name\fR \fIname\fR\[rB]: The name of the agent (default: \fBqualifier\fR), given in its long form only, as \fB-n\fR is the short form of \fB--lines\fR.
+.RE 0
+.IP \(bu 4
+\fBase agent qualifier stop\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]: Stop the qualifier agent of the name \fIname\fR (default: \fBqualifier\fR) by \fBSIGTERM\fR, waiting (up to 5 minutes) until it aborted its running processings and put their tasks back. An agent not running is reported informationally only.
+.RE 0
+.SH "ENVIRONMENT"
+.RS 0
+.IP \(bu 4
+\fBASE_TOOL\fR: The default agent tool of \fB--tool\fR (default: \fBclaude\fR).
+.IP \(bu 4
+\fBASE_AGENT_RELAY_TOKEN\fR: The bearer token of the agent relay, if not embedded in the URL of \fB--agent-relay\fR resp. \fBproject.relay.url\fR.
+.IP \(bu 4
+\fBASE_HEADLESS\fR: Set to \fBtrue\fR for the agent tool processes spawned by the agent.
+.RE 0
+.SH "FILES"
+.RS 0
+.IP \(bu 4
+\fB.ase/agent/\fR\fIname\fR\fB.yaml\fR: The process state (kind, process id, and process start time) of the agent, existing while it runs.
+.IP \(bu 4
+\fB.ase/agent/\fR\fIname\fR\fB.log\fR: The log of the agent run in the background.
+.IP \(bu 4
+\fIper-user state directory\fR\fB/agent-qualifier/\fR\fIstore-hash\fR\fB/\fR\fIrun-id\fR\fB.lock\fR and \fB.json\fR: The run lock and the run record of each qualifier agent process, used to recover the tasks of terminated agent processes (see \fBINTERRUPTS AND RECOVERY\fR in \fBase-agent\fR(1)).
+.RE 0
+.SH "EXIT STATUS"
+.P
+\fBase agent qualifier start\fR exits with status \fB0\fR once the agent started (or was already running), resp. once a foreground agent terminated regularly, and with status \fB1\fR on any error (e.g., an invalid option, a task lifecycle model other than \fBenterprise\fR, or a missing agent tool). \fBase agent qualifier status\fR exits with status \fB1\fR if the agent is not running.
+.SH "EXAMPLES"
+.P
+.RS 2
+.nf
+# review the implemented tasks, leaving the decision to a human
+$ ase agent qualifier start -m judge -p 2
+
+# review the implemented tasks and decide on them by the verdict
+$ ase agent qualifier start -m qualify
+.fi
+.RE
+.SH "SEE ALSO"
+.P
+\fBase\fR(1), \fBase-agent\fR(1), \fBase-agent-rebooter\fR(1), \fBase-agent-condenser\fR(1), \fBase-agent-researcher\fR(1), \fBase-agent-implementer\fR(1), \fBase-agent-integrator\fR(1), \fBase-agent-editor\fR(1), \fBase-agent-estimator\fR(1), \fBase-agent-adhoc\fR(1), \fBase-agent-fleet\fR(1), \fBase-agent-relay\fR(1), \fBase-task\fR(1), \fBase-task-board\fR(1).
+.SH "AUTHOR"
+.P
+Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR

package/dst/man/ase-agent-rebooter.1

@@ -0,0 +1,193 @@
+.TH "ASE-AGENT-REBOOTER" "1" "October 2026" "2.0.0" "Agentic Software Engineering (ASE)"
+.SH "NAME"
+\fBase-agent-rebooter\fR - Plan Rebooting Agent
+.SH "SYNOPSIS"
+.P
+\fBase agent rebooter start\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB] \[lB]\fB-t\fR|\fB--tool\fR \fBclaude\fR|\fBcopilot\fR|\fBcodex\fR\[rB] \[lB]\fB-p\fR|\fB--parallel\fR \fInum\fR\[rB] \[lB]\fB-T\fR|\fB--timeout\fR \fIduration\fR\[rB] \[lB]\fB-o\fR|\fB--one-shot\fR\[rB] \[lB]\fB--agent-relay\fR \fIurl\fR\[rB] \[lB]\fB--\fR\fIgroup\fR\fB-\fR\fIitem\fR \fIvalue\fR \[lB]...\[rB]\[rB] \[lB]\fB-f\fR|\fB--foreground\fR\[rB]
+.P
+\fBase agent rebooter status\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]
+.P
+\fBase agent rebooter log\fR \[lB]\fB-f\fR|\fB--follow\fR\[rB] \[lB]\fB-n\fR|\fB--lines\fR \fIn\fR\[rB] \[lB]\fB--name\fR \fIname\fR\[rB]
+.P
+\fBase agent rebooter stop\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]
+.SH "DESCRIPTION"
+.P
+\fBase agent rebooter\fR re-creates the plans of tasks in the \fBPlanning\fR phase of the \fBenterprise\fR task lifecycle model (refused for any other model) from scratch.
+.P
+As a plan is re-created only on the explicit request of a human, the rebooter claims only the tasks in the state \fBDRAFTED\fR whose \fBAssignee:\fR frontmatter key already is its agent name (default: \fBrebooter\fR), i.e., which a human assigned to the rebooter. Such a task is claimed immediately, without waiting for its \fBAfter:\fR predecessors (and, for an explicit epic, its group members), except for a predecessor still being processed by a rebooter or a cancelled \fBAfter:\fR predecessor.
+.P
+The rebooter moves each claimed task into \fBPLANNING\fR, tags it with \fBase-agent-rebooter:active\fR, and reboots its plan via the skill invocation \fBase-task-reboot --next DONE\fR \fIid\fR. The skill itself resets a successfully rebooted plan into \fBDRAFTED\fR (the processing succeeds only then). Afterwards, on success as well as on failure, the rebooter puts the task back into \fBDRAFTED\fR (for its review and its promotion into \fBPLANNED\fR by a human), removes its tag, and unassigns it. As the task is no longer assigned to the rebooter, it is not claimed again, while assigning it to the rebooter again requests another reboot.
+.P
+On an interrupt, a task being processed is put back, untagged and with its previous assignee (i.e., still assigned to the rebooter), into \fBDRAFTED\fR. The rebooter works in the project root only, so it neither requires a Git working copy nor \fBgit\fR, and it accepts no \fB--repo\fR and \fB--tempdir\fR. See \fBase-agent\fR(1) for the common mechanics of all agents.
+.SH "OPTIONS"
+.RS 0
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show usage information of \fBase agent rebooter\fR (or of the given sub-command) only.
+.RE 0
+.P
+All other options belong to the sub-commands (see \fBCOMMANDS\fR).
+.SH "COMMANDS"
+.RS 0
+.IP \(bu 4
+\fBase agent rebooter start\fR \[lB]\fIoptions\fR\[rB]: Start the rebooter agent in the background, logging into \fB.ase/agent/\fR\fIname\fR\fB.log\fR. The agent is validated and initialized (e.g., its agent tool is looked up and the task lifecycle model is checked) before the command returns (waiting up to 30 seconds), so a failing agent is reported together with the tail of its log. An agent of the same name already running is left alone. The options are:
+.RS 4
+.IP \(bu 4
+\[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]: The name of the agent (default: \fBrebooter\fR): up to 64 letters, digits, underscores, and dashes, starting with a letter or digit, other than the name of another agent kind, \fBrelay\fR, or \fBfleet\fR.
+.sp
+It names the agent in its log lines (also in the shared processing log attachment \fBagent\fR), the \fBAssignee:\fR of the tasks it processes, and its process files \fB.ase/agent/\fR\fIname\fR\fB.yaml\fR and \fB.ase/agent/\fR\fIname\fR\fB.log\fR. Agents of the kind \fBrebooter\fR under different names form a pool, competing for the same tasks, but each claims only the tasks explicitly assigned to its own name.
+.IP \(bu 4
+\[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB]: The headless agent tool processing the tasks: \fBclaude\fR (\fIAnthropic Claude Code CLI\fR), \fBcopilot\fR (\fIGitHub Copilot CLI\fR), or \fBcodex\fR (\fIOpenAI Codex CLI\fR) (default: \fB$ASE_TOOL\fR, else \fBclaude\fR). Its command has to be found in \fB$PATH\fR.
+.IP \(bu 4
+\[lB]\fB-p\fR|\fB--parallel\fR \fInum\fR\[rB]: The maximum number of tasks processed in parallel by this agent (default: \fB1\fR), a positive integer.
+.IP \(bu 4
+\[lB]\fB-T\fR|\fB--timeout\fR \fIduration\fR\[rB]: The maximum duration of processing a task (the run of the agent tool), as \fInumber\fR \fIunit\fR (without a space) with \fIunit\fR \fBs\fR (seconds), \fBm\fR (minutes), or \fBh\fR (hours) (default: \fB60m\fR). A processing exceeding it is aborted and counts as failed.
+.IP \(bu 4
+\[lB]\fB-o\fR|\fB--one-shot\fR\[rB]: Terminate the agent, instead of observing for further tasks, once a check of the task store finds no dispatchable task while the agent processes no task anymore -- intended for CI contexts like GitHub Actions, and not allowed in a fleet. A task still waiting for its predecessors at that time is left for a later run. A check of the task store failing three times in a row then terminates the agent with a non-zero exit status (instead of being retried endlessly after a growing delay).
+.IP \(bu 4
+\[lB]\fB--agent-relay\fR \fIurl\fR\[rB]: The agent relay to pass the live presence of the agent to, as \fBase://\fR\fIaddr\fR\fB:\fR\fIport\fR\[lB]\fB/\fR\fItoken\fR\[rB] resp. \fBases://\fR\fIaddr\fR\fB:\fR\fIport\fR\[lB]\fB/\fR\fItoken\fR\[rB]\[lB]\fB?insecure\fR\[rB] for HTTPS (default: the configured \fBproject.relay.url\fR, else none). See \fBAGENT RELAY\fR in \fBase-agent\fR(1).
+.IP \(bu 4
+\[lB]\fB--title\fR \fItext\fR\[rB]: The one-line title of the operation of the agent (at most 80 characters), shown on the task boards. Built-in: \fBReboot the plans of assigned tasks\fR.
+.IP \(bu 4
+\[lB]\fB--description\fR \fItext\fR\[rB]: The brief description of the operation of the agent (about 3-6 lines, at most 600 characters, with its whitespace collapsed), shown on the task boards. Built-in: a description of the operation.
+.IP \(bu 4
+\[lB]\fB--type\fR \fBphase\fR|\fBrequest\fR\[rB]: The processing type: \fBphase\fR claims the tasks by their lifecycle status, \fBrequest\fR processes the prompt requests attached to the tasks. Generic default: \fBphase\fR. Built-in: \fBphase\fR.
+.IP \(bu 4
+\[lB]\fB--workdir\fR \fIkind\fR\[rB]: The working directory of the agent tool: \fBproject\fR, \fBsource\fR, \fBchangeset\fR, \fBchangeset-read\fR, or \fBtarget\fR. Generic default: \fBproject\fR. Built-in: \fBproject\fR.
+.IP \(bu 4
+\[lB]\fB--lifecycle\fR \fImodel\fR\[rB]: A supported task lifecycle model (\fBsolo\fR, \fBteam\fR, or \fBenterprise\fR, repeatable). Generic default: every model containing all given states, resp. all models for \fBrequest\fR and with \fB--unclaimed\fR. Built-in: \fBenterprise\fR.
+.IP \(bu 4
+\[lB]\fB--serial\fR\[rB]: Process the tasks serially only, ignoring \fB--parallel\fR. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--unclaimed\fR\[rB]: Process the tasks of the incoming states without claiming them, independent of their assignee and predecessors, and without ever changing their status and assignee (\fBphase\fR only). Built-in: not set. Not allowed, as the rebooter claims the tasks into its activity state.
+.IP \(bu 4
+\[lB]\fB--params\fR \fIname\fR\fB=\fR\fIvalue\fR\[rB]: The value of a parameter declared by the definition (repeatable). Built-in: none declared.
+.IP \(bu 4
+\[lB]\fB--state-incoming\fR \fIstate\fR\[rB]: A state of the tasks to claim (mandatory for \fBphase\fR, repeatable with \fB--unclaimed\fR or \fB--state-activity\fR only). Built-in: \fBDRAFTED\fR.
+.IP \(bu 4
+\[lB]\fB--state-activity\fR \fIstate\fR\[rB]: The state of a task during its processing. Generic default: the incoming state. Built-in: \fBPLANNING\fR.
+.IP \(bu 4
+\[lB]\fB--state-success\fR \fIstate\fR\[rB]: The target state on success, or \fBprevious\fR for the incoming state of the claim. Generic default: the incoming state. Built-in: \fBDRAFTED\fR.
+.IP \(bu 4
+\[lB]\fB--state-failure\fR \fIstate\fR\[rB]: The target state on failure, or \fBprevious\fR for the incoming state of the claim. Generic default: the incoming state. Built-in: \fBDRAFTED\fR.
+.IP \(bu 4
+\[lB]\fB--state-phase\fR \fIstate\fR\[rB]: The phase success state, into which the skill itself can move a task. Generic default: the success state, resp. the activity state for a \fBprevious\fR success state. Built-in: not set (hence \fBDRAFTED\fR, the default state, into which the skill resets a rebooted plan).
+.IP \(bu 4
+\[lB]\fB--state-passed\fR \fIstate\fR\[rB]: The first state from which on a task has passed the phase for its \fBAfter:\fR successors. Generic default: the phase success state. Built-in: not set (hence \fBDRAFTED\fR, the first state, so the predecessors impose no gate).
+.IP \(bu 4
+\[lB]\fB--state-verdict\fR \fIVERDICT\fR\fB=\fR\fIstate\fR\[rB]: The target state per verdict (repeatable). Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--tag-name\fR \fItag\fR\[rB]: The tag of the processed tasks (\fBase-agent-\fR\fIword\fR). Generic default: \fBase-agent-\fR\fIname\fR, resp. for \fBrequest\fR always \fBase-agent-\fR\fIrequest-name\fR. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--tag-success\fR \fItag\fR\[rB]: The tag on success: \fItag-name\fR, \fItag-name\fR\fB:\fR\fIvalue\fR, or \fBnone\fR (\fBphase\fR only). Generic default: \fItag-name\fR. Built-in: \fBnone\fR.
+.IP \(bu 4
+\[lB]\fB--tag-failure\fR \fItag\fR\[rB]: The tag on failure: \fItag-name\fR, \fItag-name\fR\fB:\fR\fIvalue\fR, or \fBnone\fR (\fBphase\fR only). Generic default: \fItag-name\fR. Built-in: \fBnone\fR.
+.IP \(bu 4
+\[lB]\fB--tag-require\fR \fItag\fR\[rB]: A tag a claimable task has to carry (repeatable). Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--tag-exclude\fR \fItag\fR\[rB]: A tag a claimable task must not carry (repeatable). Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--tag-retry\fR\[rB]: A shorthand for \fB--tag-failure none\fR, so a failed task is claimed again after a growing delay (\fBphase\fR only). Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--assign-name\fR \fIwho\fR\[rB]: The assignee under which the tasks are claimed, held, recognized, and released, and which names the agent-owned worktrees. Generic default: the agent name. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--assign-required\fR\[rB]: Claim only the tasks explicitly assigned to \fIwho\fR of \fB--assign-name\fR (\fBphase\fR only). Built-in: enabled.
+.IP \(bu 4
+\[lB]\fB--assign-success\fR \fIwho\fR\[rB]: The assignee of a task after its successful processing: a name, \fBnone\fR, or \fBprevious\fR. Generic default: \fBnone\fR for \fBphase\fR, \fBprevious\fR for \fBrequest\fR. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--assign-failure\fR \fIwho\fR\[rB]: The assignee of a task after its failed processing: a name, \fBnone\fR, or \fBprevious\fR. Generic default: \fBnone\fR for \fBphase\fR, \fBprevious\fR for \fBrequest\fR. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--request-name\fR \fIname\fR\[rB]: The name of the processed requests (\fBrequest\fR only). Generic default: the agent name. Built-in: not set. Not allowed, as the rebooter is of type \fBphase\fR.
+.IP \(bu 4
+\[lB]\fB--request-done\fR \fIword\fR\[rB]: The word naming a processed task in the log lines (\fBrequest\fR only). Generic default: \fBprocessed\fR. Built-in: not set. Not allowed, as the rebooter is of type \fBphase\fR.
+.IP \(bu 4
+\[lB]\fB--prompt-skill\fR \fIname\fR\[rB]: The skill to invoke (mutually exclusive with \fB--prompt-text\fR and \fB--prompt-file\fR). Built-in: \fBase-task-reboot\fR.
+.IP \(bu 4
+\[lB]\fB--prompt-args\fR \fItemplate\fR\[rB]: The argument template of the skill. Generic default: \fB{id}\fR for \fBphase\fR, \fB{id}: {prompt}\fR for \fBrequest\fR. Built-in: \fB--next DONE {id}\fR.
+.IP \(bu 4
+\[lB]\fB--prompt-text\fR \fItemplate\fR\[rB]: The prompt text template to invoke instead of a skill. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--prompt-file\fR \fIfile\fR\[rB]: The file with the prompt text template to invoke instead of a skill. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--prepare-run\fR \fIcmd\fR\[rB]: A shell command run in the working directory before the prompt (repeatable). Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--success-criterion\fR \fIcriterion\fR\[rB]: A success criterion: \fBexit\fR, \fBclean\fR, \fBchanged\fR, \fBverdict\fR, \fBattachment\fR, or \fBstatus\fR (repeatable). Generic default: \fBexit\fR and \fBclean\fR for \fBphase\fR, \fBclean\fR and \fBchanged\fR for \fBrequest\fR. Built-in: \fBstatus\fR.
+.IP \(bu 4
+\[lB]\fB--success-match\fR \fIregex\fR\[rB]: A regular expression an output line has to match (repeatable). Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--verdict-label\fR \fIlabel\fR\[rB]: The label after which the verdict is given in the output. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--verdict-allow\fR \fIVERDICT\fR\[rB]: An accepted verdict (repeatable). Generic default: the verdicts of \fB--state-verdict\fR, else any. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--attach-output\fR \fIkind\fR\[rB]: The kind of the attachment storing the output lines of the prompt. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--attach-expect\fR \fIspec\fR\[rB]: The attachment \[lB]\fImime-type\fR\fB;\fR\[rB]\fIkind\fR to be created or changed by the processing for the success criterion \fBattachment\fR. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--attach-skip\fR \fIspec\fR\[rB]: The attachment \[lB]\fImime-type\fR\fB;\fR\[rB]\fIkind\fR leaving a task unclaimed (\fBphase\fR only). Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--attach-changeset\fR \fIkind\fR\[rB]: The kind of the attachment \fBtext/x-diff;\fR\fIkind\fR storing the change set snapshot of the task (with \fB--workdir changeset\fR or \fBtarget\fR only). Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--finish-commit\fR\[rB]: Commit the work onto a \fBbranch:\fR changeset and publish it (with \fB--workdir changeset\fR only). Built-in: not set. Not allowed, as the rebooter works in the project root.
+.IP \(bu 4
+\[lB]\fB--finish-success\fR \fIcmd\fR\[rB]: A shell command run in the working directory after a successful processing. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB--finish-failure\fR \fIcmd\fR\[rB]: A shell command run in the working directory after a failed processing. Built-in: not set.
+.IP \(bu 4
+\[lB]\fB-f\fR|\fB--foreground\fR\[rB]: Run the agent in the current process instead, logging to the terminal, until it is interrupted (e.g., via \fBCTRL+C\fR) or stopped, where an agent of the same name already running is an error.
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show the usage information of the sub-command only.
+.RE 0
+.IP "" 4
+The options \fB--\fR\fIgroup\fR\fB-\fR\fIitem\fR above override the built-in definition of the agent (where an option also replaces its mutually exclusive alternatives, e.g., \fB--prompt-text\fR replaces the skill of \fB--prompt-skill\fR), while the agent keeps the identity of its kind (its runs, its presence, and its agent-owned worktrees are named after \fBrebooter\fR). See \fBase-agent-adhoc\fR(1) for their full semantics.
+.IP \(bu 4
+\fBase agent rebooter status\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]: Report whether the rebooter agent of the name \fIname\fR (default: \fBrebooter\fR) is running, as \fBagent\fR \fIname\fR\fB: running (pid\fR \fIpid\fR\fB)\fR resp. \fBagent\fR \fIname\fR\fB: not running\fR (exit status 1).
+.IP \(bu 4
+\fBase agent rebooter log\fR \[lB]\fB-f\fR|\fB--follow\fR\[rB] \[lB]\fB-n\fR|\fB--lines\fR \fIn\fR\[rB] \[lB]\fB--name\fR \fIname\fR\[rB]: Show the log \fB.ase/agent/\fR\fIname\fR\fB.log\fR of the rebooter agent of the name \fIname\fR (default: \fBrebooter\fR) run in the background, where an agent of a fleet logs into the log of the fleet instead (see \fBase-agent-fleet\fR(1)). Without a log file, an informational message is shown only. The options are:
+.RS 4
+.IP \(bu 4
+\[lB]\fB-f\fR|\fB--follow\fR\[rB]: Show the last \fIn\fR lines (default: 10) and then follow all newly appended lines, in the style of \fBtail -f\fR, until interrupted.
+.IP \(bu 4
+\[lB]\fB-n\fR|\fB--lines\fR \fIn\fR\[rB]: Show the last \fIn\fR lines only (default: all, or 10 with \fB--follow\fR).
+.IP \(bu 4
+\[lB]\fB--name\fR \fIname\fR\[rB]: The name of the agent (default: \fBrebooter\fR), given in its long form only, as \fB-n\fR is the short form of \fB--lines\fR.
+.RE 0
+.IP \(bu 4
+\fBase agent rebooter stop\fR \[lB]\fB-n\fR|\fB--name\fR \fIname\fR\[rB]: Stop the rebooter agent of the name \fIname\fR (default: \fBrebooter\fR) by \fBSIGTERM\fR, waiting (up to 5 minutes) until it aborted its running processings and put their tasks back. An agent not running is reported informationally only.
+.RE 0
+.SH "ENVIRONMENT"
+.RS 0
+.IP \(bu 4
+\fBASE_TOOL\fR: The default agent tool of \fB--tool\fR (default: \fBclaude\fR).
+.IP \(bu 4
+\fBASE_AGENT_RELAY_TOKEN\fR: The bearer token of the agent relay, if not embedded in the URL of \fB--agent-relay\fR resp. \fBproject.relay.url\fR.
+.IP \(bu 4
+\fBASE_HEADLESS\fR: Set to \fBtrue\fR for the agent tool processes spawned by the agent.
+.RE 0
+.SH "FILES"
+.RS 0
+.IP \(bu 4
+\fB.ase/agent/\fR\fIname\fR\fB.yaml\fR: The process state (kind, process id, and process start time) of the agent, existing while it runs.
+.IP \(bu 4
+\fB.ase/agent/\fR\fIname\fR\fB.log\fR: The log of the agent run in the background.
+.IP \(bu 4
+\fIper-user state directory\fR\fB/agent-rebooter/\fR\fIstore-hash\fR\fB/\fR\fIrun-id\fR\fB.lock\fR and \fB.json\fR: The run lock and the run record of each rebooter agent process, used to recover the tasks of terminated agent processes (see \fBINTERRUPTS AND RECOVERY\fR in \fBase-agent\fR(1)).
+.RE 0
+.SH "EXIT STATUS"
+.P
+\fBase agent rebooter start\fR exits with status \fB0\fR once the agent started (or was already running), resp. once a foreground agent terminated regularly, and with status \fB1\fR on any error (e.g., an invalid option, a task lifecycle model other than \fBenterprise\fR, or a missing agent tool). \fBase agent rebooter status\fR exits with status \fB1\fR if the agent is not running.
+.SH "EXAMPLES"
+.P
+.RS 2
+.nf
+# start the rebooter, rebooting the plans of the tasks assigned to it
+$ ase agent rebooter start
+
+# request the reboot of a drafted task by assigning it to the rebooter
+$ ase task assign FOO-42 rebooter
+.fi
+.RE
+.SH "SEE ALSO"
+.P
+\fBase\fR(1), \fBase-agent\fR(1), \fBase-agent-condenser\fR(1), \fBase-agent-researcher\fR(1), \fBase-agent-implementer\fR(1), \fBase-agent-qualifier\fR(1), \fBase-agent-integrator\fR(1), \fBase-agent-editor\fR(1), \fBase-agent-estimator\fR(1), \fBase-agent-adhoc\fR(1), \fBase-agent-fleet\fR(1), \fBase-agent-relay\fR(1), \fBase-task\fR(1), \fBase-task-board\fR(1).
+.SH "AUTHOR"
+.P
+Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR

package/dst/man/ase-agent-relay.1

@@ -0,0 +1,128 @@
+.TH "ASE-AGENT-RELAY" "1" "October 2026" "2.0.0" "Agentic Software Engineering (ASE)"
+.SH "NAME"
+\fBase-agent-relay\fR - Manage the Agent Relay Server
+.SH "SYNOPSIS"
+.P
+\fBase agent relay start\fR \[lB]\fB-a\fR|\fB--address\fR \fIhost\fR\[rB] \[lB]\fB-p\fR|\fB--port\fR \fIport\fR\[rB] \[lB]\fB-t\fR|\fB--token\fR \fItoken\fR\[rB] \[lB]\fB-c\fR|\fB--cors\fR \fIorigin\fR\[rB] \[lB]\fB--tls-cert\fR \fIfile\fR \fB--tls-key\fR \fIfile\fR\[rB] \[lB]\fB-f\fR|\fB--foreground\fR\[rB]
+.P
+\fBase agent relay status\fR
+.P
+\fBase agent relay log\fR \[lB]\fB-f\fR|\fB--follow\fR\[rB] \[lB]\fB-n\fR|\fB--lines\fR \fIn\fR\[rB]
+.P
+\fBase agent relay stop\fR
+.SH "DESCRIPTION"
+.P
+\fBase agent relay\fR manages the per-user \fIagent relay\fR server, which passes the live presence of the agents (see \fBase-agent\fR(1)) to the task boards (see \fBase-task-board\fR(1)) without any external infrastructure. It can run locally or on a central host, as long as both the agents and the task boards reach it, and serves any number of projects (by their \fBproject.id\fR).
+.P
+The agent relay holds the presence of the agents in memory only: per agent its kind, name, mode, the title and description of its operation (for the agent logs view of \fBase-task-board\fR(1)), request name, the lifecycle states it operates on (of a phase agent: its incoming, activity, written, and gate states, for the agent graph of \fBase-task-board\fR(1)), host, process id, current working directory, user name and user id, start time, state (\fBwaiting\fR or \fBbusy\fR), the ids of the tasks it is busy with, its usage of the agent tool (in total and by its last job), the time since which it is in its state, the time of its latest announcement (its heartbeat), and its most recent 100 processing log lines (each message truncated to 500 characters).
+.P
+An agent without heartbeat for 30 seconds is removed (checked every 5 seconds), and a project exists only while it has agents.
+.P
+The agents announce their presence (see \fB--agent-relay\fR of \fBase-agent\fR(1)) on every change of their state, after each finished job, with their new processing log lines, and as a heartbeat every 10 seconds, and remove it on their termination. The task boards subscribe to the agents of their project.
+.P
+Alternatively, \fBase task store start --with-agent-relay\fR (see \fBase-task-store\fR(1)) co-hosts the agent relay in the task store server under the same address, port, and token, so a central host needs a single server process only. A fleet with the section \fBrelay\fR owns the agent relay instead (see \fBase-agent-fleet\fR(1)).
+.P
+The agent relay is selected by the agents and task boards via the configuration \fBproject.relay.url\fR (or their option \fB--agent-relay\fR), as \fBase://\fR\fIaddr\fR\fB:\fR\fIport\fR\[lB]\fB/\fR\fItoken\fR\[rB] for HTTP, resp. \fBases://\fR\fIaddr\fR\fB:\fR\fIport\fR\[lB]\fB/\fR\fItoken\fR\[rB]\[lB]\fB?insecure\fR\[rB] for HTTPS (verifying the server certificate against the Node.js CA store, extendable via \fB$NODE_EXTRA_CA_CERTS\fR, or, with \fB?insecure\fR, without certificate verification). The relay requires an explicit \fBproject.id\fR.
+.P
+The bearer token of a client is the one embedded in the URL (warned about if configured on the \fBproject\fR or a \fBtask\fR scope, as it might be committed), else \fB$ASE_AGENT_RELAY_TOKEN\fR, else \fBproject.relay.token\fR (intended for the \fBuser\fR scope, and warned about on any other scope), else the token of the locally started agent relay (resp. of the locally started task store co-hosting it), but only if the URL addresses exactly this server. Sending a token to a non-loopback host selected by a repository-supplied scope is warned about.
+.SH "COMMANDS"
+.RS 0
+.IP \(bu 4
+\fBase agent relay start\fR \[lB]\fIoptions\fR\[rB]: Start the agent relay server in the background (spawning a detached process logging into \fBrelay.log\fR) and wait until it responds (up to 10 seconds), or with \fB--foreground\fR run it in the current process.
+.sp
+The configuration of the server is resolved from the options, the environment, and the per-user \fBrelay.yaml\fR, and its effective values (address, port, token, CORS origins, TLS certificate and key, and process id) are persisted in \fBrelay.yaml\fR (readable by the current user only). The start is idempotent: an already running server is left alone, unless an explicitly given option (\fB--address\fR, \fB--port\fR, \fB--token\fR, \fB--cors\fR, \fB--tls-cert\fR, or \fB--tls-key\fR) deviates from its configuration, in which case the server is restarted to apply it.
+.sp
+With \fB--foreground\fR, an already running server with an unchanged configuration is an error. A configured port held by a foreign service is re-allocated (with a warning). Binding to a non-loopback address without TLS is warned about, as the bearer token then travels unencrypted. All options are described under \fBOPTIONS\fR below.
+.IP \(bu 4
+\fBase agent relay status\fR: Report whether the agent relay server is running, as \fBrelay: running
+on\fR \fIurl\fR \fB(pid\fR \fIpid\fR\fB)\fR, after probing it on its configured address and port with its configured token. Exits with status 1 if it is not running (no port configured, the port not responding, or the port in use by a foreign service), or if it rejects the configured token.
+.IP \(bu 4
+\fBase agent relay log\fR \[lB]\fB-f\fR|\fB--follow\fR\[rB] \[lB]\fB-n\fR|\fB--lines\fR \fIn\fR\[rB]: Show the log \fBrelay.log\fR of the agent relay server run in the background. With \fB-n\fR|\fB--lines\fR \fIn\fR, only the last \fIn\fR lines are shown (default: all). With \fB-f\fR|\fB--follow\fR, the last \fIn\fR lines (default: 10) are shown and then, in the style of \fBtail -f\fR, all newly appended lines are followed until interrupted. If no log file exists, this is just reported (at log level \fBinfo\fR). The server logs its requests at log level \fBdebug\fR only, as the agents announce frequently.
+.IP \(bu 4
+\fBase agent relay stop\fR: Stop the agent relay server by sending it \fBSIGTERM\fR and waiting (up to 5 seconds) until it is gone, closing all subscriptions of the task boards. A not running server is reported as such, without an error.
+.RE 0
+.SH "OPTIONS"
+.P
+The following options exist for \fBase agent relay start\fR:
+.RS 0
+.IP \(bu 4
+\[lB]\fB-a\fR|\fB--address\fR \fIhost\fR\[rB]: The address to bind to (default: the configured \fBaddress\fR of \fBrelay.yaml\fR, else \fB127.0.0.1\fR), e.g., \fB0.0.0.0\fR for all IPv4 interfaces of a central host.
+.IP \(bu 4
+\[lB]\fB-p\fR|\fB--port\fR \fIport\fR\[rB]: The TCP port to bind to, \fB1\fR..\fB65535\fR (default: the configured \fBport\fR of \fBrelay.yaml\fR, else a randomly allocated free port in the range \fB42000\fR..\fB44000\fR).
+.IP \(bu 4
+\[lB]\fB-t\fR|\fB--token\fR \fItoken\fR\[rB]: The bearer token to expect from all clients (default: \fB$ASE_AGENT_RELAY_TOKEN\fR, else the configured \fBtoken\fR of \fBrelay.yaml\fR, else a generated random token).
+.IP \(bu 4
+\[lB]\fB-c\fR|\fB--cors\fR \fIorigin\fR\[rB]: (repeatable) Allow cross-origin browser requests from \fIorigin\fR, or from any origin with \fB*\fR (default: the configured \fBcors\fR origins of \fBrelay.yaml\fR, else none).
+.IP \(bu 4
+\[lB]\fB--tls-cert\fR \fIfile\fR\[rB]: Serve HTTPS with the PEM certificate (chain) in \fIfile\fR, which requires \fB--tls-key\fR, too (default: the configured \fBproject.relay.crt\fR (unless \fBproject.relay.url\fR selects HTTP via \fBase://\fR on this host), else the configured \fBtls.cert\fR of \fBrelay.yaml\fR, else plain HTTP). A relative path of a configuration is relative to its configuration file.
+.IP \(bu 4
+\[lB]\fB--tls-key\fR \fIfile\fR\[rB]: Serve HTTPS with the PEM private key in \fIfile\fR, which requires \fB--tls-cert\fR, too (default: the configured \fBproject.relay.key\fR (unless \fBproject.relay.url\fR selects HTTP via \fBase://\fR on this host), else the configured \fBtls.key\fR of \fBrelay.yaml\fR).
+.IP \(bu 4
+\[lB]\fB-f\fR|\fB--foreground\fR\[rB]: Run the server in the current process, logging to the terminal instead of \fBrelay.log\fR, until it is interrupted (e.g., via \fBCTRL+C\fR) or stopped via \fBase agent relay stop\fR.
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show the usage information of the command and exit.
+.RE 0
+.SH "PROTOCOL"
+.P
+All requests have to carry the bearer token in the \fBAuthorization:
+Bearer\fR \fItoken\fR header (the WebSocket handshake alternatively in the query parameter \fBtoken\fR), else they are rejected with status 401 and an \fBapplication/problem+json\fR problem details response. The REST endpoints are:
+.RS 0
+.IP \(bu 4
+\fBGET /agents\fR: The projects with agents, as \fB{ "projects": \[lB] { "id":\fR \fIid\fR\fB,
+"agents":\fR \fIcount\fR \fB} \[rB] }\fR.
+.IP \(bu 4
+\fBGET /projects/\fR\fIid\fR\fB/agents\fR: All agents of the project \fIid\fR, as \fB{ "agents": \[lB]\fR ... \fB\[rB] }\fR.
+.IP \(bu 4
+\fBPUT /projects/\fR\fIid\fR\fB/agents/\fR\fIagent\fR: The announcement of the agent \fIagent\fR (also its heartbeat), as a JSON payload with its presence and only its processing log lines added since its previous announcement (at most 100), answered with status 204.
+.IP \(bu 4
+\fBDELETE /projects/\fR\fIid\fR\fB/agents/\fR\fIagent\fR: The removal of the agent \fIagent\fR (on its termination), answered with status 204.
+.RE 0
+.P
+The WebSocket event endpoint \fB/projects/\fR\fIid\fR\fB/agents/events\fR first sends a snapshot frame of all agents of the project (with \fBreset:
+true\fR) and then a frame on each change (the added or updated agents, and the removed ones), where the processing log lines of an agent are always to be appended to the already received ones.
+.P
+Subscribers are pinged every 15 seconds and terminated if they did not answer the previous ping, resp. if they cannot keep up (more than 1 MB of not yet transmitted data). A plain HTTP request onto the event endpoint is answered with status 426.
+.P
+The project ids have to match \fB\[lB]A-Za-z0-9_-\[rB]+\fR and the agent ids \fB\[lB]A-Za-z0-9\[rB]\[lB]A-Za-z0-9_.-\[rB]*\fR (at most 128 characters), else the request is rejected with status 422. To bound its memory, the relay holds at most 128 projects with agents, 64 agents per project, and 1024 agents in total, and accepts at most 64 subscribers per project and 1024 subscribers in total, where a request beyond these limits is rejected with status 429.
+.SH "ENVIRONMENT"
+.RS 0
+.IP \(bu 4
+\fBASE_AGENT_RELAY_TOKEN\fR: The default of \fB--token\fR of \fBase agent relay start\fR, and the bearer token of the agents and task boards connecting to the relay (if not embedded in its URL).
+.RE 0
+.SH "FILES"
+.RS 0
+.IP \(bu 4
+\fIper-user configuration directory\fR\fB/relay.yaml\fR: The configuration and runtime state of the agent relay server: the keys \fBaddress\fR, \fBport\fR, \fBtoken\fR, \fBcors\fR (a list of origins), \fBtls.cert\fR, \fBtls.key\fR, and \fBpid\fR (of the running server). It is written by \fBase agent relay start\fR (readable by the current user only), and can be edited by hand to configure the defaults.
+.IP \(bu 4
+\fIper-user configuration directory\fR\fB/relay.log\fR: The log of the agent relay server run in the background.
+.RE 0
+.P
+The \fIper-user configuration directory\fR is \fB~/Library/Application
+Support/ase\fR on macOS, \fB%APPDATA%\[rs]ase\fR on Windows, and \fB$XDG_CONFIG_HOME/ase\fR (falling back to \fB~/.config/ase\fR) on Linux and other Unix systems.
+.SH "EXIT STATUS"
+.P
+\fBstart\fR and \fBstop\fR exit with status 0 on success (also for a server already running resp. not running) and 1 on any error. \fBstatus\fR exits with status 1 if the server is not running or rejects the configured token. \fBlog\fR exits with status 0.
+.SH "EXAMPLES"
+.P
+.RS 2
+.nf
+# start the agent relay locally and let the agents and task boards follow it
+$ ase agent relay start -p 4711
+$ ase config --scope project set project.id myproject
+$ ase config --scope project set project.relay.url ase://127.0.0.1:4711
+
+# start the agent relay on a central host via HTTPS
+$ ase agent relay start -a 0.0.0.0 -p 4711 --tls-cert relay.crt --tls-key relay.key
+$ ase config --scope user set project.relay.token <token>
+
+# check and follow the agent relay
+$ ase agent relay status
+$ ase agent relay log -f
+.fi
+.RE
+.SH "SEE ALSO"
+.P
+\fBase\fR(1), \fBase-agent\fR(1), \fBase-agent-fleet\fR(1), \fBase-task-board\fR(1), \fBase-task-store\fR(1), \fBase-config\fR(1).
+.SH "AUTHOR"
+.P
+Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR