Closes#1695.
@Patrick-81 reported the bare "AIAgent not available -- check that
hermes-agent is on sys.path" error on a symlinked install (~/Programmes/hermes-agent
linked to ~/hermes-agent). The maintainer's response — three diagnostic
commands plus `pip install -e .` in the agent dir — fixed it for them.
This PR captures both halves of that learning so the next user with the
same shape doesn't have to file a new issue:
1. **Error message diagnostic block.** New helper
`_aiagent_import_error_detail()` in api/streaming.py builds a multi-line
diagnostic when the import fails, including:
- the running Python interpreter
- HERMES_WEBUI_AGENT_DIR (set value, or "(not set)")
- sys.path entries that mention hermes/agent (or "no entries mention..."
— itself a strong diagnostic signal)
- the most-common fix (`pip install -e .` in the agent dir)
- a pointer to docs/troubleshooting.md
The original error message string is preserved as the FIRST line so
existing log scrapers and docs-search keep matching.
Helper is kept as a separate function so it stays out of the hot path
until we actually need to raise — building it on every successful import
would be wasted work.
2. **New docs/troubleshooting.md.** Symptom → Why → Diagnostic commands →
Fix → When-to-file-a-bug template, with one entry to start: the
"AIAgent not available" flow Patrick-81 walked through. Future
recurring failure modes follow the same template. Required a one-line
addition to .gitignore — docs/* is gitignored with an allowlist, and
the new file needed `!docs/troubleshooting.md` to be tracked.
3. **README link.** docs/troubleshooting.md added to the `## Docs` section
so users know where to look first.
13 regression tests in tests/test_1695_aiagent_import_error_detail.py:
9 for the helper output shape (preserves original message line, includes
running python, shows HERMES_WEBUI_AGENT_DIR set/unset both ways, includes
pip-install-e hint, points at troubleshooting doc, lists relevant sys.path
entries when present, says "no entries..." when absent, output is multi-line)
plus 4 for the docs-presence regression (file exists, has the AIAgent
section, includes pip install -e ., describes the diagnostic chain with
readlink + agent/__init__.py verification).
190 streaming/aiagent tests pass after the change. ast.parse on
api/streaming.py clean.
CI failure on prior push was due to the docs/* gitignore swallowing the
new troubleshooting.md file silently — this commit adds the allowlist
entry so the file is tracked.
Closes#1707 — single-click on a workspace tree filename did nothing.
#1698 was a regression where the filename's dblclick rename handler was
unreachable because the row's el.onclick (openFile) fired synchronously
on the first click. The fix in #1702 stopped click propagation on nameEl
— but that broke single-click activation entirely (#1707): clicking the
filename now did nothing, you had to click the icon or row whitespace
to open the file.
Restored fix preserves both intents via a 300ms debounced delegator:
let _nameClickTimer = null;
nameEl.onclick = (e) => {
e.stopPropagation();
if (_nameClickTimer) { clearTimeout(_nameClickTimer); _nameClickTimer = null; }
_nameClickTimer = setTimeout(() => {
_nameClickTimer = null;
if (typeof el.onclick === 'function') el.onclick(e);
}, 300);
};
nameEl.ondblclick = (e) => {
e.stopPropagation();
if (_nameClickTimer) { clearTimeout(_nameClickTimer); _nameClickTimer = null; }
// ... existing rename body
};
Single-click on nameEl schedules a setTimeout that calls el.onclick(e)
after the dblclick threshold passes (300ms — matches the OS dblclick
threshold on most platforms). Double-click cancels the pending timer
and triggers the existing rename input.
Cost: 300ms latency on file-open clicks. Acceptable trade for keeping
rename reachable on single-click.
Also updated tests/test_workspace_tree_rename.py to accept both the
pre-#1707 (pure stopPropagation) and post-#1707 (debounced delegator)
shapes — the original assertion was too narrow and would have rejected
the correct fix.
9 new regression tests in tests/test_1707_workspace_filename_click.py:
- 6 source-level static-analysis checks on the patched handler shape
- 3 behavioral tests via Node VM (synthesize click → 300ms delay,
click → dblclick within tick → assert rename mounts + openFile
is not called).
7 of 9 tests fail on master pre-fix (verified); all 9 pass after.
CHANGELOG.md: full v0.51.1 entry covering all 11 constituent PRs
ROADMAP.md: bump version + test count to 4429
TESTING.md: bump version + test count to 4429
Independent review: Opus advisor on stage-298 diff (4749 LOC).
6/6 security/correctness questions verified clean. Verdict: SHIP.
0 MUST-FIX, 0 SHOULD-FIX. Two polish notes deferred to follow-up.
CHANGELOG.md: full v0.51.0 entry covering the 12-commit Kanban stack
(#1645, #1646, #1647, #1649, #1654, #1655, #1660, #1675) including
multi-board management, SSE event stream, dispatcher contract enforcement,
CSS-injection fix, archive race fix, mobile responsive, and 35 new
Kanban-specific tests (33 -> 68).
ROADMAP.md, TESTING.md: bumped to v0.51.0 / 4356 tests / 'Kanban v1 launch'.
Major version bump from 0.50.x -> 0.51.0 reflects the size and significance
of the feature: first-party-compatible Kanban surface (CRUD on /api/kanban/boards
+ real-time SSE event stream) parity-verified against the Hermes Agent
dashboard plugin. Independent review APPROVED, Opus advisor SHIP, all
SHOULD-FIX absorbed in-release with regression tests.
Constituent PRs:
#1637 by @Michaelyklam — protect raw pre from glued-bold lift (closes#1451)
#1639 by @bergeouss — macOS auto-scroll race + custom:* provider list (closes#1360, #1619)
#1642 by @nesquena-hermes — YAML/JSON/diff code block newlines (closes#1618, #1463)
Opus advisor SHIP verdict on stage-295. One observation absorbed:
- api/config.py:2533 dead-code comment per Opus (defensive belt-and-braces
for #1619 fallback; load-bearing fix is in routes.py /api/models/live)
PR #1641 (Michaelyklam parallel-discovery duplicate of #1642) closed as
superseded; UI media adopted with co-author trailer.
4245 → 4255 tests passing (+10).
Closes#1579.
api/updates.py was building the GitHub compare URL from local HEAD short SHA:
repoUrl + '/compare/' + curSha + '...' + newSha
where curSha = `git rev-parse --short HEAD`
Whenever local HEAD diverges from upstream — unpushed work, dirty stage
branches, forks, in-flight rebases, release-time merge commits whose SHA
only lives in the maintainer's local history — the compare URL points at
a SHA github.com has never seen and returns the standard 404 page.
Reporter (@ai-ag2026) observed:
c660c7f...86cb22e
→ 404 because c660c7f was an unpushed local commit.
The right base is `git merge-base HEAD <compare_ref>` — the most recent
commit local and upstream share. Since `git fetch` succeeded just before,
the merge-base is guaranteed to exist on the upstream GitHub repo.
Behavior matrix:
Pure-behind clone (no local commits): merge-base == HEAD; URL unchanged.
Behind + local-only commits (#1579): merge-base != HEAD; URL points at
public ancestor instead of local HEAD.
merge-base failure (shallow clone): current_sha=None; JS link guard
suppresses link rather than emitting
a known-broken URL.
Also hardens static/ui.js: reset the link's href and display:none on every
banner render, so a stale link from a prior render can't survive a re-render
where the new payload has current_sha=null.
Tests:
- test_current_sha_is_merge_base_not_local_HEAD — reporter's scenario
- test_current_sha_equals_HEAD_when_no_local_commits — backward compat
- test_current_sha_falls_back_to_None_when_merge_base_fails — defensive
- test_whats_new_link_resets_display_and_href_on_every_render
- test_whats_new_link_suppressed_when_curSha_falsy
- test_reporter_url_shape_no_longer_produces_invalid_compare_url
4094 → 4100 passing. 0 regressions.
v0.50.284 shipped startup self-heal in api/session_recovery.py that
crashed on the very first JSON file it scanned in the production
session directory. Verified live on the prod server immediately after
the v0.50.284 deploy:
[recovery] startup recovery failed: 'list' object has no attribute 'get'
Root cause: the production session dir contains _index.json — a
top-level LIST of session metadata dicts (not a dict). _msg_count()
did data.get('messages') which raises AttributeError on a list.
The broad except Exception in server.py's startup hook swallowed the
error and the recovery silently no-op'd for every user — defeating
the entire purpose of the v0.50.284 release.
Fix is three small defensive changes:
1. _msg_count() — added isinstance(data, dict) guard. Non-dict-shaped
JSON files now return -1 (the harmless 'unknown count' sentinel)
instead of raising AttributeError.
2. recover_all_sessions_on_startup() — skips any file whose name starts
with '_' (the existing project convention for non-session metadata
files like _index.json). These are convention-marked as system
files, not session payloads.
3. recover_all_sessions_on_startup() — wraps recover_session(path) in
try/except Exception so a single malformed file can't break recovery
for the rest. Logs and continues.
2 new regression tests:
- test_recover_all_sessions_on_startup_skips_non_session_index_json
- test_msg_count_returns_neg1_for_non_dict_top_level
4026 → 4028 tests passing (+2).
Net effect: any user wiped between v0.50.279 and v0.50.284 deploys
whose session has a .bak shadow will now get auto-recovered on first
launch of v0.50.285, as v0.50.284's release notes promised.
Closes#1558 (follow-up — the original P0 was closed by v0.50.284 but
the recovery half didn't actually run in production).
Both files had drifted significantly from the actual current state of the
project:
ROADMAP.md previously contained:
- A ~75-row 'sprint history' table that overlapped with CHANGELOG.md
- A 'Wave 2 Core' section frozen at Sprint 7 progress
- A 'Wave 2: Full CRUD' nested section repeating the same Wave 7 items
- A 'User Requested Features' table that double-counted the same shipped issues
- A 'Feature Parity Checklist' with many unchecked boxes that were actually shipped
(branch/fork via #465, LLM-generated session titles via auto_title_refresh_every,
workspace git detection at api/workspace.py:719, code execution and TTS
reclassified, etc.)
SPRINTS.md previously contained:
- 1159 lines of historical sprint plans (Sprints 11-26)
- Inline planning detail more appropriate for the private workspace
- Stale 'as of v0.50.245' header with 'next sprint Sprint 24' reference
- Track-A/B/C breakdowns from sprints already long-merged
Rewrite:
ROADMAP.md (now 397 lines, was 363):
- Status snapshot table at the top
- Architecture table reflecting current layout (api/ ~20k LOC, static/*.js ~26k LOC)
- Feature parity checklist reorganized by surface (chat / sessions / workspace /
cron / skills / memory / profiles / config / security / visual / voice /
mobile / i18n / gateway / MCP / distribution) with every line currently in
master correctly checked
- 'Forward work' section split into confirmed candidates (with tracking issue
numbers) vs deferred backlog vs intentionally not planned
- 'Sprint history' compressed to a single chronological theme table — per-version
detail explicitly redirects to CHANGELOG.md
- Versioning conventions documented
SPRINTS.md (now 165 lines, was 1159):
- Forward-looking only — no historical sprint plans (those live in CHANGELOG.md)
- Active sprint candidates table sourced from the sprint-candidate label
- Planning principles section (phase-0 fit assessment, salvage over absorb,
independent-review gate, per-PR release velocity, no feature creep mid-PR,
pre-release gate)
- Sprint shape table (typical 3-7 day sprint with phases)
- Out-of-scope section centralized
- Template for new sprint plans
Also updates TESTING.md test count 3990 → 3995 to match actual pytest collect.
No private workspace info, agent infra references, or contributor stipend
content. References to the maintainer's private planning notes are
acknowledged as 'in a private workspace' without further specifics — same
disclosure pattern most open-source projects use.
CHANGELOG, ROADMAP, TESTING bumped (3929 \u2192 3936).
Pre-release Opus advisor pass: SHIP AS-IS. Sentinel collision impossible
(UUID hex \u2014 no underscores), stale-active-filter on project delete safe,
CSS specificity clean. One non-blocking edge case (stuck filter at zero
projects + zero unassigned) explicitly deferred per Opus advice
(recoverable via reload, too narrow to justify pre-merge work).
Both contributors (Thanatos-Z and AlexeyDsov) credited via Co-authored-by
trailers preserved from the synthesis commit.
CHANGELOG, ROADMAP, TESTING bumped (3925 → 3929 tests collected).
Opus SHOULD-FIX absorbed in-release: tests #1-3 documented the dedup
contract via direct construction but did not invoke get_models_grouped().
Test #4 (test_get_models_grouped_unconfigured_providers_get_independent_dicts)
inspects the live source for the literal copy.deepcopy(auto_detected_models)
call AND runs an end-to-end smoke of the fixed assignment loop.
A future refactor that removes the deepcopy at api/config.py:2078 will
fail this test immediately.
CHANGELOG, ROADMAP, TESTING all updated.
3923 → 3925 tests collected (+2 regression tests).
Pre-release Opus advisor pass: SHIP AS-IS.
Independent review: nesquena APPROVED with end-to-end trace.
Migration note: existing v0.50.275 users will see one more round of
broken styling on first reload after upgrade (old SW serves old
index.html). Subsequent reloads clean. Future upgrades will not
recur because SW pre-cache is now keyed on versioned URL.
Filed follow-up #1509 for __CACHE_VERSION__/__WEBUI_VERSION__
placeholder consolidation (low-priority cleanup, no functional impact).
- CHANGELOG.md: v0.50.270 entry detailing #1315 + maintainer follow-ups
- ROADMAP.md: bump to v0.50.270, 3849 tests collected
- TESTING.md: bump header + total to 3849
- bootstrap.py: Opus advisor optional-followup — PYTHONPATH prepend comment
#1315 by @ccqqlo (113 LOC): bootstrap.py validates launcher Python can
import both yaml and run_agent.AIAgent. Companion fix to v0.50.269's #1478
— addresses the start-healthy-then-cryptic-fail mode (different from #1478's
supervisor-respawn loop).
3849 tests pass. Opus advisor verdict: ship as-is. CI green on contributor
branch + on local stage. QA harness all green.
