hx-cli 0.2.8__tar.gz → 0.2.9__tar.gz

{hx_cli-0.2.8 → hx_cli-0.2.9}/CHANGELOG.md

@@ -28,6 +28,23 @@ the project follows [semantic versioning](https://semver.org/).
 
 ---
 
+## [0.2.9] - 2026-09-27
+
+### Added
+
+- `~/.hx/AGENTS.md` holds your own instructions and is loaded into every
+  session in every project, ahead of the project's `AGENTS.md`. The first
+  session creates it empty, ready to fill in. `hx prompt` and `/prompt` now
+  name each `AGENTS.md` in force, and `/prompt` says when one has changed on
+  disk since the session started.
+
+### Fixed
+
+- An `AGENTS.md` or system-prompt override that is not valid UTF-8 is skipped
+  like an unreadable one, instead of stopping HX from starting.
+
+---
+
 ## [0.2.8] - 2026-09-27
 
 ### Changed
@@ -725,7 +742,8 @@ First release, published to PyPI as [`hx-cli`](https://pypi.org/project/hx-cli/)
 - `/configure` and `hx auth` for the OpenRouter key, `hx upgrade` for
   self-update, and `install.sh` bootstrapping uv with a pinned Python.
 
-[Unreleased]: https://github.com/aletisunil/hx/compare/v0.2.8...HEAD
+[Unreleased]: https://github.com/aletisunil/hx/compare/v0.2.9...HEAD
+[0.2.9]: https://github.com/aletisunil/hx/compare/v0.2.8...v0.2.9
 [0.2.8]: https://github.com/aletisunil/hx/compare/v0.2.7...v0.2.8
 [0.2.7]: https://github.com/aletisunil/hx/compare/v0.2.6...v0.2.7
 [0.2.6]: https://github.com/aletisunil/hx/compare/v0.2.5...v0.2.6

{hx_cli-0.2.8 → hx_cli-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hx-cli
-Version: 0.2.8
+Version: 0.2.9
 Summary: HX - an agent harness for the terminal
 Project-URL: Homepage, https://hx.sunilaleti.dev
 Project-URL: Documentation, https://hx.sunilaleti.dev
@@ -753,6 +753,7 @@ files load here unchanged. `src/hx/tui/themes/dark.json` is the reference.
 | `~/.hx/keybindings.json` | your key overrides |
 | `~/.hx/system-prompt.md` | your system prompt, replacing the built-in one |
 | `~/.hx/system-prompt-append.md` | text appended to whichever prompt is in force |
+| `~/.hx/AGENTS.md` | your instructions, loaded into every session in every project; created empty |
 | `~/.hx/sessions/` | transcripts, spilled tool output, subagent sessions |
 | `~/.hx/sessions/<id>/trace.html` | where `/trace` writes, unless you name a path |
 | `~/.hx/skills/`, `~/.hx/agents/` | your skills and agents |
@@ -767,6 +768,12 @@ files load here unchanged. `src/hx/tui/themes/dark.json` is the reference.
 tests, conventions, what not to touch. `/init` writes a first draft. It is
 loaded once per session and frozen, so it costs one prefix, not one per turn.
 
+`~/.hx/AGENTS.md` is the same thing for you rather than the project: how you
+like commits written, tools you always want used, in every repository. It is
+loaded first and the project's `AGENTS.md` after it, so where the two disagree
+the project has the last word. The first session creates it empty, ready to
+fill in; empty, it adds nothing. `hx prompt` and `/prompt` list each one in force.
+
 ---
 
 ## Safety

{hx_cli-0.2.8 → hx_cli-0.2.9}/README.md

@@ -713,6 +713,7 @@ files load here unchanged. `src/hx/tui/themes/dark.json` is the reference.
 | `~/.hx/keybindings.json` | your key overrides |
 | `~/.hx/system-prompt.md` | your system prompt, replacing the built-in one |
 | `~/.hx/system-prompt-append.md` | text appended to whichever prompt is in force |
+| `~/.hx/AGENTS.md` | your instructions, loaded into every session in every project; created empty |
 | `~/.hx/sessions/` | transcripts, spilled tool output, subagent sessions |
 | `~/.hx/sessions/<id>/trace.html` | where `/trace` writes, unless you name a path |
 | `~/.hx/skills/`, `~/.hx/agents/` | your skills and agents |
@@ -727,6 +728,12 @@ files load here unchanged. `src/hx/tui/themes/dark.json` is the reference.
 tests, conventions, what not to touch. `/init` writes a first draft. It is
 loaded once per session and frozen, so it costs one prefix, not one per turn.
 
+`~/.hx/AGENTS.md` is the same thing for you rather than the project: how you
+like commits written, tools you always want used, in every repository. It is
+loaded first and the project's `AGENTS.md` after it, so where the two disagree
+the project has the last word. The first session creates it empty, ready to
+fill in; empty, it adds nothing. `hx prompt` and `/prompt` list each one in force.
+
 ---
 
 ## Safety

{hx_cli-0.2.8 → hx_cli-0.2.9}/src/hx/__init__.py

@@ -1,5 +1,5 @@
 """HX - an agent harness for the terminal."""
 
-__version__ = "0.2.8"
+__version__ = "0.2.9"
 
 __all__ = ["__version__"]

{hx_cli-0.2.8 → hx_cli-0.2.9}/src/hx/cli.py

@@ -346,7 +346,12 @@ def build_runtime(parsed: ParsedArgs, *, resume: str | None = None) -> Runtime:
     from hx.config import load_settings
     from hx.core.checkpoints import CheckpointStore
     from hx.core.compaction import Compactor
-    from hx.core.context import ContextBuilder, build_project_context, load_system_prompt
+    from hx.core.context import (
+        ContextBuilder,
+        build_project_context,
+        load_instructions,
+        load_system_prompt,
+    )
     from hx.core.events import EventBus
     from hx.core.lateinject import Injection, InjectionRegistry
     from hx.core.loop import AgentLoop
@@ -430,6 +435,7 @@ def build_runtime(parsed: ParsedArgs, *, resume: str | None = None) -> Runtime:
         settings.cwd,
         keep_recent_turns=settings.context.keep_recent_turns,
     )
+    instructions = load_instructions(settings.cwd)
 
     checkpoints = CheckpointStore(session, session_checkpoints_dir(session.meta.session_id))
     tools = build_default_registry(shell, jobs, tracker, todos, bus_holder, auth, checkpoints)
@@ -478,7 +484,8 @@ def build_runtime(parsed: ParsedArgs, *, resume: str | None = None) -> Runtime:
         settings=settings,
         model_info=model_info,
         skills_index=build_index(list(skills.values())) or None,
-        project_context=build_project_context(settings.cwd),
+        project_context=build_project_context(settings.cwd, instructions),
+        instructions=instructions,
         hooks=hooks,
     )
 
@@ -842,15 +849,17 @@ def run_print_command(parsed: ParsedArgs) -> int:
 def run_prompt_command(parsed: ParsedArgs) -> int:
     """``hx prompt`` - print the system prompt this directory resolves to.
 
-    The prompt goes to stdout so it can be piped or diffed; where it came from
-    goes to stderr so it never contaminates that output.
+    The prompt goes to stdout so it can be piped or diffed; where it came from,
+    and which AGENTS.md files ride alongside it, goes to stderr so it never
+    contaminates that output.
     """
     from hx.config import load_settings
-    from hx.core.context import resolve_system_prompt
+    from hx.core.context import load_instructions, resolve_system_prompt
 
     try:
         settings = load_settings(parsed.cwd, parsed.overrides)
         resolved = resolve_system_prompt(settings.cwd, settings.prompt)
+        instructions = load_instructions(settings.cwd)
     except Exception as exc:
         return _report(exc)
 
@@ -858,6 +867,8 @@ def run_prompt_command(parsed: ParsedArgs) -> int:
     print(f"[source] {resolved.source}", file=sys.stderr)
     for append in resolved.appends:
         print(f"[append] {append}", file=sys.stderr)
+    for loaded in instructions:
+        print(f"[instructions] {loaded.path}", file=sys.stderr)
     return 0
 
 

{hx_cli-0.2.8 → hx_cli-0.2.9}/src/hx/core/context.py

@@ -10,7 +10,7 @@ Layout, in order::
     [1] system prompt          static for the session
     [2] tool schemas           deterministic sort: builtins, then mcp__* alphabetical
     [3] skills index           name + description only (progressive disclosure)
-    [4] project context        AGENTS.md, cwd, git branch, top-level listing
+    [4] project context        cwd, git branch, top-level listing, ~/.hx/AGENTS.md, AGENTS.md
     --- breakpoint A (static) ---
     [5] conversation history
     --- breakpoint B (rolling, before the last few turns) ---
@@ -238,11 +238,46 @@ def _message_text(message: Message) -> str:
     return "\n".join(parts)
 
 
-def build_project_context(cwd: Path) -> str:
-    """Static per-session project preamble: AGENTS.md contents, cwd, git branch, listing.
+@dataclass(slots=True)
+class Instructions:
+    """One AGENTS.md in force: what it is, where it lives, what it says."""
+
+    heading: str
+    path: Path
+    text: str
+
+
+def load_instructions(cwd: Path) -> list[Instructions]:
+    """Every AGENTS.md in force, least specific first.
+
+    ``~/.hx/AGENTS.md`` follows the user into every project; the project's own
+    ``AGENTS.md`` comes after it, so where the two disagree the more specific
+    one has the last word. A blank or unreadable file is skipped, and running
+    from inside ``$HX_HOME`` - where both paths name the same file - loads it once.
+    """
+    from hx.paths import project_instructions_file, tilde, user_instructions_file
+
+    user = user_instructions_file()
+    found: list[Instructions] = []
+    seen: set[Path] = set()
+    for heading, path in (
+        (f"User instructions ({tilde(user)})", user),
+        ("Project instructions (AGENTS.md)", project_instructions_file(cwd)),
+    ):
+        body = _read_prompt_file(path)
+        if not body or path.resolve() in seen:
+            continue
+        seen.add(path.resolve())
+        found.append(Instructions(heading, path, body))
+    return found
+
+
+def build_project_context(cwd: Path, instructions: list[Instructions] | None = None) -> str:
+    """Static per-session project preamble: cwd, git branch, listing, AGENTS.md contents.
 
     Computed once at startup and then frozen - refreshing it mid-session would
-    invalidate the prefix.
+    invalidate the prefix. Pass ``instructions`` to fold in the AGENTS.md files
+    already loaded, so the caller can remember exactly which ones are in force.
     """
     lines = [f"Working directory: {cwd}"]
 
@@ -256,9 +291,8 @@ def build_project_context(cwd: Path) -> str:
     if entries:
         lines.append("Top level: " + ", ".join(entries[:60]))
 
-    agents_md = cwd / "AGENTS.md"
-    if agents_md.is_file():
-        lines.append(f"\n# Project instructions (AGENTS.md)\n\n{agents_md.read_text()}")
+    for loaded in load_instructions(cwd) if instructions is None else instructions:
+        lines.append(f"\n# {loaded.heading}\n\n{loaded.text}")
 
     return "\n".join(lines)
 
@@ -367,12 +401,12 @@ def resolve_system_prompt(cwd: Path, prompt: PromptSettings | None = None) -> Re
 def _read_prompt_file(path: Path) -> str:
     """Contents of a prompt override file, or ``""`` when it is absent or empty.
 
-    An unreadable file is treated as absent: a permissions problem on an
-    optional override must not stop the session from starting.
+    An unreadable file - no permission, or not UTF-8 - is treated as absent: a
+    problem with an optional override must not stop the session from starting.
     """
     try:
-        return path.read_text().strip() if path.is_file() else ""
-    except OSError:
+        return path.read_text(encoding="utf-8").strip() if path.is_file() else ""
+    except (OSError, UnicodeDecodeError):
         return ""
 
 

{hx_cli-0.2.8 → hx_cli-0.2.9}/src/hx/core/loop.py

@@ -18,7 +18,7 @@ import time
 from dataclasses import dataclass, replace
 from typing import TYPE_CHECKING, Any, ClassVar
 
-from hx.core.context import AssembledContext
+from hx.core.context import AssembledContext, Instructions
 from hx.core.events import (
     CompactionFinished,
     CompactionStarted,
@@ -103,6 +103,7 @@ class AgentLoop:
         active_skills: ActiveSkills | None = None,
         skills_index: str | None = None,
         project_context: str | None = None,
+        instructions: list[Instructions] | None = None,
         hooks: HookEngine | None = None,
     ) -> None:
         self.provider = provider
@@ -118,6 +119,8 @@ class AgentLoop:
         self.active_skills = active_skills
         self.skills_index = skills_index
         self.project_context = project_context
+        self.instructions = instructions or []
+        """The AGENTS.md files folded into ``project_context``, least specific first."""
         self.hooks = hooks
         self._cancelled = False
         self._turn_index = 0

{hx_cli-0.2.8 → hx_cli-0.2.9}/src/hx/paths.py

@@ -30,6 +30,20 @@ def user_home() -> Path:
     return Path(override).expanduser() if override else Path.home() / ".hx"
 
 
+def tilde(path: str | Path) -> str:
+    """``path`` with the home directory written as ``~``.
+
+    Compared as text, not resolved: a session records the path it resolved
+    when it was made, and the directory may be gone by the time it is drawn.
+    """
+    text, home = str(path), str(Path.home())
+    if text == home:
+        return "~"
+    if text.startswith(home.rstrip("/") + "/"):
+        return "~" + text[len(home.rstrip("/")) :]
+    return text
+
+
 def user_settings_file() -> Path:
     return user_home() / "settings.json"
 
@@ -198,7 +212,28 @@ def project_system_prompt_append_file(cwd: Path | None = None) -> Path:
     return project_dir(cwd) / "system-prompt-append.md"
 
 
+def user_instructions_file() -> Path:
+    """Your ``AGENTS.md``: instructions that follow you into every project."""
+    return user_home() / "AGENTS.md"
+
+
+def project_instructions_file(cwd: Path | None = None) -> Path:
+    """The project's ``AGENTS.md``, at the root of the working directory."""
+    return (cwd or Path.cwd()) / "AGENTS.md"
+
+
 def ensure_user_dirs() -> None:
-    """Create the user-level directory skeleton if it does not exist."""
+    """Create the user-level skeleton if it does not exist.
+
+    That includes an empty ``AGENTS.md``, so there is a file to find and fill
+    in; empty, it adds nothing to the prompt. An existing one - including a
+    symlink, dangling or not - is never touched, and failing to create it never
+    stops a session: the file is optional.
+    """
     for path in (user_home(), sessions_dir(), user_skills_dir(), user_agents_dir(), logs_dir()):
         path.mkdir(parents=True, exist_ok=True)
+    try:
+        with user_instructions_file().open("x"):
+            pass
+    except OSError:
+        pass

{hx_cli-0.2.8 → hx_cli-0.2.9}/src/hx/tui/commands.py

@@ -507,7 +507,7 @@ async def cmd_title(ctx: CommandContext, args: str) -> None:
 
 async def cmd_prompt(ctx: CommandContext, args: str) -> None:
     """``/prompt`` - the system prompt this session is actually running with."""
-    from hx.core.context import resolve_system_prompt
+    from hx.core.context import load_instructions, resolve_system_prompt
 
     in_use = ctx.app.loop.context.system_prompt
     lines = [in_use.rstrip()]
@@ -516,10 +516,15 @@ async def cmd_prompt(ctx: CommandContext, args: str) -> None:
     lines.append(f"\nSource: {resolved.source}")
     for append in resolved.appends:
         lines.append(f"Appended: {append}")
+    in_force = ctx.app.loop.instructions
+    for loaded in in_force:
+        lines.append(f"Instructions: {loaded.path}")
+    # The prompt and AGENTS.md are read once at startup to keep the cache prefix
+    # stable, so an edit since then is real but not yet in force.
     if resolved.text.strip() != in_use.strip():
-        # The prompt is read once at startup to keep the cache prefix stable, so
-        # an override edited since then is real but not yet in force.
         lines.append("An override has changed on disk since startup; it applies next run.")
+    if load_instructions(ctx.settings.cwd) != in_force:
+        lines.append("An AGENTS.md has changed on disk since startup; it applies next run.")
     ctx.app.notice("\n".join(lines))
 
 
@@ -741,8 +746,7 @@ async def cmd_permissions(ctx: CommandContext, args: str) -> None:
         lines.append("")
         lines.append('No rules configured. Add them under "permissions" in .hx/settings.json.')
 
-    from hx.paths import project_local_settings_file
-    from hx.tui.format import tilde
+    from hx.paths import project_local_settings_file, tilde
 
     # Where, and why there: a grant is machine-local, so it is kept per project
     # under the user's home instead of being dropped into the checkout.

{hx_cli-0.2.8 → hx_cli-0.2.9}/src/hx/tui/format.py

@@ -11,7 +11,6 @@ from __future__ import annotations
 
 import re
 from collections.abc import Sequence
-from pathlib import Path
 
 from hx.term.sanitize import plain_text
 from hx.term.width import cell_width, truncate_to_width
@@ -76,17 +75,3 @@ def one_line(text: str, width: int) -> str:
     if cell_width(flat) <= width:
         return flat
     return truncate_to_width(flat, max(0, width - cell_width(ELLIPSIS))) + ELLIPSIS
-
-
-def tilde(path: str | Path) -> str:
-    """``path`` with the home directory written as ``~``.
-
-    Compared as text, not resolved: a session records the path it resolved
-    when it was made, and the directory may be gone by the time it is drawn.
-    """
-    text, home = str(path), str(Path.home())
-    if text == home:
-        return "~"
-    if text.startswith(home.rstrip("/") + "/"):
-        return "~" + text[len(home.rstrip("/")) :]
-    return text

{hx_cli-0.2.8 → hx_cli-0.2.9}/src/hx/tui/runtime.py

@@ -26,10 +26,10 @@ from hx.core.messages import (
 )
 from hx.core.usage import format_tokens
 from hx.git import BranchWatcher
+from hx.paths import tilde
 from hx.term.loop import TuiRunner
 from hx.term.modifiers import ShiftEnter
 from hx.term.terminal import Terminal
-from hx.tui.format import tilde
 from hx.tui.renderers import ToolCall
 from hx.tui.views.blocks import (
     AssistantMessage,

{hx_cli-0.2.8 → hx_cli-0.2.9}/src/hx/tui/views/pickers.py

@@ -16,9 +16,10 @@ import time
 from typing import Any, ClassVar
 
 from hx.core.usage import format_tokens
+from hx.paths import tilde
 from hx.term.component import Widget
 from hx.term.primitives import Lines, Rule, Spacer, Text
-from hx.tui.format import columns, one_line, tilde
+from hx.tui.format import columns, one_line
 from hx.tui.fuzzy import filter_items
 from hx.tui.glyphs import CURRENT, CURSOR, GUTTER
 from hx.tui.limits import LIST_MINIMUM, LIST_VISIBLE, RECORD_WIDTH

{hx_cli-0.2.8 → hx_cli-0.2.9}/tests/e2e/test_cli.py

@@ -134,10 +134,19 @@ def test_mcp_add_list_remove(hx: HX) -> None:
 
 
 def test_prompt_shows_project_instructions(hx: HX) -> None:
-    """`hx prompt` prints the system prompt with AGENTS.md folded in; provenance goes to stderr."""
+    """`hx prompt` prints the system prompt and names every AGENTS.md in force, user's first;
+    provenance goes to stderr."""
+    (hx.hx_home / "AGENTS.md").write_text("Sign off every answer.\n")
     (hx.project / "AGENTS.md").write_text("Always answer in haiku.\n")
     result = hx.run("prompt", "--append-system-prompt", "Mind the tests.", check=True)
     assert "[source]" in result.stderr
     assert "[append]" in result.stderr
     assert "[source]" not in result.stdout
     assert "Mind the tests." in result.stdout
+    instructions = [
+        line for line in result.stderr.splitlines() if line.startswith("[instructions] ")
+    ]
+    assert instructions == [
+        f"[instructions] {hx.hx_home / 'AGENTS.md'}",
+        f"[instructions] {hx.project / 'AGENTS.md'}",
+    ]

{hx_cli-0.2.8 → hx_cli-0.2.9}/tests/e2e/test_commands.py

@@ -107,6 +107,34 @@ def test_mode_command(hx: HX) -> None:
     assert f"plan · {SANDBOX_STATUS}" in term.lines()[-2]
 
 
+def test_prompt_command_names_the_agents_md_files(hx: HX) -> None:
+    """/prompt shows the running system prompt, then every AGENTS.md in force, user's first."""
+    (hx.hx_home / "AGENTS.md").write_text("Sign off every answer.\n")
+    (hx.project / "AGENTS.md").write_text("Always answer in haiku.\n")
+    term = hx.tui(columns=250, rows=60)
+    term.submit("/prompt")
+    screen = term.wait_for("Instructions: " + str(hx.project / "AGENTS.md"))
+    term.snapshot("/prompt")
+    user = screen.index("Instructions: " + str(hx.hx_home / "AGENTS.md"))
+    assert screen.index("Source: built-in") < user < screen.index(str(hx.project / "AGENTS.md"))
+
+
+def test_prompt_command_names_the_agents_md_in_force_not_on_disk(hx: HX) -> None:
+    """/prompt lists the AGENTS.md files the session started with; one written, edited or
+    emptied since is flagged as applying next run rather than claimed to be in force."""
+    (hx.project / "AGENTS.md").write_text("Always answer in haiku.\n")
+    term = hx.tui(columns=250, rows=60)
+    user_md = hx.hx_home / "AGENTS.md"
+    user_md.write_text("Sign off every answer.\n")
+    (hx.project / "AGENTS.md").write_text("")
+    term.submit("/prompt")
+    screen = term.wait_for("applies next run")
+    term.snapshot("/prompt after AGENTS.md changed on disk")
+    assert "Instructions: " + str(hx.project / "AGENTS.md") in screen
+    assert "Instructions: " + str(user_md) not in screen
+    assert "An AGENTS.md has changed on disk since startup; it applies next run." in screen
+
+
 def test_title_command(hx: HX, stub: Stub) -> None:
     """/title shows the model's name for the session, and /title <text> renames it."""
     stub.title = "Greeting exchange"

{hx_cli-0.2.8 → hx_cli-0.2.9}/tests/e2e/test_extend.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import os
 import sys
 from pathlib import Path
 
@@ -26,6 +27,84 @@ def test_agents_md_reaches_the_model(hx: HX, stub: Stub) -> None:
     assert "Run tests with `make check`" in json.dumps(stub.requests[0].messages)
 
 
+def test_user_agents_md_reaches_the_model_before_the_projects(hx: HX, stub: Stub) -> None:
+    """~/.hx/AGENTS.md rides in every request, ahead of the project's AGENTS.md, byte-stable
+    across turns."""
+    write(hx.hx_home / "AGENTS.md", "USER-RULE: write commit subjects in the imperative.\n")
+    write(hx.project / "AGENTS.md", "PROJECT-RULE: run tests with `make check`.\n")
+    write(hx.project / "notes.txt", "hello\n")
+    stub.script(call("Read", file_path=str(hx.project / "notes.txt")), say("Read it."))
+    hx.run("-p", "read notes.txt", check=True)
+
+    first, second = stub.requests[0].system, stub.requests[1].system
+    assert first == second
+    user = first.index("USER-RULE: write commit subjects")
+    project = first.index("PROJECT-RULE: run tests")
+    assert user < project
+    assert first.index("# User instructions") < user < first.index("# Project instructions")
+
+
+def test_user_agents_md_is_created_empty_and_never_clobbered(hx: HX, stub: Stub) -> None:
+    """The first session leaves an empty ~/.hx/AGENTS.md to fill in, adding nothing to the
+    prompt; later sessions load what the user wrote and never rewrite it, even through a
+    symlink into a dotfiles repo."""
+    user_md = hx.hx_home / "AGENTS.md"
+    assert not user_md.exists()
+    stub.script(say("Fine."))
+    hx.run("-p", "hi", check=True)
+    assert user_md.is_file() and user_md.read_text() == ""
+    assert "# User instructions" not in stub.requests[0].system
+
+    user_md.write_text("USER-RULE: sign off every answer.\n")
+    stub.script(say("Fine."))
+    hx.run("-p", "hi", check=True)
+    assert user_md.read_text() == "USER-RULE: sign off every answer.\n"
+    assert "USER-RULE: sign off every answer." in stub.requests[1].system
+
+    dotfiles = write(hx.home / "dotfiles" / "AGENTS.md", "DOTFILES-RULE: tabs, not spaces.\n")
+    user_md.unlink()
+    user_md.symlink_to(dotfiles)
+    stub.script(say("Fine."))
+    hx.run("-p", "hi", check=True)
+    assert user_md.is_symlink()
+    assert dotfiles.read_text() == "DOTFILES-RULE: tabs, not spaces.\n"
+    assert "DOTFILES-RULE: tabs, not spaces." in stub.requests[2].system
+
+
+def test_blank_unreadable_and_shared_agents_md_are_harmless(hx: HX, stub: Stub) -> None:
+    """A blank AGENTS.md adds no empty heading, one that is not UTF-8 or not readable does not
+    stop the session, and running from inside $HX_HOME does not load the same file twice."""
+    write(hx.project / "AGENTS.md", "  \n\n")
+    user_md = hx.hx_home / "AGENTS.md"
+    # Saved from a Latin-1 editor: "café" is not valid UTF-8.
+    user_md.write_bytes(b"NEVER-SEEN caf\xe9\n")
+    stub.script(say("Fine."))
+    hx.run("-p", "hi", check=True)
+    system = stub.requests[-1].system
+    assert "# User instructions" not in system
+    assert "# Project instructions" not in system
+    assert "NEVER-SEEN" not in system
+
+    # Root reads through any mode bits, so there is nothing to test there.
+    if os.geteuid() != 0:
+        user_md.write_text("NEVER-SEEN\n")
+        user_md.chmod(0o000)
+        try:
+            stub.script(say("Fine."))
+            hx.run("-p", "hi", check=True)
+            assert "NEVER-SEEN" not in stub.requests[-1].system
+        finally:
+            user_md.chmod(0o644)
+
+    user_md.write_text("SHARED-RULE: once only.\n")
+    stub.script(say("Fine."))
+    hx.run("-p", "hi", cwd=hx.hx_home, check=True)
+    system = stub.requests[-1].system
+    assert system.count("SHARED-RULE: once only.") == 1
+    assert "# User instructions" in system
+    assert "# Project instructions" not in system
+
+
 def test_skill_is_indexed_then_loaded(hx: HX, stub: Stub) -> None:
     """Only a skill's name and description are sent up front; calling Skill loads its body."""
     write(