displayNotice
displayNotice(
title,lines,options?):void
Defined in: packages/core/src/utils/consoleUtils.ts:339
Print one whole NOTICE — a title and its body lines — on stderr.
One notice, one stream
Section titled “One notice, one stream”A notice is a title that names something and body lines that are the substance of it; neither
half is usable alone. Written through the ordinary helpers it is written across BOTH streams,
because those bind colour to stream: a title coloured with displayWarning is yellow AND stderr,
while display body lines are stdout. On a terminal both go to the same place and nothing shows;
redirect one and the notice tears in half — the reader keeps “Run ended” with no reason code
while the file keeps the reason code with no notice.
So a notice takes its title and its lines together and writes them through one call. The split cannot be reintroduced by a caller, because a caller no longer chooses per line.
stderr, because a notice is commentary on the run and not the run’s output. It is where
displayWarning already writes, and that is the only one of the ordinary helpers that does —
even displayError, the loudest of them, is red but goes to stdout. It is unbuffered, and it
leaves stdout carrying only what the command produced — so gth ask … > answer.txt gets an
answer file that is the answer, with the whole explanation of a bad ending still on the screen
and still collectable with 2>.
It also keeps a notice on the same stream as the approval dialog it sits beside on the readline
surface (displayDialogLine); split across two, those two related blocks can arrive in an
order neither of them was written in.
The session log gets every line UNCONDITIONALLY, gate or no gate, so a quieted console never costs the transcript a notice it did not show.
The gate is per NOTICE, never per line
Section titled “The gate is per NOTICE, never per line”gate is checked once, before the first line is written, and decides the whole notice. That is
the property, not an implementation detail: the level filter applied per line is what let a
quieted console print a title with no body under it (and, at display level, a body with no
title over it), which still looks like a whole notice and is not one.
'always' is for a notice whose absence cannot be recovered by the reader — the termination
notice carries the one token a bug report needs, and the session log that would otherwise hold it
is off by default. A notice the user asked for by typing a command is not that: it is gated at
its own tone’s level, and re-running the command after un-quieting the console brings it back.
Parameters
Section titled “Parameters”string
readonly string[]
options?
Section titled “options?”Returns
Section titled “Returns”void