If You Do Not Restart APX, You Are Testing Old Code

One of the most practical APX rules has nothing to do with prompts, models, or MCPs.

It is this: if you change APX code and do not restart the daemon before testing, you are usually testing the old runtime.

That sounds obvious. In practice, it causes a lot of false debugging.

APC and APX split responsibilities on purpose.

APC is the portable context layer. It keeps project truth in repository files such as AGENTS.md, .apc/project.json, agent definitions, skills, and other committed context.

APX is the daily-use runtime and tooling layer. It is the daemon, CLI, web admin, channel handling, sessions, message logs, and other machine-local state under ~/.apx/.

Because APX is a live runtime, code changes do not matter until the running daemon actually reloads them.

Why this matters

The APX project guide says it bluntly: skip restart and your test is a lie.

That is not style advice. The daemon keeps the JavaScript it booted with. Adapters, routes, prompt builders, and tool handlers all stay in memory until the process restarts.

So this sequence is broken:

1. edit APX code
2. run a manual check immediately
3. conclude the fix did not work
4. debug the wrong problem

The problem is often not the code. The problem is that the daemon is still serving the previous version.

What the docs and repo already say

The APX README describes APX as a daemon plus CLI plus web admin. The daemon starts on first use, and the browser UI talks to that same local process.

The APX repo guide goes further and turns that into a development rule:

• know which checkout the daemon is running from
• run apx restart after every code change and before manual testing
• verify the restart actually happened
• only then exercise the path you changed

That same guide warns about another easy mistake: the daemon runs from the main checkout, not from a random worktree. A fix committed somewhere the daemon never reads is not live, even if your branch looks correct.

Where APC fits

This restart rule also shows the APC/APX boundary clearly.

APC does not define a daemon. APC does not define process lifecycle. APC does not define how a local runtime reloads route handlers or tool wiring.

APC only defines portable project context.

APX owns the operational layer that makes that context usable today. The APC docs describe APX exactly that way: the reference runtime that keeps sessions, memory, and messages outside .apc/ under ~/.apx/, while the repository keeps the durable project contract.

So if APC answers, "What does this project mean?" APX answers, "What code is this machine actually running right now?"

Restart belongs on the APX side because live execution belongs on the APX side.

Practical loop

A safe APX edit loop is small:

apx restart
curl -s 127.0.0.1:7430/api/health
apx daemon logs --tail 30

Then test the exact path you changed.

• changed a route: hit the route
• changed agent or tool behavior: run apx exec or apx run
• changed a web flow: restart first, then reload the browser and test end to end

That loop is boring, but it removes a whole class of fake failures.

Bigger lesson

A lot of agent-tool confusion comes from mixing portable context with live runtime behavior.

APC can be perfectly correct while APX is still running stale code.

Your repo may already contain the right project contract, agent files, and rules. But until the APX daemon reloads, the local runtime still reflects yesterday's process image.

That is why this rule matters so much.

Portable context tells every compatible tool what the project is.

APX restart makes sure the local runtime is actually using the code you just changed.

If you want one sentence to keep:

APC can stay stable in git, while APX must be restarted to make a code fix real.