magus v0.4.3 is out. See what's new
¶ View markdown source · ✎ Suggest an edit
6 min read

Splitting other work

The jobs guide splits a code change. The same commands split any work whose pieces are files: each job names the files it may write, so two people cannot quietly take the same slice, and magus job wait tells the person keeping the list whether a piece is done. Three examples, each verified the way the first page's are: the transcripts are compared byte for byte by cmd/magus/testdata/script/job_people_*.txtar.

A dependency upgrade, one project at a time

A shop has two projects, api and web, each pinning a library in its own deps.txt and each with its own test target. The upgrade splits one job per project, declared together in one stream:

$ magus job apply -f - <<'EOF'
{"schema_version": 11, "id": "upgrade/api", "criteria": "api runs left-pad 1.3", "write_paths": ["api/deps.txt"], "check": {"target": "test", "project": "api"}}
{"schema_version": 11, "id": "upgrade/web", "criteria": "web runs left-pad 1.3", "write_paths": ["web/deps.txt"], "check": {"target": "test", "project": "web"}}
EOF
created upgrade/api, declared, with 1 write path(s)
created upgrade/web, declared, with 1 write path(s)

Each job's check is that project's own test, so api passing says nothing about web. Ana takes upgrade/api in her worktree and Ben takes upgrade/web in his, each with magus job exec. Who holds what, from anywhere:

$ magus ls jobs -o template='{{range .jobs}}{{.id}}  {{.checkout_root}}{{"\n"}}{{end}}'
upgrade/api  ~/src/ana
upgrade/web  ~/src/ben

Each bumps the pin, runs magus run test api or magus run test web, and exits the job with the run's ref, as on the first page. Whoever keeps the list checks each piece:

$ magus job wait upgrade/api
verified upgrade/api, recorded pass
its holder reports it ran magus run test api
goal check: verified (out<hex>)
footprint: where its diff since the checkpoint landed
  api/deps.txt:1-1
console: nothing is serving it; `magus server start` to watch this job without interrupting its holder

and the whole set is done when every row reads pass:

for job in upgrade/api upgrade/web; do
  magus job wait "$job" > /dev/null || echo "$job is not done"
done

$ magus ls jobs
JOB          HOLDER  STATE  MODEL  PATHS  PROOF  CHECK
upgrade/api  ana     pass   -      1      alone  magus run test api
upgrade/web  ben     pass   -      1      alone  magus run test web

in flight: never fetched; `magus queue ls --provider <provider> --base <branch>` reads the open changes
console: nothing is serving it; `magus server start` to watch this job without interrupting its holder

A job holding upgrade/api that also changed web's deps.txt would not pass: wait holds every changed line to the job's write paths.

Translating pages without sharing one

Two translators divide a docs site by page. The repository marks Markdown with git's Markdown diff driver, which is what lets magus see headings inside a page:

*.md diff=markdown

Ana forks fr/install on the French install page and takes it in her worktree. Ben, in his, claims the same page for the section he wants:

$ magus job fork fr/upgrading --criteria 'upgrading section in French' --write-paths docs/fr/install.md --check 'lint .'
[error] magus job fork: [MGS3032] job: fr/upgrading declares "docs/fr/install.md", and fr/install (running, updated 0s ago) already holds "docs/fr/install.md". Both are live and neither is the other's parent, child, or depends_on partner, so docs/fr/install.md has one owner unless the rows say otherwise. fr/install has touched none yet in it so far. Claim `docs/fr/install.md#<declaration>` on both rows, add `--depends-on fr/install` to fr/upgrading, or fold fr/upgrading into fr/install
  see: https://eli.gladman.cc/magus/reference/codes/sandbox/MGS3032/

Refused, with no row written: the page is held in another checkout, so it has one owner until the rows say otherwise. The refusal names the ways out. They split the page by heading, which narrows Ana's job and declares Ben's in one stream:

$ magus job apply -f - <<'EOF'
{"schema_version": 11, "id": "fr/install", "criteria": "install page in French", "write_paths": ["docs/fr/install.md#Installer"], "check": {"target": "lint", "project": "."}}
{"schema_version": 11, "id": "fr/upgrading", "criteria": "upgrading section in French", "write_paths": ["docs/fr/install.md#Mettre à jour"], "check": {"target": "lint", "project": "."}}
EOF
updated fr/install, still running:
  write_paths +docs/fr/install.md#Installer -docs/fr/install.md
created fr/upgrading, declared, with 1 write path(s)

The part after # names a heading the diff driver matches. Once Ben takes his job, the board shows the shared page and why it is not a conflict:

$ magus ls jobs
JOB           HOLDER  STATE    MODEL  PATHS  PROOF     CHECK
fr/install    ana     running  -      1      alone     magus run lint .
fr/upgrading  ben     running  -      1      disjoint  magus run lint .

overlaps
  fr/install and fr/upgrading claim common ground
    fr/install: docs/fr/install.md#Installer
    fr/upgrading: docs/fr/install.md#Mettre à jour
    claims: disjoint (different declarations of one file: an integration order, not a wait)
    footprints: disjoint

in flight: never fetched; `magus queue ls --provider <provider> --base <branch>` reads the open changes
console: nothing is serving it; `magus server start` to watch this job without interrupting its holder

When each exits, magus job wait places every changed line under the heading it landed in, and a line in the other translator's section is named as a violation.

A release checklist

Each item on a release checklist is a job whose goal says what done means. A goal needs no target: paths goals read the diff and the tree.

$ magus job apply -f - <<'EOF'
{"schema_version": 11, "id": "release-1.3/changelog", "criteria": "CHANGELOG.md has a 1.3 section", "write_paths": ["CHANGELOG.md"], "goals": [{"id": "changelog", "kind": "paths", "expect": "changed", "paths": ["CHANGELOG.md"]}]}
{"schema_version": 11, "id": "release-1.3/notes", "criteria": "release notes exist for 1.3", "write_paths": ["notes/1.3.md"], "goals": [{"id": "notes", "kind": "paths", "expect": "present", "paths": ["notes/1.3.md"]}]}
EOF
created release-1.3/changelog, declared, with 1 write path(s)
created release-1.3/notes, declared, with 1 write path(s)

Two people take an item each in their own worktree. The changelog gets written. The notes are blocked on numbers that do not exist yet, so their holder says so on the way out instead of pretending:

$ magus job exit release-1.3/notes --stdin <<'EOF'
{"schema_version": 2, "changed_paths": [], "unresolved_risks": ["the notes need the final benchmark numbers"]}
EOF
exited release-1.3/notes, recorded exited, with its result filed. Whoever forked it verifies with `magus job wait release-1.3/notes`

The board says both items came back, and nothing more:

$ magus ls jobs
JOB                    HOLDER     STATE   MODEL  PATHS  PROOF  CHECK
release-1.3/changelog  changelog  exited  -      1      alone  -
release-1.3/notes      notes      exited  -      1      alone  -

in flight: never fetched; `magus queue ls --provider <provider> --base <branch>` reads the open changes
console: nothing is serving it; `magus server start` to watch this job without interrupting its holder

Coming back is not being done. The person cutting the release checks each item:

$ magus job wait release-1.3/changelog
verified release-1.3/changelog, recorded pass
goal changelog: verified
footprint: where its diff since the checkpoint landed
  CHANGELOG.md:3-6
console: nothing is serving it; `magus server start` to watch this job without interrupting its holder

$ magus job wait release-1.3/notes
rejected release-1.3/notes, and its state is unchanged
  job release-1.3/notes is not read-only and the result claims no changed paths at all
  nothing in the diff since 5f6b136f2721af3fb8a117fbf824b24a3a78b059 is inside its write paths (notes/1.3.md)
  goal "notes": nothing matching "notes/1.3.md" is in the tree, so this goal is unmet
goal notes: rejected
footprint: no line changed since the checkpoint
unresolved risks its holder reported
  the notes need the final benchmark numbers
console: nothing is serving it; `magus server start` to watch this job without interrupting its holder

Exit 1, every unmet rule named, and the risk repeated where the person deciding will read it. The board is the checklist:

$ magus ls jobs
JOB                    HOLDER     STATE   MODEL  PATHS  PROOF  CHECK
release-1.3/changelog  changelog  pass    -      1      alone  -
release-1.3/notes      notes      exited  -      1      alone  -

in flight: never fetched; `magus queue ls --provider <provider> --base <branch>` reads the open changes
console: nothing is serving it; `magus server start` to watch this job without interrupting its holder

The release waits until every row reads pass. An item nobody will finish ends with magus job exit <job>, recorded no_return, so the board never shows a skipped item as a finished one.

GuidesPages in this section. JobsCoordinate work by hand with magus job (one person across two worktrees, two teammates sharing a file, and CI recording whether merged work still passes), and what the job store tells you about who holds what, since when, and what done means. Jobs and leasesThe surface magus gives an agent that fans work out (the working-state checkpoint, the declared job store, the lease a holder takes on a job, the console Jobs view, the recorded spawn, and verifying a result against the diff since the checkpoint). The broker and the servermagus runs up to two background processes. The broker holds this host's capacity and shared services and a run starts it; the server serves MCP, the console and jobs and a person starts it.
jobsmagus jobdependenciesupgradestranslationdocsreleasechecklistwrite paths
Last updated (895d94e4)
Earlier changes on this page (1)

Full history ↗ · Blame source ↗

Glossary

Project

A directory magus recognizes as a unit of work (it has a magusfile); the unit of caching, scheduling, and dependency tracking. See workspace.

Target

A named operation (build, test, ...) you invoke with magus run <target>; it may compose a spell's tool-native operations and depend on other targets. See targets.

Op

A single tool-native command a target composes (long form: operation); the middle of the work hierarchy (Spell to Op to Target). See operations.

Sandbox

The restricted filesystem and environment a target runs in, so builds stay reproducible and side-effect-free. See sandbox.

Server

The background process a person starts with magus server start. It serves MCP, the console, background jobs and the warm knowledge graph, and adopts nested magus calls into one pool. See server.

CI

An ordinary magusfile-defined target you compose yourself with magus\needs: magus does not hardcode its stages. Magus.RunCI treats it specially only in that it strips the rw charm, it is the anchor magus affected ci keys off, and a selected scope with no project declaring it is a load error rather than a silent no-op. See targets.

Job

The unit of delegated work, and one row of the job store: what an orchestrating agent handed out, with its goal, the checkpoint it was cut against, the paths it may write or must not touch, and the one check it runs. A job's holder is either a session, for work an orchestrator handed out, or the server, for its own maintenance. The store records; the agent guard is what reads those facts back when grading a write. See doctrine.

A job is not a run. magus run build web is a run, and no job exists for it. A job causes runs: its check executes as one, and a server job records the invocation of its last one. Jobs are listed with magus ls jobs and in the console's Jobs view; runs are listed in the Runs view.

Run

One target executing under one magus invocation, such as magus run test web or magus affected ci. A run keeps its captured output behind an output reference. Every magus run is a run whether or not any job asked for it; see Job for how the two relate.

Lease

The grant a holder takes on a job: the write and read paths that job declared, enforced in the checkout that took it with magus job exec. A job is the piece of work; a lease is permission over it.

Conventions

Placeholders

Angle brackets mark a value you replace with your own; never type the brackets:

magus run <target>
magus completion <shell>    # e.g. bash, zsh, fish

<target>, <path>, <shell>, <name> and the like are stand-ins, not literal text.