Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript

feat: multi-agent registry, install identity checks, Codex/Claude cache path fixes (v0.6.2)

Sol Aitken7b240794f880
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 72b57019..4bef338a 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.6.1",
+ "version": "0.6.2",
"description": "Plugin-first second brain package for AI agents and humans.",
"author": {
"name": "Open Second Brain contributors"
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 059f06ab..a4ab53c5 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.6.1",
+ "version": "0.6.2",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"skills": "./skills",
"keywords": ["second-brain", "obsidian", "agents", "skills", "event-log", "mcp"]
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9f34301e..9c81f3de 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+## [0.6.2] - 2026-05-08
+
+### Added
+
+- install.md `## Verification β€” identity registry` block. Confirms
+ the chosen agent name appears in
+ `<vault>/AI Wiki/identity/agents.md` after `o2b init`. Multi-runtime
+ installs grow the list incrementally.
+- install.md prelude note: `o2b` CLI on PATH is a single shared
+ symlink across runtimes β€” first-installed wins, subsequent
+ `install-cli` refuses to overwrite. Manual repointing is allowed
+ but unnecessary.
+
+### Changed
+
+- install.md "Agent name" subsection (branches A–D): installer agent
+ **MUST** ask the user, **MUST** first check
+ `~/.config/open-second-brain/config.yaml`,
+ `<vault>/AI Wiki/identity/agents.md`, and `<vault>/Daily/*.md` for
+ a previously-set identity and surface it as a reuse-or-change
+ question. Defaults list only shown if no prior identity is found.
+- install.md "no version pin" guidance: replaced the ambiguous
+ "tracks `main`" framing with "**latest released version**" plus an
+ explicit `v0.6.1` vs `v0.6.0` example, and a direct statement that
+ manually appending `@v...` freezes the install at the literal tag
+ you typed.
+- install.md prelude: `o2b init` idempotency description updated to
+ describe the new multi-agent append behavior on
+ `AI Wiki/identity/agents.md`.
+
+### Fixed
+
+- Multi-agent registration in `AI Wiki/identity/agents.md`. Second and
+ later `o2b init --agent-name <name>` runs now append under
+ `## Registered agents` instead of being a silent no-op once the
+ placeholder is gone. Idempotent for already-registered names.
+- install.md Branch C steps 2–3: Codex CLI 0.129+ caches the
+ marketplace under `~/.codex/.tmp/marketplaces/<name>/`, not the
+ previously documented `~/.codex/plugins/cache/<marketplace>/<plugin>/<hash>/`.
+ Step 3 now uses a `find` pattern that works on either layout.
+- install.md Branch D step 3: Claude Code caches plugins under a
+ `<version>` segment (`~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/scripts/o2b`).
+ Same `find`-based fix as Branch C.
+
## [0.6.1] - 2026-05-08
### Added
@@ -514,7 +558,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Sandbox vault and plugin manifest fixtures for tests.
- GitHub release workflow for tag-based and manually dispatched releases.
-[unreleased]: https://github.com/itechmeat/open-second-brain/compare/v0.6.1...HEAD
+[unreleased]: https://github.com/itechmeat/open-second-brain/compare/v0.6.2...HEAD
+[0.6.2]: https://github.com/itechmeat/open-second-brain/compare/v0.6.1...v0.6.2
[0.6.1]: https://github.com/itechmeat/open-second-brain/compare/v0.6.0...v0.6.1
[0.6.0]: https://github.com/itechmeat/open-second-brain/compare/v0.5.5...v0.6.0
[0.5.5]: https://github.com/itechmeat/open-second-brain/compare/v0.5.4...v0.5.5
diff --git a/install.md b/install.md
index 4a1de099..c47a3569 100644
--- a/install.md
+++ b/install.md
@@ -4,9 +4,11 @@
This guide is written for an **AI agent**, not a human. It contains the exact commands and decision logic needed to install and configure the **open-second-brain** plugin autonomously. Follow exactly one of the branches below based on the target runtime: **A β€” Hermes**, **B β€” OpenClaw**, **C β€” Codex**, **D β€” Claude Code**, or **E β€” generic adapter** (any other runtime not covered by A–D). Complete every step in the chosen branch.
-**Always install the latest version.** Every install command in this guide pulls the current state of the `main` branch β€” there are no version pins. Do **NOT** add `@vX.Y.Z`, `@<tag>`, or any other version specifier to the install commands below, even if you happen to know the most recent release number; the project ships fixes between releases and the canonical install always tracks `main`. After install, the agent's effective version is reported by `o2b status` / `o2b doctor` and by the runtime's plugin listing β€” read it from there if you need it, do not hard-code it anywhere.
+**Always install the latest released version.** When the user installs the plugin, they expect to receive the newest published release β€” for example, if `v0.6.1` is the most recent tag and `v0.6.0` was the previous one, the install **must** end up at `v0.6.1`, not at `v0.6.0`. Each runtime CLI in branches A–D below already resolves "latest" by default when handed a bare `owner/repo` identifier (or the runtime-specific equivalent). Manually appending a version specifier β€” `@v0.6.0`, `@v1.2.3`, `@<some-tag>`, `--ref v...`, etc. β€” **bypasses** that resolution and freezes the install at the literal value you typed, including back to an older release if you happen to know an outdated tag number. Do **NOT** add any version specifier to the install commands below; rely on the CLI's default-latest behavior. After install, the effective version is reported by `o2b status` / `o2b doctor` and by the runtime's own plugin listing β€” read it from there if you need to know what got installed, do not pre-suppose it.
-**`o2b init` is idempotent.** Re-running it on an already-initialized vault only fills in missing scaffolding (`AI Wiki/identity/agents.md`, etc.) and never rewrites the user's notes or templates. Re-running with `--agent-name <name>` is the supported way to switch identities: it rewrites the entry in `AI Wiki/identity/agents.md` and updates the persisted `agent_name` in the plugin config (`~/.config/open-second-brain/config.yaml`). Use `--force` only when the user explicitly asks for a reset of the scaffolding files.
+**`o2b init` is idempotent.** Re-running it on an already-initialized vault only fills in missing scaffolding (`AI Wiki/identity/agents.md`, etc.) and never rewrites the user's notes or templates. Re-running with `--agent-name <name>` is the supported way to switch identities: it appends the new agent's entry to `AI Wiki/identity/agents.md` (without removing existing ones, so the registry grows correctly across multi-runtime installs) and updates the persisted `agent_name` in the plugin config (`~/.config/open-second-brain/config.yaml`). Use `--force` only when the user explicitly asks for a reset of the scaffolding files.
+
+**The `o2b` CLI on PATH is shared across runtimes.** The first runtime to run `o2b install-cli` wires `~/.local/bin/o2b` (and `vault-log`) at its own checkout; subsequent runtimes' `install-cli` invocations detect the existing symlink and **deliberately refuse to overwrite it** (printing `warning: already points to ..., not overwriting`). This is by design: the `o2b` script is byte-identical across all runtime checkouts (they all clone the same repo at the same version), so a single symlink serves every runtime correctly, and overwriting silently would risk pointing at a stale-and-uninstalled checkout when one runtime updates faster than another. If you have a deliberate reason to point `o2b` at a specific runtime's checkout (e.g. you want CLI behavior to track that runtime's plugin update cycle), repoint with `ln -sfn <path> ~/.local/bin/o2b` manually β€” the plugin won't second-guess you. But the default state, with `o2b` pointing at whichever runtime got there first, is correct and does not need fixing.
If at any point you are missing information β€” for example, the vault path is unknown, a required tool is not installed, or the runtime version is unclear β€” stop and ask the user for clarification. Offer concrete options where possible (e.g. suggest a default vault path, list supported Python versions, or propose an alternative runtime).
@@ -42,9 +44,33 @@ agreement. The plugin will refuse to write to the wrong place β€” but
catching a misclick at this step is much cheaper than after entries
have started accumulating.
-**Agent name.** Ask the user to choose the agent name that will appear
-as the `@agent-name` prefix in Daily event log entries. Offer these
-defaults plus a custom value:
+**Agent name.** You **MUST ask the user** to choose this. Do **not**
+silently pick a default value, do **not** assume the user wants
+whichever runtime-prefixed name looks reasonable. The value will
+appear as the `@agent-name` prefix in every single Daily event log
+entry written from this runtime; it has to be the user's deliberate
+choice, not the agent's guess.
+
+**Before asking, check for a previously-set identity.** If the user
+has installed Open Second Brain before β€” under another runtime, in a
+prior session, or after a reset β€” there are likely traces on disk:
+
+- `~/.config/open-second-brain/config.yaml` `agent_name` field β€” the
+ authoritative persisted identity (written by any past
+ `o2b init --agent-name` invocation, regardless of runtime).
+- `<vault>/AI Wiki/identity/agents.md` β€” usually has a line like
+ `- <name>: primary agent on this server`.
+- `<vault>/Daily/*.md` β€” recurring `@<name>` lines hint at past
+ identities the user has been writing under.
+
+If any of these surfaces a name, **show it to the user first** with a
+question like Β«This vault is already configured with `@<found-name>`.
+Should I reuse that name for the Hermes runtime, or do you want a
+different one for this runtime specifically?Β». Wait for an explicit
+answer β€” do not assume "reuse" or "change" on the user's behalf.
+
+Only when no prior identity is found, offer these defaults plus a
+custom value:
- `hermes-main`
- `hermes-vps-agent`
@@ -245,9 +271,33 @@ on the target machine in this order:
Confirm the chosen path with the user (show them the absolute path you
resolved) before passing it to `o2b init` and `openclaw config set`.
-**Agent name.** Ask the user to choose the agent name that will appear
-as the `@agent-name` prefix in Daily event log entries. Offer these
-defaults plus a custom value:
+**Agent name.** You **MUST ask the user** to choose this. Do **not**
+silently pick a default value, do **not** assume the user wants
+whichever runtime-prefixed name looks reasonable. The value will
+appear as the `@agent-name` prefix in every single Daily event log
+entry written from this runtime; it has to be the user's deliberate
+choice, not the agent's guess.
+
+**Before asking, check for a previously-set identity.** If the user
+has installed Open Second Brain before β€” under another runtime, in a
+prior session, or after a reset β€” there are likely traces on disk:
+
+- `~/.config/open-second-brain/config.yaml` `agent_name` field β€” the
+ authoritative persisted identity (written by any past
+ `o2b init --agent-name` invocation, regardless of runtime).
+- `<vault>/AI Wiki/identity/agents.md` β€” usually has a line like
+ `- <name>: primary agent on this server`.
+- `<vault>/Daily/*.md` β€” recurring `@<name>` lines hint at past
+ identities the user has been writing under.
+
+If any of these surfaces a name, **show it to the user first** with a
+question like Β«This vault is already configured with `@<found-name>`.
+Should I reuse that name for the OpenClaw runtime, or do you want a
+different one for this runtime specifically?Β». Wait for an explicit
+answer β€” do not assume "reuse" or "change" on the user's behalf.
+
+Only when no prior identity is found, offer these defaults plus a
+custom value:
- `openclaw-main`
- `openclaw-server`
@@ -287,7 +337,9 @@ by the optional `o2b mcp` server, not by the OpenClaw plugin runtime.
### 2. Install the plugin
-From Git (always installs the latest from `main`; do not append `@v...`):
+From Git (let the CLI resolve to the latest released version on its
+own; do not append `@v...` β€” see the prelude on why pinning a tag
+manually is the wrong move):
```bash
openclaw plugins install git:github.com/itechmeat/open-second-brain
@@ -436,9 +488,33 @@ on the target machine in this order:
Confirm the chosen path with the user (show them the absolute path you
resolved) before passing it to `o2b init` and the Codex MCP entry.
-**Agent name.** Ask the user to choose the agent name that will appear
-as the `@agent-name` prefix in Daily event log entries. Offer these
-defaults plus a custom value:
+**Agent name.** You **MUST ask the user** to choose this. Do **not**
+silently pick a default value, do **not** assume the user wants
+whichever runtime-prefixed name looks reasonable. The value will
+appear as the `@agent-name` prefix in every single Daily event log
+entry written from this runtime; it has to be the user's deliberate
+choice, not the agent's guess.
+
+**Before asking, check for a previously-set identity.** If the user
+has installed Open Second Brain before β€” under another runtime, in a
+prior session, or after a reset β€” there are likely traces on disk:
+
+- `~/.config/open-second-brain/config.yaml` `agent_name` field β€” the
+ authoritative persisted identity (written by any past
+ `o2b init --agent-name` invocation, regardless of runtime).
+- `<vault>/AI Wiki/identity/agents.md` β€” usually has a line like
+ `- <name>: primary agent on this server`.
+- `<vault>/Daily/*.md` β€” recurring `@<name>` lines hint at past
+ identities the user has been writing under.
+
+If any of these surfaces a name, **show it to the user first** with a
+question like Β«This vault is already configured with `@<found-name>`.
+Should I reuse that name for the Codex runtime, or do you want a
+different one for this runtime specifically?Β». Wait for an explicit
+answer β€” do not assume "reuse" or "change" on the user's behalf.
+
+Only when no prior identity is found, offer these defaults plus a
+custom value:
- `codex-main`
- `codex-vps-agent`
@@ -478,10 +554,16 @@ This repository ships a single-plugin marketplace manifest at
codex plugin marketplace add itechmeat/open-second-brain
```
-(Always pulls the latest commit on `main`; do not append `@v...`.) Codex
-clones the repo into `~/.codex/plugins/cache/open-second-brain/<plugin>/<hash>/`
-and registers a `[marketplaces.open-second-brain]` entry in
-`~/.codex/config.toml`.
+(The CLI resolves to the latest released version by default; do
+**not** append `@v...` β€” see the prelude.) Codex clones the repo
+somewhere under `~/.codex/`. The exact path varies by
+CLI version: older builds use `~/.codex/plugins/cache/<marketplace>/<plugin>/<hash>/`;
+Codex 0.129 stores it under `~/.codex/.tmp/marketplaces/<marketplace>/`.
+Step 3 below uses a `find` to locate the plugin scripts regardless of
+layout, so this difference is not user-visible. A
+`[marketplaces.open-second-brain]` entry is added to
+`~/.codex/config.toml`; the printed `Installed marketplace root: ...`
+line shows the absolute path of the install for that run.
Then enable the plugin so its bundled skills/agents/commands become
available β€” there is no `codex plugin enable` subcommand on current
@@ -505,13 +587,15 @@ enablement.
The `o2b` and `vault-log` scripts ship inside the plugin checkout; this
step symlinks them into `~/.local/bin` so they are usable on PATH.
+The cached path differs across Codex versions (see step 2), so locate
+the script by searching under `~/.codex/`:
+
```bash
-~/.codex/plugins/cache/open-second-brain/open-second-brain/*/scripts/o2b install-cli
+"$(find ~/.codex -path '*open-second-brain*/scripts/o2b' -type f 2>/dev/null | head -1)" install-cli
```
-(The glob handles the version hash that Codex assigns to the cached
-clone. If you installed the marketplace from a local path, run
-`<that-path>/scripts/o2b install-cli` instead.)
+If you installed the marketplace from a local path, run
+`<that-path>/scripts/o2b install-cli` directly instead.
### 4. Initialize the vault
@@ -630,9 +714,36 @@ on the target machine in this order:
Confirm the chosen path with the user (show them the absolute path
you resolved) before passing it to `o2b init`.
-**Agent name.** Ask the user to choose the agent name that will appear
-as the `@agent-name` prefix in Daily event log entries. Offer these
-defaults plus a custom value:
+**Agent name.** You **MUST ask the user** to choose this. Do **not**
+silently pick a default value, do **not** assume the user wants
+whichever runtime-prefixed name looks reasonable. The value will
+appear as the `@agent-name` prefix in every single Daily event log
+entry written from this runtime; it has to be the user's deliberate
+choice, not the agent's guess.
+
+**Before asking, check for a previously-set identity.** If the user
+has installed Open Second Brain before β€” under another runtime, in a
+prior session, or after a reset β€” there are likely traces on disk:
+
+- `~/.config/open-second-brain/config.yaml` `agent_name` field β€” the
+ authoritative persisted identity (written by any past
+ `o2b init --agent-name` invocation, regardless of runtime). On
+ Claude Code specifically this field is what the bundled
+ `.mcp.json` resolves at runtime, so a stale value here will
+ silently become Claude's identity unless step 4 overwrites it.
+- `<vault>/AI Wiki/identity/agents.md` β€” usually has a line like
+ `- <name>: primary agent on this server`.
+- `<vault>/Daily/*.md` β€” recurring `@<name>` lines hint at past
+ identities the user has been writing under.
+
+If any of these surfaces a name, **show it to the user first** with a
+question like Β«This vault is already configured with `@<found-name>`.
+Should I reuse that name for the Claude Code runtime, or do you want
+a different one for this runtime specifically?Β». Wait for an explicit
+answer β€” do not assume "reuse" or "change" on the user's behalf.
+
+Only when no prior identity is found, offer these defaults plus a
+custom value:
- `claude-main`
- `claude-vps-agent`
@@ -671,11 +782,14 @@ claude plugin marketplace add itechmeat/open-second-brain
claude plugin install open-second-brain@open-second-brain
```
-(The marketplace step always pulls the latest commit on `main`; do not
-append `@v...`.) After install, `claude plugin list` shows the plugin
-under user scope with `Status: βœ” enabled`. Claude clones the repo into
-`~/.claude/plugins/cache/open-second-brain/<plugin-name>/` and tracks
-the source via the `claude-plugins` config block.
+(The marketplace step resolves to the latest released version on its
+own; do **not** append `@v...` β€” see the prelude.) After install,
+`claude plugin list` shows the plugin under user scope with
+`Status: βœ” enabled`. Claude clones the repo
+under `~/.claude/plugins/cache/<marketplace>/<plugin-name>/<version>/`
+(the trailing `<version>` segment matches the installed plugin
+manifest's `version`, e.g. `0.6.1`) and tracks the source via the
+`claude-plugins` config block.
The plugin auto-registers its MCP server through the bundled `.mcp.json`
file at the repo root β€” **no `claude mcp add` step is needed**. After
@@ -687,8 +801,11 @@ step 4 below (vault init), `claude mcp list` will show
The `o2b` and `vault-log` scripts ship inside the plugin checkout; this
step symlinks them into `~/.local/bin` so they are usable on PATH.
+The cached path includes the plugin version segment, so locate the
+script by searching under the cache:
+
```bash
-~/.claude/plugins/cache/open-second-brain/open-second-brain/scripts/o2b install-cli
+"$(find ~/.claude/plugins/cache -path '*open-second-brain*/scripts/o2b' -type f 2>/dev/null | head -1)" install-cli
```
### 4. Initialize the vault
@@ -804,7 +921,9 @@ runtimes will find one they understand:
- A vanilla Git checkout (every runtime can clone a repo)
Pick whichever your runtime documents. Do **not** add a version pin
-(`@v...`) β€” the canonical install always tracks the `main` branch.
+(`@v...`) β€” let the runtime CLI resolve to the latest released
+version on its own (see the prelude on why manual pinning freezes you
+to a stale release).
### 3. Publish CLI commands to PATH
@@ -904,6 +1023,39 @@ created in step 3. Vault Markdown files are never deleted.
---
+## Verification β€” identity registry
+
+The plugin's MCP-side identity (what gets stamped in Daily as
+`@<name>`) is one of two artifacts; the **vault's identity registry**
+(the human-/agent-readable list of who is allowed to write) is the
+other. Both must agree, and both must be checked. Past install
+sessions have skipped this and silently ended up with the runtime
+writing under one identity that the registry never recorded β€” the MCP
+server happily logged events without complaint, and the gap only
+surfaced later when someone audited the vault.
+
+After step 4's `o2b init --agent-name <name>` finishes, open
+`<vault>/AI Wiki/identity/agents.md` and confirm it contains a line
+like:
+
+```
+- <chosen-agent-name>: primary agent on this server
+```
+
+Multi-runtime installs build this list incrementally: each
+`o2b init --agent-name X` appends another entry under
+`## Registered agents` if `X` isn't already there. So on a vault
+that already has Hermes registered, a fresh Codex install should
+result in **two** lines β€” one for `hermes-vps-agent`, one for
+`codex-vps-agent` β€” not just one.
+
+If your runtime's identity is missing from the registry after
+`o2b init` ran without errors, treat the install as **incomplete**:
+report it to the user, then either re-run `o2b init --agent-name <name>`
+(it's idempotent and will append the missing entry), or add the line
+by hand if you have a reason not to re-run init. Don't proceed to
+the daily-identity check below without this in place.
+
## Verification β€” daily identity
`o2b doctor` and `vault_health` confirm that the vault is structurally
diff --git a/openclaw.plugin.json b/openclaw.plugin.json
index 78d51434..4ad199f3 100644
--- a/openclaw.plugin.json
+++ b/openclaw.plugin.json
@@ -2,7 +2,7 @@
"id": "open-second-brain",
"name": "Open Second Brain",
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults.",
- "version": "0.6.1",
+ "version": "0.6.2",
"activation": { "onStartup": true },
"skills": ["./skills"],
"contracts": {
diff --git a/package.json b/package.json
index d73b5d3f..12b06986 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.6.1",
+ "version": "0.6.2",
"type": "module",
"private": false,
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw.",
diff --git a/plugin.yaml b/plugin.yaml
index a9aef722..3d9b41a6 100644
--- a/plugin.yaml
+++ b/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "0.6.1"
+version: "0.6.2"
description: "Hermes plugin entrypoint for OpenSecondBrain vault health checks and the optional MCP tool server."
author: "OpenSecondBrain contributors"
kind: standalone
diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yaml
index 2aaf0931..f2e593dc 100644
--- a/plugins/hermes/plugin.yaml
+++ b/plugins/hermes/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "0.6.1"
+version: "0.6.2"
description: "Hermes adapter for OpenSecondBrain vault health checks and optional MCP tool server."
author: "OpenSecondBrain contributors"
kind: standalone
diff --git a/pyproject.toml b/pyproject.toml
index dc996d48..47124c71 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "open-second-brain"
-version = "0.6.1"
+version = "0.6.2"
description = "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw."
readme = "README.md"
requires-python = ">=3.11"
diff --git a/src/open_second_brain/init.py b/src/open_second_brain/init.py
index a3b6050b..b9614c12 100644
--- a/src/open_second_brain/init.py
+++ b/src/open_second_brain/init.py
@@ -111,20 +111,65 @@ def bootstrap_vault(
return created
+_AGENTS_REGISTERED_HEADING = "## Registered agents"
+
+
def _upgrade_agents_file(path: Path, agent_name: str) -> bool:
- """Replace the template placeholder with the chosen agent entry.
+ """Register ``agent_name`` in ``AI Wiki/identity/agents.md``.
+
+ Three cases this handles, in order:
+
+ * The file still contains the bootstrap placeholder
+ (``- (add your agents here, …)``): replace the placeholder with
+ ``- <agent_name>: primary agent on this server``.
+
+ * The file already contains an entry for ``agent_name``: no-op.
+ This makes ``o2b init --agent-name X`` idempotent on a vault
+ that already has X registered.
- Returns True if the file was rewritten.
+ * Neither of the above β€” the file has already been initialised
+ with **another** agent's entry, and this is a multi-runtime
+ / multi-agent setup. Append the new entry under
+ ``## Registered agents``, before the next ``##`` section
+ heading. Previously this case was a silent no-op, so users
+ running ``o2b init --agent-name codex-vps-agent`` after a
+ prior ``--agent-name claude-vps-agent`` saw their identity
+ recorded in the plugin config but never written into the
+ vault registry. Fixed.
+
+ Returns True when the file was actually rewritten.
"""
try:
text = path.read_text(encoding="utf-8")
except OSError:
return False
+
entry = f"- {agent_name}: primary agent on this server"
if entry in text:
return False
+
if AGENTS_PLACEHOLDER in text:
new_text = text.replace(AGENTS_PLACEHOLDER, entry)
path.write_text(new_text, encoding="utf-8")
return True
- return False
+
+ # Multi-agent path: append under "## Registered agents". Locate the
+ # heading and the next "##" that follows it (or end-of-file), and
+ # insert the new bullet right before that boundary so subsequent
+ # sections (e.g. "## Scopes") stay where the user expects them.
+ heading_idx = text.find(_AGENTS_REGISTERED_HEADING)
+ if heading_idx == -1:
+ return False
+ after_heading = heading_idx + len(_AGENTS_REGISTERED_HEADING)
+ rest = text[after_heading:]
+ next_section_relative = rest.find("\n## ")
+ if next_section_relative == -1:
+ head = text[:after_heading] + rest.rstrip()
+ new_text = head + f"\n{entry}\n"
+ else:
+ boundary = after_heading + next_section_relative
+ before = text[:boundary].rstrip()
+ after = text[boundary:]
+ new_text = before + f"\n{entry}\n" + after
+ path.write_text(new_text, encoding="utf-8")
+ return True
diff --git a/tests/test_init.py b/tests/test_init.py
index 6ae58c2e..2267e21e 100644
--- a/tests/test_init.py
+++ b/tests/test_init.py
@@ -46,6 +46,52 @@ class InitTests(unittest.TestCase):
)
self.assertIn(AGENTS_PLACEHOLDER, agents_md)
+ def test_bootstrap_vault_registers_second_agent_when_first_already_present(self):
+ # Multi-runtime install: a previous `o2b init --agent-name X`
+ # already replaced the placeholder, so this run's agent name
+ # has to be APPENDED to the existing list, not skipped. Before
+ # this fix the second invocation was a silent no-op: the
+ # plugin config got the new identity but the vault registry
+ # never learned about it. Both Codex and Claude install
+ # sessions hit this in practice.
+ with tempfile.TemporaryDirectory() as tmp:
+ vault = Path(tmp)
+ bootstrap_vault(vault, name="Test", agent_name="hermes-vps-agent")
+ agents_path = vault / "AI Wiki" / "identity" / "agents.md"
+ first_text = agents_path.read_text(encoding="utf-8")
+ self.assertIn("- hermes-vps-agent: primary agent on this server", first_text)
+ self.assertNotIn(AGENTS_PLACEHOLDER, first_text)
+
+ created = bootstrap_vault(vault, name="Test", agent_name="codex-vps-agent")
+ self.assertIn(Path("AI Wiki") / "identity" / "agents.md", created)
+ text = agents_path.read_text(encoding="utf-8")
+ # Both agents are present, in registration order.
+ self.assertIn("- hermes-vps-agent: primary agent on this server", text)
+ self.assertIn("- codex-vps-agent: primary agent on this server", text)
+ self.assertLess(
+ text.index("hermes-vps-agent"),
+ text.index("codex-vps-agent"),
+ "first-registered agent must come first",
+ )
+ # The "## Scopes" section that follows must still be intact.
+ self.assertIn("## Scopes", text)
+ self.assertLess(
+ text.index("codex-vps-agent"),
+ text.index("## Scopes"),
+ "new agent must be inserted under '## Registered agents', "
+ "not after the next section header",
+ )
+
+ # A third register of an already-present name is a no-op.
+ created_again = bootstrap_vault(vault, name="Test", agent_name="codex-vps-agent")
+ self.assertNotIn(Path("AI Wiki") / "identity" / "agents.md", created_again)
+ text_after = agents_path.read_text(encoding="utf-8")
+ self.assertEqual(
+ text_after.count("- codex-vps-agent: primary agent on this server"),
+ 1,
+ "re-registering an existing agent must not duplicate the entry",
+ )
+
def test_bootstrap_vault_upgrades_existing_placeholder_in_place(self):
with tempfile.TemporaryDirectory() as tmp:
vault = Path(tmp)