How a run works

One context, end to end

lumpcode run myLump on a laptop (mode: "shared" in local.json) rehearses on this branch:

1. Load the lump config. Soft-skip if the lump is disabled.
2. Resolve the context list, then ask git which of those names are still toDo.
3. Run the agent on this checkout. Each step's output prints while the command is still running. A dirty tree is allowed. No lump/… branch. The walk does not commit or push.
4. After a successful walk with contexts, a TTY (not --json) shows porcelain and [c] / [e]. c stamps LUMP markers (no push). e leaves the tree dirty.

Each worker pass (mode: "dedicated") still cuts lump/myLump/…, commits markers, and pushes. Lumpcode never merges. You open that pushed branch as a pull request, change it if the agent missed, and merge when it looks right.

Where “done” lives

There is no Lumpcode database. A context is finished when its marker commit is on origin/<baseBranch>. Until you merge (or otherwise put that commit on the integration branch), the next run will not treat it as done.

toDo ──run + push──► branchPushed ──you merge──► finished

dependsOnContexts requires finished, not branchPushed. A ticket that waits on schema will sit until the schema PR is merged.

run versus start

start is dedicated-only. It discovers every loadable lump (unless you pass --include / --exclude) on a cron, default every five minutes. New lumps appear on the next pass after you merge them to the branch the worker tracks. Nothing to deploy or register.

Companion commands: daemon-status, daemon-log, stop, restart. Project-wide stop is stop --all. start also keeps a supervisor process up; you do not run that yourself.

Daemon process files under ~/.lumpcode/daemons/<project>.<id>.daemon.*: pid, log, meta.json (spawn identity plus live overlay: in-flight lump lines, next tick, config fingerprint), desired.json (spawn recipe; stopping: true means drain). lumpcode daemon-status reads that overlay. Supervisor files: ~/.lumpcode/supervisor/<project>.{pid,log,meta.json}.

Daemon files from git

On a dedicated worker, commit .lumpcode/daemons/<id>.json so that daemon can start from git. Shared mode ignores these files. File shape: Start daemons from git.

Shared laptop versus dedicated worker

Get started is the laptop rehearsal. The worker is dedicated.

Shared loads config and runs the agent on this checkout. No pre-flight. Dedicated pre-flights this clone to a concrete discovery branch before config load (fetch / switch / hard-reset, not git pull), then pre-flights again at baseBranch for the run.

Branch resolution

effectivePrimaryBranches = primaryBranches or [primaryBranch]
primary                  = first exact entry          # all-glob list is invalid
scanBranches             = expand globs (dedicated)   # shared: exact primary only

effectiveDiscovery       = --discoveryBranch
                         | first exact lump discovery rule
                         | fail if pattern-only without the flag

resolvedBaseBranch       = lump baseBranch (string or fn)
                         | effectiveDiscovery

Discovery is where a dedicated worker finds the lump. Base is where work branches off and where finished is read. Dedicated allowlist: each lump discovery rule must match configured (unexpanded) primaryBranches. Shared run ignores discovery rules (warns if you pass --discoveryBranch). Inspect commands can still filter with the flag.

The open-branch cap is per lump name, across every scan line. On a dedicated worker, those lines run in remaining-batch order: each batch score is every numberOfContextsPerBranch-th sorted eligible-todo options.priority (lower first). A hotter feature/* line is not stuck behind the primary. The same lump + discovery branch stays sequential. lumpcode run is still one line.

Checkout or worktree

workspaceStrategy in local.json:

• checkout (default) — on a dedicated worker, the execution workspace switches onto the lump branch for the run, then back. One lump at a time in that folder. Shared run ignores this (stays on HEAD).
• worktree — the agent runs in .lumpcode/worktrees/<branch>/ (branch segments become folders: lump/a/b → …/worktrees/lump/a/b). The main tree can stay on the base branch. Needed if you want maxParallelRun > 1 on a worker. Execution-path lock is released after workspace setup; the git-object-db lock still serializes git.

If two things try to run at once

Lumpcode takes a lock on the folder it is about to mutate, and a second lock on the shared git object database so linked worktrees do not race. Manual lumpcode run fails fast if another run holds the lock (workspacePathBusy). A worker waits (up to 15 minutes), then skips that lump and tries again next pass.

Stale locks after a crash or stop --force clear themselves when the next acquire sees a dead PID.

Marker commits you should not rewrite away

Lumpcode always commits:

LUMP: <lumpName> - <contextName>

lump-status, clean, and context-status look for that string anywhere in the full commit message. foo does not match foo-bar. Keep it when you squash. If it is gone, the context looks toDo until you restore the line or run lumpcode context-status <lump> <context> --setToFinished.