Archive the-supervisor-advises

openspec/specs/agentic-harness/spec.md

@@ -3516,3 +3516,91 @@ checked against the same permitted character set as any other.
 - **WHEN** a stage's entry is `"local-llm-acp"` alone
 - **THEN** the configuration is read without error, and the model is
   found from the settings or the server
+
+### Requirement: The supervisor advises by default and can be turned off
+
+The harness configuration SHALL accept `supervisor.mode` with the values
+`advise` and `off`, in the global file and in a change's own file. Absent
+SHALL mean `advise`. A change's own `supervisor` object SHALL be merged
+key by key over the global one.
+
+Under `off`, none of the supervisor's suggestions SHALL be computed.
+Under `advise`, the supervisor SHALL suggest and SHALL NOT stop, start,
+restart or change any run, file or setting.
+
+Any other value of `supervisor.mode` SHALL be refused where the
+configuration resolves.
+
+`supervisor.silentAfterSeconds` and `supervisor.waitingAfterSeconds` SHALL
+be positive integers, 600 and 60 where absent.
+
+#### Scenario: A configuration that says nothing about it
+
+- **WHEN** neither harness file sets `supervisor`
+- **THEN** the supervisor advises, with thresholds of 600 and 60 seconds
+
+#### Scenario: Turned off
+
+- **WHEN** the resolved `supervisor.mode` is `off`
+- **THEN** no suggestion of the supervisor's is computed, and every other
+  suggestion still is
+
+#### Scenario: A mode that does not exist
+
+- **WHEN** a harness file sets `supervisor.mode` to a value other than
+  `advise` or `off`
+- **THEN** resolving the configuration fails and names the field
+
+### Requirement: A run that says nothing new is pointed out
+
+The supervisor SHALL suggest looking at a run whose status record is not
+gone, which is not waiting on anyone, and whose activity has not changed
+for longer than `supervisor.silentAfterSeconds`.
+
+The suggestion SHALL quote what the run last said and for how long, and
+SHALL give the command that shows the run's status and the command that
+asks it to stop. It SHALL NOT call the run hung or stuck: a long turn and
+a hang look the same from outside (ADR 0028).
+
+#### Scenario: Silent past the threshold
+
+- **WHEN** a run's heartbeat is fresh and its activity is twelve minutes
+  old, with the threshold at ten
+- **THEN** a suggestion names the run, quotes its last activity, says
+  twelve minutes, and gives `status` and `stop` commands for it
+
+#### Scenario: A run whose writer is gone
+
+- **WHEN** a run's heartbeat is older than the staleness window
+- **THEN** this suggestion is not made for it
+
+### Requirement: A run waiting on a person is pointed out
+
+The supervisor SHALL suggest attending to a run that has waited on a
+checkpoint or a permission for longer than
+`supervisor.waitingAfterSeconds`, naming what it waits for.
+
+A waiting run SHALL NOT also be pointed out as saying nothing new.
+
+#### Scenario: A permission nobody answered
+
+- **WHEN** a run has waited for a permission for three minutes, with the
+  threshold at one
+- **THEN** a suggestion says the run waits on a person, names the
+  permission, and the run is not pointed out as silent
+
+### Requirement: A change whose last run cannot be repeated is pointed out
+
+The supervisor SHALL suggest the remedy for a change whose last run
+failed with a diagnosis saying repeating will not help, while no run is
+working on that change.
+
+#### Scenario: The agent was not signed in
+
+- **WHEN** a change's last run failed diagnosed as "not signed in"
+- **THEN** a suggestion says so, quotes the line, and gives the remedy
+
+#### Scenario: A later run succeeded
+
+- **WHEN** a later run of the same change completed
+- **THEN** the suggestion is no longer made

openspec/specs/ci-cli/spec.md

@@ -2,7 +2,9 @@
 
 ## Purpose
 TBD - created by archiving change ci-cli. Update Purpose after archive.
+
 ## Requirements
+
 ### Requirement: `validate` command checks every active change and aggregates the result
 
 The CLI SHALL list every active OpenSpec change in the given workspace,
@@ -1011,3 +1013,21 @@ It SHALL exit `2` only where the changes themselves cannot be read.
 - **THEN** it prints both stays In review, and the time In review over two
   visits
 
+### Requirement: The terminal shows what the supervisor finds
+
+`openspec-ui-cli advise` SHALL print the supervisor's suggestions with the
+others, in text and in JSON. `openspec-ui-cli run` SHALL print a failed
+run's diagnosis beneath its failure.
+
+#### Scenario: A silent run seen from a terminal
+
+- **WHEN** a run has said nothing new past the threshold and `advise` is
+  run
+- **THEN** the suggestion is printed with its reason and its commands
+
+#### Scenario: A run that fails in the terminal
+
+- **WHEN** `openspec-ui-cli run` ends with a failed stage that carries a
+  diagnosis
+- **THEN** the cause, whether repeating can help, the quoted line and the
+  remedy are printed after the failure

openspec/specs/execution-core/spec.md

@@ -3175,3 +3175,52 @@ SHALL say whether it honours the switch: `ignored`, `environment` or
 - **WHEN** the switch is off
 - **THEN** every agent's environment and connections are what they were
   before this requirement
+
+### Requirement: A failed run says what is known about why
+
+When a run of any agent fails, the runner SHALL diagnose the failure from
+the run's reason and the last of its output, and SHALL attach the
+diagnosis to the `failed` event and to the run's terminal audit entry.
+
+A diagnosis SHALL name one cause from a closed set: the agent is not
+installed, it is not signed in, the machine blocked it, the network could
+not be reached, the service rate-limited it, the service failed, or
+unknown. It SHALL say whether repeating the run can help (`no`, `likely`
+or `unknown`), SHALL quote the line the cause was found in, and SHALL say
+what to do instead where repeating cannot help.
+
+A failure matching no known cause SHALL be diagnosed as `unknown`, never
+as a guessed cause.
+
+The diagnosis SHALL be an optional field. A reader written before it
+SHALL read the event and the entry as before.
+
+#### Scenario: An agent that is not signed in
+
+- **WHEN** a run fails and its output says "Authentication required"
+- **THEN** its `failed` event and its audit entry carry the cause
+  "not signed in", repeating `no`, the quoted line, and a remedy naming
+  the agent's executable
+
+#### Scenario: An agent that is not installed
+
+- **WHEN** a run fails because its executable could not be found
+- **THEN** the diagnosis says the agent is not installed and that
+  repeating will not help
+
+#### Scenario: A service under load
+
+- **WHEN** a run fails and its output names HTTP 503
+- **THEN** the diagnosis says the service failed and that repeating is
+  likely to help
+
+#### Scenario: A failure nobody has seen
+
+- **WHEN** a run fails with output matching no known cause
+- **THEN** the diagnosis says the cause is unknown and whether repeating
+  helps is unknown
+
+#### Scenario: A chain fails at a stage
+
+- **WHEN** a chain ends because one of its stages failed
+- **THEN** the chain's ending entry carries that stage's diagnosis

openspec/specs/shared-ui/spec.md

@@ -2153,3 +2153,38 @@ which command is sent: `propose` is sent as `plan`, and `apply` as
 - **THEN** each option reads as its name and what it does, and the
   `propose` option says it writes the change's missing planning artifacts
   and is sent as `plan`
+
+### Requirement: A failure is shown with its diagnosis
+
+Where a host shows that a run failed, on a change's card, in a run's
+panel or in its log, it SHALL show the failure's diagnosis with it: the
+cause, whether repeating can help, the quoted line and the remedy. Both
+hosts SHALL render it with one shared component, from the field the
+event and the last run already carry, and SHALL NOT diagnose anything
+themselves.
+
+A failure without a diagnosis SHALL be shown as before.
+
+#### Scenario: A card whose last run failed
+
+- **WHEN** a change's last run failed diagnosed as "not signed in"
+- **THEN** its card says the last run failed, and that the agent is not
+  signed in and repeating will not help
+
+#### Scenario: A chain that fails while watched
+
+- **WHEN** a chain's stage fails with a diagnosis while its panel is open
+- **THEN** the panel shows the failure reason, the diagnosis beneath it,
+  and the remedy as text a person can copy
+
+### Requirement: The Harness Settings views set the supervisor's mode
+
+Both Harness Settings views, the global one and a change's own, SHALL
+offer the supervisor's mode, Advise or Off, and SHALL save it with the
+rest of the configuration.
+
+#### Scenario: Turning it off for one change
+
+- **WHEN** a person sets the supervisor to Off in a change's Harness tab
+  and saves
+- **THEN** that change's `harness.json` carries `supervisor.mode: "off"`