antfarm-colony-ops
Use when restarting or checking the D:/NightSmith AntFarm colony after an antfarm/ code change, when its dashboard says 'Failed to fetch', or when judging if a pytest failure there is pre-existing. Al
SKILL.mdskills/managed/antfarm-colony-ops/SKILL.md
GitHubAntFarm colony ops (D:/NightSmith)
Repo-specific operational facts learned the hard way. Applies to the AntFarm
colony: supervisor loop + queen CLI + web dashboard on 127.0.0.1:8770.
For dashboard command bugs (toasts, buttons that do nothing), use
antfarm-webui-command-verify.
Interpreter
Always .venv/Scripts/python.exe. A bare python on PATH lacks the
project deps and dies with ModuleNotFoundError: No module named 'yaml'
before binding the port — which looks exactly like a server that started and
then broke.
.venv/Scripts/python.exe main.py --ui # colony + dashboard
.venv/Scripts/python.exe -m antfarm.queen_cli status
.venv/Scripts/python.exe -m pytest tests/ -q
AntFarm.cmd locates the venv itself, but it does not survive a
non-interactive/PTY shell: its rem comment lines get fed back to cmd.exe
as literal commands ('tarts' is not recognized...). Launch it by hand, or use
the venv interpreter directly from a script.
Windows switches from Git Bash
MSYS rewrites a single-slash switch into a path, so from Git Bash double it:
tasklist //FI, taskkill //PID <pid> //F, cmd //c. The single-slash forms
fail with ERROR: Invalid argument/option - 'C:/Program Files/Git/FI', or, for
cmd /c, print the cmd banner and run nothing (verified 2026-09-24). Single
slashes are right only in cmd or PowerShell.
Is it actually running?
"Cannot reach the dashboard server — TypeError: Failed to fetch" almost always means nothing is listening, not a code regression. Check in this order:
netstat -ano | findstr :8770 # LISTENING + pid, or nothing
tasklist //FI "PID eq <lock pid>" # is the run.lock pid even alive?
curl -sS -i http://127.0.0.1:8770/api/overview
Then read .antfarm/heartbeat.json (pid, cycle, uptime_s) and the newest
.antfarm/logs/events-*.jsonl for ui_listening / colony_start / a traceback.
run.lock needs no cleanup
.antfarm/run.lock holding a dead pid is not a blocker. runlock.read()
returns None when _pid_alive(pid) is false, so acquire() takes it. A clean
stop removes the file (main.py calls runlock.release, which deletes only its
own pid's lock); a kill leaves the dead pid behind, harmlessly. Never delete it
manually; never propose "clear the stale lock" as a fix. (verified 2026-09-24)
Restarting after a code change
The dashboard is served by the supervisor, so a server-side change is invisible
until the colony restarts. A frontend change also needs a rebuild, because
dist/ is what the server serves:
cd antfarm/webui/frontend && npm run build
Read
.antfarm/run.lockand check whether that pid is alive — never start a second colony.If live, stop it:
.venv/Scripts/python.exe -m antfarm.queen_cli stop. It is acked immediately but cannot abort an LLM call already streaming; if it is midstreaming:plannerit may needtaskkill //PID <pid> //F.reconcile_interrupted()cleans up the open episode on the next start.Start detached with the venv interpreter, leave it running and unpaused.
nohupsilently fails to detach on Windows; thiscmd //cform detached a test process when checked on 2026-09-24:cmd //c "start /B .venv\Scripts\python.exe main.py --ui > .antfarm\ui-restart.log 2>&1" sleep 30 && rtk read .antfarm/run.lock # must show a NEW pidProve it:
netstatLISTENING +curl /api/overview200 + heartbeat pid matches the newrun.lock. The new pid is the proof, not the launch command's exit code.
Known-failing test baseline
pytest tests/ -q has 12 pre-existing failures unrelated to any current
change. Confirm the set is unchanged; do not "fix" them and do not count them
against your work:
- 9 ×
tests/test_watchdog_liveness.py—AttributeError: '_Sup' object has no attribute '_drain_control_off_thread'(test double predates the method) - 2 ×
tests/test_lint_is_clean.py—TestPython(RUFF_BASELINE=29constant is stale, actual 43) andTestFrontend(oxlint drift inScreenMap.tsx) - 1 ×
tests/test_subprocess_decoding.py[supervisor.py-]— asubprocess.run(text=True)withouterrors=
Attribute any new failure properly: git stash, re-run the same test ids,
git stash pop. Never assert "pre-existing" without that comparison.
Repo conventions that bite
- No shell heredocs. They have corrupted source files here by interpreting
\n. Use the file-write tool. - Ruff runs
I001import sorting — adding an import to a module can fail the lint test by itself. Check the ruff finding count against baseline, not just the test's pass/fail. - Never
rmin the repo root during cleanup: an untracked, never-committedAntFarm-LAN.cmdwas destroyed that way and was unrecoverable (not in git, not in the backup zip, not in$Recycle.Bin). - Commit style: imperative subject < 72 chars, no
feat:/fix:prefixes, no attribution, flat- Imperative phrasebullets only when grouping.
Architecture facts worth not re-deriving
- Live roles are exactly
queen,planner,explorer(config.ROLES).coder/critic/testerare removed and a config naming them is rejected (config.py_REMOVED_ROLES); so are thevram/telemetry/budget/farm/backend/ollamasections (_REMOVED_SECTIONS). - Every role needs
roles.<role>.model; nothing picks one. Startup refuses withNoModelForRole. dispatch.triage_order()is the single ordering source read by bothQueen.cycleand the dashboard's/api/queue. Keep them on one function — they diverged once and the queue page silently showed nothing for months.- Control commands:
control/inbox.jsonlappend-only + byte offset. Both ends must open withnewline=""or Windows CRLF translation drifts the offset.