Proposing a PR to the Official Hermes Agent Repo

When a change concerns Hermes Agent’s code itself (not personal config or docs), it must be delivered to the official NousResearch/hermes-agent repository. Concrete example: fixing the dashboard /profile view so it shows multiplexed profiles as served by the gateway instead of “not started”.

An incident report, issue comment, and upstream documentation proposal are separate deliverables. Documenting one here does not post it or open an upstream PR; the upstream action remains explicitly manual.

Why a fork?

The author (François) is not a maintainer of NousResearch/hermes-agent. On GitHub, an outside contributor pushes changes to their own copy (fork) of the repository, then opens a pull request against the original.

• The official repo is read-only (no push access).
• The fork lives under the personal account fducat18.
• The PR is reviewed and merged by Nous Research maintainers.

Alternative to consider: if maintainers ever grant direct collaborator access, a branch could be pushed straight to NousResearch/hermes-agent. Today the canonical path is fork → branch → PR.

Prerequisites

1. A GitHub fine-grained token with Contents: Read and write rights on the fork (fducat18/hermes-agent). Verify with:

   curl -s -H "Authorization: Bearer ${GITHUB_TOKEN}" \
     https://api.github.com/repos/fducat18/hermes-agent

   (expect HTTP 200 + permissions.push: true).
2. Git identity configured (name “François Ducatillon”, personal email):

   git config --global user.name "François Ducatillon"
   git config --global user.email "francois.ducatillon@gmail.com"

3. ~/.hermes/hermes-agent is a git clone of the official repo. It serves as the working base (see below — keep local patches out of the PR).

Beware of local patches (important pitfall)

~/.hermes/hermes-agent contains deliberate local patches that must not be shipped in a PR:

• hermes_cli/web_server.py — security patch “trusted loopback hosts” (Host-header validation for the dashboard through the tunnel).
• Possibly models.py / catalog patches.

Before creating a PR, isolate only the intended change. Never include these local patches. Recommended: start a clean working branch from official main, then apply only the future PR’s diff to it.

Steps

1. Refresh the official base

cd ~/.hermes/hermes-agent
git fetch origin
git checkout -b fix/profile-multiplex-status origin/main

2. Apply (or write) the change

Copy the targeted changed file, or edit directly on the fresh branch. For the /profile dashboard, the fix concerns detection of multiplexed profile status (see Gateway Profiles).

Do not simultaneously commit the local patches (web_server.py security). Keep them on another branch or re-apply them afterward.

3. Test

Follow AGENTS.md in the repo (behavior contracts, role alternation, targeted tests):

python -m pytest tests/gateway -o 'addopts=' -q

For a dashboard change, add or adapt a test that demonstrates the expected behavior (a profile served by a multiplexed gateway is not “not started”).

4. Commit as François

git add <targeted files>
git commit -m "fix: ..."

Verify the author:

git log -1 --format='%an <%ae>'
# → François Ducatillon <francois.ducatillon@gmail.com>

5. Push to the fork and open the PR

# Configure the fork remote once
git remote add fork https://x-access-token:${GITHUB_TOKEN}@github.com/fducat18/hermes-agent.git

git push -u fork fix/profile-multiplex-status

Then open the PR via the GitHub UI, or:

gh pr create --repo NousResearch/hermes-agent \
  --head fducat18:fix/profile-multiplex-status \
  --base main \
  --title "fix(dashboard): correct multiplexed profile gateway status" \
  --body "see Gateway Profiles doc (operations/gateway-profiles.md)"

6. Follow the review

• Respond to comments.
• Push review changes to the same branch (git push fork <branch>).
• The maintainers decide the final merge.

Issue comments and documentation-only upstream follow-up

Not every finding should become an upstream PR immediately. For an estate incident that is related to an existing report but has a different mechanism, document the candidate comment first and post it only after manual review.

The required sequence follows the official CONTRIBUTING.md guidance:

1. Search open and closed issues and PRs for the error signature and mechanism.
2. Search the current source to check whether the behavior is already fixed.
3. Prefer a comment on the closest existing issue when the overlap is real; open a new issue only when the scope is materially distinct and no better home exists.
4. Sanitize hostnames, paths, IDs, tokens, prompts, and personal data.
5. Include the environment, exact symptom, minimal reproduction or observation, expected behavior, actual behavior, and the evidence that separates the report from nearby issues.
6. Ask maintainers whether a dedicated issue or PR is preferred; do not prescribe a fix from one deployment without confirming the code path.

For the September 2026 state.db recurrence, this workflow is documented in the Proposed Upstream state.db Report. It references the closed issue #78182 as the closest existing report, records the proposed scope, and explicitly states that no comment or issue was posted by the estate documentation work.

Keep estate-specific watchdog scripts and cron schedules in the estate repository. An upstream documentation PR may document the generic sessions recover flags and recovery flow, but it must not copy personal paths, local service names, or secrets.

End-to-end verification

Before claiming “PR opened”, get the PR URL (gh pr create output or https://github.com/NousResearch/hermes-agent/pull/<n>) and verify it: the diff contains no local patches, the author is François, and the CI is green or under review.

Agent Host rules reminder

• Never push directly to main of the fork either: always branch → PR.
• Do not mix an official PR with the in-progress modifications of the local ~/.hermes/hermes-agent (stash/discard the local patches).
• Document any estate-side decision in docs.ducatillon.net and reference the PR in the corresponding documentation.