Building a runner instance should need only this repository

[davidleomay]

Goal, from the owner: building a new runner instance should need only this repository. Today it needs two — agent for the skills and store, and a second, private one for the runner that actually turns a GitHub mention into a job.

This issue is to agree where that lands and who does it, not to propose a design.

Where the line runs today

Already here, and clearly right:

• session store, tasks, checklists, rounds, gates
• the skill contracts (spine, review-loop, pr-review, error-fix)
• hub pairing and sync, activity execution (pr.open, comment.post, issue.write, and review.post in 01a04284 - Publish rejected findings as a review, not a bare comment #41)
• agent supervise --session (01a04006 - Add a static closed-question supervise loop #39)

Still only in the runner repo, roughly 5 400 lines of bash across 3 binaries and 15 libraries:

ingest	GitHub notifications → a job, with actor/repo/job-type policy applied fail-closed
dispatch	claims a job, prepares a worktree, starts a detached tmux worker
supervise	finalises a job: outcome, done_kind, work_performed, contract_followed
job, prune, status, doctor	queue as a filesystem, retention, health
install, install-cron	deployment and the five cron lines
worker, github, instance_config	tmux sessions, gh calls, per-instance config split

Plus 11 test files, a Dockerfile, a compose example and docs/CONTAINER.md.

Note the name collision that keeps confusing this discussion: that repo is named after the first bot to use it, but nothing in it is bot-specific. Both bots run it. Only policy.json / runner.json are per-instance.

What is not obvious from the outside

agent supervise --session and the runner's supervise are different things that share a word. The first watches a session; the second finalises a job and decides whether work was actually performed — the check that catches a DONE marker emitted over an unfinished review. Folding one into the other is a design question, not a move.

Questions

1. Is this already in progress? The recent supervise/session work looks adjacent, and I would rather not duplicate it.
2. Does the runner move as bash, or get rewritten in Python alongside the rest of this CLI? The bash targets 3.2 for a macOS host; in a Linux container that constraint is gone.
3. What happens to the container packaging — does the image move here too, so docker compose up against this repo is the whole instance setup?
4. Where does per-instance config live afterwards — still a small private repo per bot, or something this repo describes?

Why it is being asked now

A second instance is being brought up on the existing image and hit two things worth knowing regardless of the answer:

• the image has no ps, so the runner's lock cannot build its owner token; mara_die fires inside a command substitution, so the caller continues with a lock that is silently ineffective rather than failing. One-line fix open as a PR against the runner repo.
• an agent store created natively on macOS (PostgreSQL 17) cannot be mounted into the image (PostgreSQL 15) — major version mismatch. device.json carries the pairing, so a fresh cluster keeps the identity and loses only task history, but it is a migration step rather than a copy.

Neither blocks the question above; both are cheaper to fix once, wherever the runner ends up living.

[davidleomay]

Owner decision: implementation is free to choose, and a rewrite is explicitly on the table. Measured the overlap before picking, because the answer turns on how much of the runner already exists here in Python:

already here	what it does	runner equivalent
lane.py 324 + runtime.py 176	vendor lanes, tmux process holder	worker.sh 429
store.py 742	owned rows, gapless events, sync	job.sh 218 + cmd_job.sh 475
github_act.py 580	gh execution, marker de-duplication	github.sh 296
watch.py 627	watch GitHub, insert script-owned rows	bin/mara-ingest 1158

Moving the bash as-is would import roughly 2 000 lines that already exist here in Python — two runtimes in one repo, two GitHub layers, and a filesystem queue beside a database. So: rewrite in Python here, not a move.

It is smaller than the 5 447-line figure suggests. Genuinely new work is the job lifecycle on top of the existing store, the fail-closed policy filter at ingest, and the completion check that decides work_performed / contract_followed. Estimated 1 200–1 800 lines rather than 5 400.

Answers to my own questions 2 and 3: Python, and yes — the container packaging comes here too, so docker compose up against this repository is the whole instance setup. Question 4 stays open: per-instance identity (expected_gh_user, actor and repo allow-lists) still wants to live outside the shared repo, but this repo should own its schema and validation.

Plan. One pull request per phase, each with tests and a mutation check that the tests fail when the behaviour is reverted:

1. job model in the store, plus instance policy and its validation
2. ingest — mention to job, fail-closed on actor / repo / job type
3. dispatch — claim, worktree, worker via lane.py / runtime.py
4. supervise — finalise, including the check that a DONE marker over unfinished work is recorded as failed
5. entry points, schedule, container packaging
6. instance configuration

The existing runner keeps running untouched until an instance is switched over, so neither bot stops. Phase 4 is the one to review hardest: it is the check that caught a review claiming completion over work it had not published, and porting it must not soften it.

Starting on phase 1.

[davidleomay]

Answers

The owner has settled the implementation question: we are free to choose what fits best, and a rewrite is welcome where it helps rather than a straight move.

• Q1 — already in progress? No overlap found with the adjacent supervise/session work.
• Q2 — bash or Python? Python, here, in src/agent_cli/. Rewritten rather than moved: the bash targets 3.2 for a macOS host, and that constraint does not survive the move anyway.
• Q3 (container packaging) and Q4 (per-instance config) are delegated to the implementation and settle in phases 5 and 6.

Shape

One phase per PR. Each lands a domain module next to chain.py and allow.py — no Postgres, no network and no subprocess inside the module itself; gh goes through an injected runner, the way watch.py does it.

Phase		Status
1	jobs.py — job identity, state machine, admits()	merged in #46
2	ingest.py — an admitted mention becomes a queued job	merged in #47
3	dispatch — claim a job, prepare a worktree, start the worker	open
4	supervise — finalise a job: outcome, done_kind, work_performed	open
5	entry points, schedule, container packaging	open
6	per-instance configuration	open

One thing to carry carefully

Phase 4 holds the check that decides whether work was actually performed — the one that catches a DONE marker emitted over an unfinished review. Porting it must not soften it. And keep the name collision in mind: agent supervise --session watches a session and is a different thing that shares the word.

Both side findings from the original post still stand and are still worth fixing once, wherever the runner ends up: the image without ps, which leaves the lock silently ineffective, and the PostgreSQL major-version mismatch when mounting a natively created store.