Skip to content

Commit 3c83c15

Browse files
fix(acp): conditional session unbind + multi-profile store guidance
Failed session/load used key-only remove, so process A reading X then failing load could delete process B's newer Y for the same channel. Clear bindings with remove_if_equals under the existing lock, and cover the interleaving race in regression tests. Durable store identity is command + args + channel, not HERMES_HOME. Require unique -p <profile> acp args for multi-profile managed agents and drop the HERMES_HOME-only alternative from dogfood docs until the store is namespaced. Also note long-lived ACP OAuth stay-alive ops in the Rocky dogfood guide. Reported by @rungmc357 on PR #2633. Co-authored-by: Georgio Constantinou <[email protected]> Co-authored-by: joelbrilliant <[email protected]> Signed-off-by: joelbrilliant <[email protected]>
1 parent 3025359 commit 3c83c15

4 files changed

Lines changed: 138 additions & 11 deletions

File tree

‎crates/buzz-acp/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,9 +102,11 @@ tools as the Hermes CLI.
102102

103103
export BUZZ_ACP_AGENT_COMMAND="hermes"
104104
export BUZZ_ACP_AGENT_ARGS="acp" # empty also normalises to acp
105-
export HERMES_HOME="$HOME/.hermes" # or a named profile home
105+
export HERMES_HOME="$HOME/.hermes" # process home; does not namespace the durable store
106106
export BUZZ_ACP_NO_MEMORY="true" # must be the string true (not 1)
107107
# Keep a single worker per profile home (Desktop: parallelism=1).
108+
# For a second Hermes profile, use unique args (e.g. BUZZ_ACP_AGENT_ARGS="-p chad acp")
109+
# so session bindings do not collide. HERMES_HOME alone is not enough.
108110

109111
buzz-acp
110112
```

‎crates/buzz-acp/src/pool.rs‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -869,10 +869,16 @@ async fn try_load_persisted_session(
869869
session_id = %stored,
870870
channel_id = %channel_id,
871871
error = %e,
872-
"session/load failed — clearing binding and creating a new session"
872+
"session/load failed — clearing stale binding (if unchanged) and creating a new session"
873+
);
874+
// Only drop the binding we failed to load. A concurrent process may
875+
// already have written a newer session for this channel.
876+
let _ = ctx.session_store.remove_if_equals(
877+
&ctx.agent_command,
878+
&ctx.agent_args,
879+
channel_id,
880+
&stored,
873881
);
874-
ctx.session_store
875-
.remove(&ctx.agent_command, &ctx.agent_args, channel_id);
876882
None
877883
}
878884
}

‎crates/buzz-acp/src/session_store.rs‎

Lines changed: 96 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -130,7 +130,7 @@ impl SessionStore {
130130
}
131131
}
132132

133-
/// Remove a binding (after invalidation / failed load).
133+
/// Remove a binding (after invalidation / explicit rotate).
134134
pub fn remove(&self, agent_command: &str, agent_args: &[String], channel_id: &Uuid) {
135135
let key = binding_key(agent_command, agent_args, channel_id);
136136
let Some(_lock) = self.acquire_lock(true) else {
@@ -148,6 +148,53 @@ impl SessionStore {
148148
}
149149
}
150150

151+
/// Remove a binding only if it still points at `expected_session_id`.
152+
///
153+
/// Used after a failed `session/load`: another process may have already
154+
/// written a newer session for the same channel, and a key-only remove
155+
/// would delete that fresher binding.
156+
///
157+
/// Returns `true` when a matching binding was removed.
158+
pub fn remove_if_equals(
159+
&self,
160+
agent_command: &str,
161+
agent_args: &[String],
162+
channel_id: &Uuid,
163+
expected_session_id: &str,
164+
) -> bool {
165+
let key = binding_key(agent_command, agent_args, channel_id);
166+
let Some(_lock) = self.acquire_lock(true) else {
167+
return false;
168+
};
169+
match load_store(&self.path) {
170+
Ok(mut data) => {
171+
let matches = data
172+
.sessions
173+
.get(&key)
174+
.is_some_and(|current| current == expected_session_id);
175+
if !matches {
176+
return false;
177+
}
178+
data.sessions.remove(&key);
179+
if let Err(e) = save_store(&self.path, &data) {
180+
self.warn_io(
181+
"failed to persist conditional ACP session binding removal",
182+
&e,
183+
);
184+
return false;
185+
}
186+
true
187+
}
188+
Err(e) => {
189+
self.warn_io(
190+
"failed to read ACP session bindings before conditional removal",
191+
&e,
192+
);
193+
false
194+
}
195+
}
196+
}
197+
151198
fn acquire_lock(&self, exclusive: bool) -> Option<StoreLock> {
152199
if let Some(parent) = self.lock_path.parent() {
153200
if let Err(e) = fs::create_dir_all(parent) {
@@ -362,4 +409,52 @@ mod tests {
362409
Some("recovered")
363410
);
364411
}
412+
413+
#[test]
414+
fn remove_if_equals_does_not_delete_newer_binding() {
415+
let dir = tempdir().unwrap();
416+
let path = dir.path().join("sessions.json");
417+
let args = ["acp".into()];
418+
let channel = Uuid::new_v4();
419+
420+
// Process A reads X.
421+
let process_a = SessionStore::open(path.clone());
422+
process_a.put("hermes", &args, &channel, "session-x");
423+
let read_x = process_a
424+
.get("hermes", &args, &channel)
425+
.expect("process A read X");
426+
assert_eq!(read_x, "session-x");
427+
428+
// Process B writes Y for the same channel.
429+
let process_b = SessionStore::open(path.clone());
430+
process_b.put("hermes", &args, &channel, "session-y");
431+
assert_eq!(
432+
process_b.get("hermes", &args, &channel).as_deref(),
433+
Some("session-y")
434+
);
435+
436+
// Process A's failed load of X must not delete Y.
437+
let removed = process_a.remove_if_equals("hermes", &args, &channel, &read_x);
438+
assert!(!removed);
439+
440+
let final_store = SessionStore::open(path);
441+
assert_eq!(
442+
final_store.get("hermes", &args, &channel).as_deref(),
443+
Some("session-y")
444+
);
445+
}
446+
447+
#[test]
448+
fn remove_if_equals_clears_matching_stale_binding() {
449+
let dir = tempdir().unwrap();
450+
let path = dir.path().join("sessions.json");
451+
let args = ["acp".into()];
452+
let channel = Uuid::new_v4();
453+
let store = SessionStore::open(path.clone());
454+
store.put("hermes", &args, &channel, "session-x");
455+
assert!(store.remove_if_equals("hermes", &args, &channel, "session-x"));
456+
assert!(store.get("hermes", &args, &channel).is_none());
457+
// No-op when already gone.
458+
assert!(!store.remove_if_equals("hermes", &args, &channel, "session-x"));
459+
}
365460
}

‎docs/hermes-agent-rocky.md‎

Lines changed: 30 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -88,17 +88,22 @@ buzz-acp
8888

8989
## Multi-profile later
9090

91-
When you want another Hermes profile on Buzz, add a **second** managed agent with either:
91+
When you want another Hermes profile on Buzz, add a **second** managed agent
92+
with **unique ACP args** so durable session bindings do not collide:
9293

9394
```text
95+
command: hermes
9496
arguments: -p chad acp
97+
HERMES_HOME=/Users/you/.hermes/profiles/chad # optional, for the process env
98+
parallelism: 1
9599
```
96100

97-
or
98-
99-
```text
100-
HERMES_HOME=/Users/you/.hermes/profiles/chad
101-
```
101+
Do **not** run two managed agents with identical command/args (e.g. both
102+
`hermes` + empty/`acp` args) and only different `HERMES_HOME` values. The durable
103+
session store is keyed by command + args + channel, not by environment or
104+
managed-agent identity, so those two agents would overwrite each other's channel
105+
bindings. Until the store is namespaced by agent identity, unique `-p <profile>
106+
acp` args are required for multi-profile.
102107

103108
Keep `parallelism=1` per profile.
104109

@@ -107,3 +112,22 @@ Keep `parallelism=1` per profile.
107112
- **This PR:** local Desktop/managed Hermes runtime discovery, arg normalisation, durable `session/load`, onboarding picker, owner Rocky dogfood guide. Intentionally does **not** include external-agent directory / kind `10100` / relay-observer presentation work.
108113
- **#2468 (nytemode):** broader external-agent hosting + VPS observer path. Currently conflicting with `main`. Ready-to-steal pieces already folded here: command-specific `hermes acp --check` readiness as AdapterMissing, exact `python`/`python3` process recognition.
109114
- **Deeper native Hermes integration** (first-class Nous product surface inside Buzz, shared memory protocols, etc.) is still best done by the Nous Research team upstream.
115+
116+
## Staying alive (OAuth / long-lived ACP)
117+
118+
Rocky over Buzz is a **long-lived** `hermes acp` process. Telegram/Discord/gateway
119+
stay warm and refresh tokens; a parked ACP worker can hold a stale xAI access
120+
token after hours of idle.
121+
122+
**One-time ops**
123+
1. Rocky managed agent: **Start on app launch** on
124+
2. **Parallelism = 1** (instance, not only definition)
125+
3. After this Hermes fix is installed: restart Rocky once so new ACP sessions
126+
get `credential_pool` and can self-heal on `403 bad-credentials`
127+
128+
**You should not need reauth** when Telegram still works. Prefer restart Rocky
129+
in Buzz Agents if a single turn fails with OAuth 403 after long idle.
130+
131+
**Fixed upstream** (Hermes): ACP now wires `credential_pool` like the gateway,
132+
and 403 auth refreshes the same path as 401 for xAI OAuth.
133+

0 commit comments

Comments
 (0)