8000 feat(shell): top-bar escalation alert for silently wedged agents by simon-inkie · Pull Request #10 · simon-inkie/inkie-deck · GitHub
[go: up one dir, main page]

Skip to content

feat(shell): top-bar escalation alert for silently wedged agents - #10

Merged
simon-inkie merged 1 commit into
mainfrom
feat/top-bar-escalation-alert
Aug 18, 2026
Merged

simon-inkie merged 1 commit into
mainfrom
feat/top-bar-escalation-alert

Conversation

@simon-inkie
Copy link
Copy Markdown
Owner

What this adds

An agent can go quiet in a way nothing on screen reports: stuck behind a permission dialog, or waiting on a person who has not looked. The sidebar pill says "stuck" only while you are looking at the sidebar, and the needs-you bell counts things to action, not things that have stopped moving. Neither surfaces "this has been true for 45 minutes".

This adds the alert that does, computed off the same single activity.json read the sidebar pills already make.

Piece Where
ESCALATION_THRESHOLD_MS (30 min) + resolveEscalationThresholdMs app/lib/activity.server.ts
statusSince on AgentActivity, plus its coercion app/lib/activity.shared.ts
escalatedAgents() app/lib/activity.shared.ts
formatDurationHm() app/lib/time.ts
escalated prop + top-bar alert UI app/components/AppShell.tsx
Loader wiring (one read, two consumers) app/routes/shell.tsx

Decisions worth a reviewer's eye

A bad ESCALATION_THRESHOLD_MS degrades, it never reshapes the alert. Blank, unparseable, zero and negative all fall back to the default, loudly. Zero would escalate everything the instant an agent went stuck; NaN compares false against every duration and would escalate nothing, silently. Both are worse than ignoring the override.

A record with no statusSince is skipped, with no fallback to updated. The fallback reads as reasonable, since updated is normally seconds old and stands in for "just entered this status". It only holds while the sweep is healthy. If the sweep itself stalls, which is precisely the failure this alert exists to notice, updated stops advancing and the gap grows without bound, firing a false escalation off data staleness at the exact moment the alert's own inputs became unreliable. statusSince is also coerced to genuinely absent rather than a stored null, because new Date(null) is the epoch and would escalate by about 56 years.

The chip names the agent in visible text, not just aria-label. One escalated agent renders "quill stuck for 45m" linking straight to the thread; more than one renders a dropdown with a count. The duration is the number you price the interruption with, so it cannot live behind a screen reader or a mouse-only title= that never fires on touch. The accessible name opens with the visible label verbatim (WCAG 2.5.3 Label in Name), pinned by test as a prefix rather than a toContain.

The header now wraps rather than overflows. That reason text is about 176px of deliberately unshrinkable content. Dropped into the right-hand cluster it took it from 132px to 264px, and the left group's shrink-0 children (avatar, chat/terminal toggle) then overflowed their min-w-0 box and were painted underneath it. Measured in Chromium against the real stylesheet: at 375px the toggle overlapped the chip by 58px and the thread title was crushed to zero width; at 320px all 78px of the toggle sat under the chip and stopped taking taps entirely. So: min-h-14 with flex-wrap, flex-1 on the identity group so it is the half that yields, overflow-hidden as the backstop, and the cluster goes w-full below lg only in the single-agent case, so no escalation and the multi-agent dropdown both stay on one row.

Tests

  • test/activity-escalation.test.ts (18 cases): threshold boundary just under / at / just over, status filtering, every missing-and-malformed statusSince path, the env resolver, and the parse coercion.
  • test/app-shell-escalation.test.tsx (9 cases): absent / single / multiple rendering, the visible reason, the accessible name, and that it stays a distinct control from the bell.
  • e2e/layout/escalation-header.test.ts (5 cases): real-viewport header geometry at 320, 375 and 1280, with elementFromPoint hit tests as the load-bearing assertion, since getBoundingClientRect reports the layout rect and would have called the occluded toggle fine. ESC-05 points the same server at a document with nothing escalated, so an unconditional wrap cannot pass this suite.

The alert's gate (ACTIVITY_ROOT) is read once at boot, so it cannot be toggled per test. The layout suite therefore gets its own server on 3918 with its own roots, rather than switching the main e2e instance onto the activity-configured branch and disturbing suites that assert the other one by name.

Deliberately not included

The narrator activity-panel inference: AgentInference, the task-line and progress-note display, and the stale-reason UI. Upstream it lives in the same file as this work but shares no code path with it, and it is being actively rewritten, so porting it now would port a moving target. This PR is escalation only.

Checks

Check Result
pnpm typecheck pass
pnpm check:boundaries pass, no violations
pnpm check:dashes pass
node scripts/leak-gate.mjs --self-test pass, 30 rules
node scripts/leak-gate.mjs clean, 371 files
pnpm test 1843 pass, 1 pre-existing flake (see below)
pnpm e2e --project=layout 5/5 pass

Three things a reviewer should know rather than discover:

  1. test/skeleton.test.ts "home.tsx exports a default function" times out at 5s on a cold transform cache under load. It fails the same way on unmodified main and passes on any warm re-run.
  2. node scripts/leak-gate.mjs --messages reports two findings, both on commits this branch did not author: one on main's own tip (the maintainer address in a squash-merge trailer, which fix(blocks): an empty subject ends its header in a space, and trim() took it #2 exists to exempt) and one on another open branch. This branch's commit adds none. Worth confirming before merge, since --messages scans rev-list --all.
  3. pnpm e2e flows has five failures on unmodified main (custom-answer, malformed-block, resizable, thread-windowing, card-reply-cross-route:135). They fail identically with and without this branch, and are not touched by it.

An agent can go quiet in a way nothing on screen reports: stuck behind a
permission dialog, or waiting on a person who has not looked. The sidebar
pill says "stuck" only while you are looking at the sidebar, and the
needs-you bell counts things to action, not things that have stopped
moving. Neither surfaces "this has been true for 45 minutes".

This adds the alert that does, on the same single activity.json read the
sidebar pills already make:

- ESCALATION_THRESHOLD_MS (30 minutes) and resolveEscalationThresholdMs,
  a per-instance override that DEGRADES to the default on blank, garbage,
  zero or negative input. Zero would escalate everything and NaN would
  escalate nothing, so both fall back rather than silently reshaping the
  alert.
- statusSince on AgentActivity, optional and coerced to absent rather
  than null, since a sweep older than that producer field writes records
  without it.
- escalatedAgents(): pure, injected clock, stuck/needs-you only. A record
  with no statusSince is SKIPPED, with deliberately no fallback to
  `updated`: if the sweep itself stalls, which is the failure this alert
  exists to notice, `updated` stops advancing and the gap grows without
  bound, firing a false escalation off data staleness at the exact moment
  its own inputs became unreliable.
- formatDurationHm(): "2h 15m" / "12m", the elapsed span the alert needs
  rather than date-fns' "about 2 hours ago".
- AppShell `escalated` prop. One agent renders a chip naming it in
  visible text ("quill stuck for 45m") that links straight to the thread;
  more than one renders a dropdown with a count. Destructive tint and a
  TriangleAlert keep it from reading as part of the bell's queue: it is a
  different claim, not another item to action.

The reason text is 176px of unshrinkable content, so the header wraps
instead of overflowing. `min-h-14` with `flex-wrap`, `flex-1` on the
identity group so it yields first, `overflow-hidden` as the backstop, and
the control cluster goes `w-full` below `lg` ONLY in the single-agent
case. Measured, not reasoned about: before this, at 375px the thread
toggle was painted under the chip and at 320px all 78px of it was, which
made it untappable. e2e/layout pins that with hit tests at 320, 375 and
1280, including a case with nothing escalated so an unconditional wrap
cannot pass.

The alert's gate is read once at boot, so it cannot be toggled per test.
The layout suite therefore gets its own server on 3918 with its own
roots, rather than switching the main e2e instance onto the
activity-configured branch and disturbing suites that assert the other
one.

DELIBERATELY NOT INCLUDED: the narrator activity-panel inference (task
line, progress note, stale-reason display). It shares a file with this
work upstream but no code path, and it is being rewritten, so porting it
now would port a moving target.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@simon-inkie
simon-inkie merged commit 5c3bbc6 into main Aug 18, 2026
1 of 4 checks passed
simon-inkie added a commit that referenced this pull request Aug 18, 2026
An agent can go quiet in a way nothing on screen reports: stuck behind a
permission dialog, or waiting on a person who has not looked. The sidebar
pill says "stuck" only while you are looking at the sidebar, and the
needs-you bell counts things to action, not things that have stopped
moving. Neither surfaces "this has been true for 45 minutes".

This adds the alert that does, on the same single activity.json read the
sidebar pills already make:

- ESCALATION_THRESHOLD_MS (30 minutes) and resolveEscalationThresholdMs,
  a per-instance override that DEGRADES to the default on blank, garbage,
  zero or negative input. Zero would escalate everything and NaN would
  escalate nothing, so both fall back rather than silently reshaping the
  alert.
- statusSince on AgentActivity, optional and coerced to absent rather
  than null, since a sweep older than that producer field writes records
  without it.
- escalatedAgents(): pure, injected clock, stuck/needs-you only. A record
  with no statusSince is SKIPPED, with deliberately no fallback to
  `updated`: if the sweep itself stalls, which is the failure this alert
  exists to notice, `updated` stops advancing and the gap grows without
  bound, firing a false escalation off data staleness at the exact moment
  its own inputs became unreliable.
- formatDurationHm(): "2h 15m" / "12m", the elapsed span the alert needs
  rather than date-fns' "about 2 hours ago".
- AppShell `escalated` prop. One agent renders a chip naming it in
  visible text ("quill stuck for 45m") that links straight to the thread;
  more than one renders a dropdown with a count. Destructive tint and a
  TriangleAlert keep it from reading as part of the bell's queue: it is a
  different claim, not another item to action.

The reason text is 176px of unshrinkable content, so the header wraps
instead of overflowing. `min-h-14` with `flex-wrap`, `flex-1` on the
identity group so it yields first, `overflow-hidden` as the backstop, and
the control cluster goes `w-full` below `lg` ONLY in the single-agent
case. Measured, not reasoned about: before this, at 375px the thread
toggle was painted under the chip and at 320px all 78px of it was, which
made it untappable. e2e/layout pins that with hit tests at 320, 375 and
1280, including a case with nothing escalated so an unconditional wrap
cannot pass.

The alert's gate is read once at boot, so it cannot be toggled per test.
The layout suite therefore gets its own server on 3918 with its own
roots, rather than switching the main e2e instance onto the
activity-configured branch and disturbing suites that assert the other
one.

DELIBERATELY NOT INCLUDED: the narrator activity-panel inference (task
line, progress note, stale-reason display). It shares a file with this
work upstream but no code path, and it is being rewritten, so porting it
now would port a moving target.

Co-authored-by: Simon <simon@inkie.ink>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

0