Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

fix(cli): a supervised serve silently swaps the gateway's channels and workdir policy

Open
  • Is something wrong?
#439 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
58/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Active
Tech stack
python
Domain
backend, cli

Research direction

Start at _gateway_argv and trace the supervised child through raven/rpc/bootstrap.py and build_engine; compare the policies in raven/core/engine_stack.py:106-115 and raven/cli/gateway_commands.py:302-308. Read raven/agent/workdir.py and its validate_override path to understand startup validation. Done means the selected mode is reported, an invalid launch directory fails clearly at startup, and the relevant behavior is covered by tests.

Written by the indexing model from the issue text.

Description

Summary

raven web supervises a child that is either raven gateway or raven serve,
chosen per launch by whether a gateway already holds the lock. The two are not
interchangeable: they differ in whether IM channels run at all, and in how a
session's working directory is chosen. The substitution is silent, so a user who
asked for one surface can be given the other and is told nothing.

Two unrelated-looking failures on one machine turned out to be the same
substitution:

  • channels stop existing. raven serve builds no ChannelManager, so an
    enabled WeChat entrance simply is not there. _gateway_argv's own docstring
    says as much.
  • every acp sub-agent refuses to start. serve resolves a session's working
    directory as the launch directory. Started from a home directory -- the
    ordinary place a terminal opens -- that directory contains agent home, and the
    child refuses the cwd it is handed.

The second one, measured

On a machine where raven web had been started from /Users/admin, every
dispatch to an acp sub-agent failed the same way:

[failed] Error: request failed: [-32602] cwd is not usable: working directory
must not contain the agent home directory
(/Users/admin/.raven/subagent_sessions/raven-code/acp)

Three different agents, a fresh conversation and a resumed one alike. The ACP
frame journal records what was actually sent:

"cwd": "/Users/admin"

The refusal is correct and should stay. validate_override explains why in
raven/agent/workdir.py: the per-turn checkpoint runs git add -A over the
working directory, and the .raven/ default exclude cannot help when the
working directory is .raven's parent, so a session rooted there would commit
every credential into a shadow repository.

Nothing in the configuration asked for that directory. On the same machine:
config.workspace_path /Users/admin/.raven/workspace -- passes validation
agents.defaults.workspace ~/.raven/workspace -- passes validation
session workdir override none recorded

The path came from the policy, not from configuration.

Why the two surfaces differ, and why that is not itself the bug

Both policies are right for the surface they were written for, and
build_local_sessions says so:

Sessions group by launch directory here, the way Claude Code groups by
project: one terminal session belongs to the checkout it was started in. The
gateway passes no slug -- one daemon serves every project, so its grouping is
the channel instead.

  • raven/core/engine_stack.py:106-115 -- launch_dir = Path.cwd() with
    WorkdirPolicy.LAUNCH_DIR. Reached by serve through
    raven/rpc/bootstrap.py -> build_engine.
  • raven/cli/gateway_commands.py:302-308 -- WorkdirPolicy.PER_CHANNEL with a
    session_root, defaulting to the per-channel root.

A launch directory is a sensible unit of work for a command someone runs inside
a checkout. It is not one for a resident daemon started from wherever the
terminal happened to be, which is what raven web produces when it falls back.

What to fix

1. Say when the substitution happens. _gateway_argv picks serve when a
gateway already holds the lock, and that choice is invisible afterwards: the
process name is the only trace, and nothing on the page says which surface is
answering. One line at startup naming the mode and what it costs -- no channel
adapters, launch-directory sessions -- would have made both failures
self-diagnosing.

2. Validate the launch directory at startup, not at dispatch. This failure
is fully determined the moment the process starts: the launch directory and the
agent home are both known, and validate_override is the function that decides.
Deferring it means a person sees nothing wrong until a sub-agent is dispatched,
and then sees it only inside that sub-agent's own panel -- the main conversation
shows "run failed" with no cause. Refusing to start, naming the directory and
suggesting another, turns a scattered runtime failure into one clear message at
the one moment someone is looking at a terminal.

3. Consider whether serve should use a launch directory at all. It is a
resident process supervised by raven web, not a command run inside a project.
The per-channel root the gateway uses fits it better, and would make the two
paths agree on the thing users notice.

(1) and (2) are worth doing regardless of (3), and (2) alone would have made
this report unnecessary.

Reproducing

cd ~ && raven web

Then dispatch to any acp sub-agent. If the supervisor's child is raven serve
(ps will show which), the dispatch fails with the -32602 above. Starting
from a directory that does not contain ~/.raven avoids it, which is also the
workaround.

Dominant language
Python
Stars
4.1k
Forks
94
Avg merge
10h 2m
Merged PRs (30d)
376

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from EverMind-AI/Raven

All issues in EverMind-AI/Raven

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.