MGS3007: project lock held by an ancestor run

A magus run tried to lock a project that one of its own ancestor invocations already holds. The ancestor cannot release it, because the ancestor is blocked waiting for this run to exit, so the run is refused instead of queued.

[MGS3007] project . is locked by the magus run this one is nested inside
  (pid 42636 (magus run screenshots .)), which cannot finish until this one does.
  Waiting would never end, so it is refused instead.

Why

A run takes the EXCLUSIVE workspace lock for every project it selects and holds it for the whole invocation. That lock exists to stop two magus invocations from mutating one project at once, and for two unrelated runs, waiting is exactly right: the holder finishes, the lock frees, the waiter proceeds. The wait is announced up front and reprinted every 15 seconds.

Nesting breaks that reasoning. When the holder is an ancestor of the waiter, the holder is inside os.exec/magus.run, waiting for this very process to exit. Neither side can move. flock cannot tell this apart from ordinary contention, and neither can a timeout - a timeout only converts a hang into a late failure that still does not say why. magus carries each invocation's ancestry (MAGUS_INVOCATION_ANCESTORS, inherited like MAGUS_LEVEL, and recorded in the lock's owner sidecar) so the two cases can be told apart at the moment of acquisition.

The usual shape is a target that shells out to magus against its own project:

export fun deploy(ctx: magus\Context, args: [str]) > void {
    magus\run(["release"]);   // no project selector: the project this run holds
}

Every spawn that goes through magus's own subprocess layer is covered: os.exec("magus", ...), magus.cmd("run", ...), magus.run(...), and a shell script several levels down all inherit the ancestry and all raise this. A magus started by something that does NOT inherit that environment - a long-running service process, a detached daemon - is not covered, and still waits.

Resolution

1. Express the dependency instead of spawning one. A target that needs another target's work wants an edge, not a subprocess:

   export fun deploy(ctx: magus\Context, args: [str]) > void {
       ctx.needs(release);
   }
   

   One invocation then runs both, under one lock, with the cache and the affected-set tracking intact - none of which a nested process inherits.

2. Target a project the outer run does not hold. Nesting itself is fine when the project sets are disjoint: a root target may run magus\run(["build", "console"]) while holding only the root lock. Name the project explicitly so the selection cannot widen to the one the outer run holds - a bare magus\run(["build"]) selects by directory and can pick up the caller's own project.

3. Reach for a read-only subcommand. magus ls, describe, graph, and query take no project lock, so a target may call them freely. The typed in-process members (magus\projects, magus\targets, magus\affected, magus\graph) are better still: they answer from the workspace already open and never fork.

4. If the work genuinely belongs in a script, keep it in the script. A sequence of magus commands driven by a shell script is a valid thing to have; it just cannot be wrapped in a target that the commands then contend with. Run the script directly.

See also

• ctx.needs: the dependency edge to use instead of a nested run.
• magus status: names the lock's holder and every waiter, including this case.
• MGS5004: the other code about a run that cannot proceed in the process context it was given.