* feat(cli): support refreshInterval in statusLine for periodic refresh
The statusLine (#3311) re-runs only when Agent state changes (token count,
model, git branch, etc.). Commands that display *external* data — a clock,
rate-limit counters, CI build status — have no Agent event to hook into
and go stale between messages.
Add an optional `ui.statusLine.refreshInterval` field (seconds, minimum 1)
that schedules a setInterval alongside the existing event-driven updates.
Overlap with state-change debounce is safe: `doUpdate` kills any in-flight
child and bumps the generation counter, so only the most recent output
reaches the footer.
Validation lives in `getStatusLineConfig`:
- Must be `number`, `Number.isFinite(...)`, `>= 1`
- Anything else is silently dropped (no interval scheduled)
No changes to the default behavior — configs without `refreshInterval`
behave exactly as before.
* fix(cli): yield periodic statusLine tick when previous exec is in flight
Review feedback on #3383: with `refreshInterval: 1` and a command whose
real exec time exceeds 1s, each tick was unconditionally calling
`doUpdate()` — which kills the in-flight child and bumps the generation
counter — so the prior exec's callback was always discarded as stale.
`setOutput` was never reached and the statusline stayed empty until
`refreshInterval` was removed or the command became faster.
Guard the interval callback with an `activeChildRef` check so a pending
exec is allowed to finish. State-change triggers (model switch, token
count, branch, etc.) still go through `scheduleUpdate` → `doUpdate`
directly and legitimately preempt stale children; only the periodic
tick yields. The existing 5s exec timeout is still the hard ceiling.
Also drop the redundant `'refreshInterval' in raw` check — the `typeof
raw.refreshInterval === 'number'` guard already excludes missing /
undefined values.
Tests:
- Add regression test `'skips periodic ticks while a previous exec is
still running'` — three ticks during one unfinished exec trigger zero
new spawns; the next tick after callback completion does spawn.
- Update two existing tests to resolve the mount exec before expecting
subsequent ticks (the old tests implicitly relied on the starvation
behavior being tolerated).
* test(cli): assert user-visible lines state in starvation regression
Self-review insight: the existing `skips periodic ticks while a previous
exec is still running` test only counted `exec` calls — it confirmed the
guard prevents redundant spawns, but would have silently passed even if
the eventual callback was still being discarded as stale (which is the
actual user-visible symptom of the starvation bug).
Add `expect(result.current.lines).toEqual(['done'])` after resolving the
mount's pending callback. Without the guard, generationRef would have
bumped 3 times during the yielded ticks, the callback's captured gen
would fail the stale check, `setOutput` would never fire, and `lines`
would stay empty — now caught explicitly.
* perf(cli): dedupe statusLine output to skip unchanged Footer re-renders
Review feedback on #3383 (narrow terminal stacking): when
`refreshInterval` fires at 1s and the command output is unchanged, the
mount-and-setOutput cycle still allocates a new array and triggers a
Footer re-render. Under certain narrow-terminal conditions, Ink's
erase-line accounting mis-counts wrapped rows and stale content
accumulates on screen.
The Footer-layout root cause is in #3311's narrow-mode flex setup and
Ink's truncate semantics, which is out of scope for this PR. But we
can cut the re-render surface here by preserving the `lines` array
reference when the command produces identical output — a strict
Pareto improvement for any caller (clock-style statuslines with
second-precision still re-render; rate-limit / branch / CI-status
style statuslines that change infrequently stop triggering work every
tick).
Tests:
- `preserves the same lines array reference when output is unchanged`
asserts referential equality after a re-exec with identical stdout.
- `produces a new reference when output changes` guards against
over-eager dedup that would miss legitimate updates.
* fix(cli): stabilize Footer rendering in narrow terminals
Narrow-terminal E2E feedback on #3383: with `refreshInterval` at 1s,
empty lines were accumulating above the input prompt each tick. Root
cause is in the Footer flex layout — originally from #3311 — where Ink
miscounts logical rows vs the physical rows the terminal actually uses.
Two adjustments, both idiomatic (used elsewhere in the repo already):
1. Left column — `minWidth={0}`. Without this, Yoga's `min-width: auto`
default keeps the Box at its natural content width, so a statusline
wider than the terminal doesn't engage `<Text wrap="truncate">`; the
text renders at content-width and the terminal wraps it physically.
`minWidth={0}` lets the column shrink so the text child can truncate
at container width.
2. Right section — `flexWrap="wrap"`. With multiple indicators (sandbox
label, debug badge, dream, context-usage) the row can exceed a narrow
terminal's width. Without `flexWrap` Ink lays them out in a single
logical row, but the terminal physically wraps to two — Ink's erase
sequence (`\e[2K\e[1A…` per logical row) then clears one row while
two exist, and the extra row ghosts every re-render. With `wrap` Ink
tracks the second row explicitly and erases correctly.
Together these make the Footer's row count match between Ink's logical
view and the terminal's physical view, so frequent re-renders (as
`refreshInterval` enables) stop accumulating ghost rows.
Needs verification in a real narrow TTY — from this environment I can
reason about the flex semantics and confirm both props are supported by
Ink's Box, but actually observing ghost-row elimination requires
process.stdout.columns on a real terminal.
* Revert "fix(cli): stabilize Footer rendering in narrow terminals"
This reverts commit 9758cda85f. Reason: I could not reproduce BZ-D's
reported ghost-row stacking in tmux (40x25, 2-line statusline + real
exec + Static history + refreshInterval: 1) over 14+ ticks. Both
`minWidth={0}` and `flexWrap="wrap"` are legitimate defensive idioms,
but without a failing repro I can't verify they address the reported
bug, and I shouldn't ship a speculative layout change as "the fix".
Keeping the output-dedup commit (e1d321186) — that one is a strict
improvement regardless of the underlying Ink behavior. Will request
BZ-D's specific terminal setup and reopen with a verified fix (or
confirm the issue is specific to a particular emulator, not flex/Ink).
* feat(cli): support multi-line status line output (#3211)
Remove the single-line hard limit (.split('\n')[0]) from the status line
hook so user scripts can output multiple rows. Footer renders each line
as a separate <Text wrap="truncate"> element, preserving per-line
horizontal truncation. Ink's virtual DOM handles re-rendering without
manual ANSI cursor management.
* feat(cli): cap status line output at 3 lines
Prevent runaway scripts from flooding the footer — lines beyond the
third are silently discarded.
* docs: mention 3-line cap in status line docs and agent prompt
* fix(cli): cap status line at 2 lines to keep footer within 3 rows
Footer has a fixed bottom row (hint/mode indicator), so status line
gets at most 2 lines to keep the total footer height at 3 rows max.
* test(cli): improve useStatusLine coverage to 100% lines
Add tests for: per-model metrics payload, contextWindowSize/version/
model fallbacks, config removal with pending debounce, command change
cancelling pending debounce.
* docs: update status line ASCII diagram for multi-line layouts
Also fix TS error in test (null → null as never for mock return).
* refactor(cli): return string[] from useStatusLine, filter empty lines
Address review feedback:
- Hook returns `lines: string[]` instead of `text: string | null`,
eliminating the join/split round-trip with Footer.
- Filter empty lines before slicing so leading blanks don't eat real
content (e.g. "\n\nreal content" no longer yields ["", ""]).
- Export MAX_STATUS_LINES with comment explaining the 3-row constraint.
- Use `status-line-${i}` as React key for clarity.
* test(cli): add Footer multi-line rendering, \r\n, and pure-newline tests
Address remaining review feedback:
- Footer test: mock useStatusLine, verify multi-line rendering and
hint suppression.
- useStatusLine test: add \r\n line ending and pure-newline edge case.
* fix(cli): align right footer indicators to top
When the status line has multiple rows, the left column becomes taller
than the right section. The outer Box defaults to `alignItems: stretch`
which caused the indicators to visually center; add `alignItems="flex-start"`
on the right Box so they stay anchored to the top row.
Reported via e2e test in #3311.
- Update architecture diagram to show status line in footer left
section instead of separate row below
- Document 1-row (default mode) and 2-row (non-default mode) layouts
- Note suppressHint behavior and truncation
- Update settings reference description
The status line is now inlined in the footer's left section,
so horizontal padding is no longer applicable. Remove padding
from StatusLineConfig, settings schema, JSON schema, and docs.
Restructure the status line stdin JSON for clarity and accuracy:
- Rename model.id → model.display_name, cwd → workspace.current_dir
- Replace raw context_window size/count with used_percentage,
remaining_percentage, current_usage, context_window_size, and
total_input_tokens/total_output_tokens
- Add version field from cfg.getCliVersion()
- Add git.branch, metrics.models, metrics.files
- Remove upstream-only fields: tokens.tool (never populated),
session (start_time/elapsed_time not live-updating),
streaming_state, approval_mode, terminal, metrics.tools
- Rename tokens.candidates → tokens.completion (Qwen API convention)
- Fix template string escaping in builtin-agents to avoid
templateString() placeholder collision
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Inline shell snippets need sh -c to execute via pipe, matching how
child_process.exec() runs the configured command.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Footer comment now accurately states only the "? for shortcuts"
hint is suppressed, not all left-section items
- Docs now note that Windows uses cmd.exe by default and suggest
wrapping commands with bash -c or using a bash script
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Use echo "$input" instead of echo $input for proper shell variable
quoting, consistent with the script file example.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The settings parser uses stripJsonComments + JSON.parse, which does
not support trailing commas. Changed the config example from jsonc
to json and removed trailing commas so users can copy-paste safely.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add size > 0 check before computing context percentage to prevent
division by zero when context_window_size is unavailable.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add jq prerequisite section
- Clarify that settings changes take effect without restart
- Provide complete JSON in troubleshooting test command
- Move script filename out of code block to avoid shebang confusion
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
