The Command record, and thirdshift status for a live Run #768

Parent

#711

What to build

A Run started on an Issue URL keeps a Command record on its machine. thirdshift status reads the records and lists the machine's live Commands.

The Command's process writes the record when the Run starts. Each write replaces the whole file atomically, beside its Command log. The record holds:

• a format version;
• the Command's kind, repository, and issue number, URL and title;
• the hostname;
• the process id and the process's start time;
• the Harness, Model and Effort, and when it started.

The record begins a stage at each of the Run's transitions: implement, Resume, Security review (when there is one), pull request (pushing it and marking it ready), CI watch, Repair, Self-merge and cleanup. Each stage has the time it began, plus the current Session log. The record ends with the outcome, the cause, and the Issue branch and pull request left behind. It stays after the Command ends.

thirdshift status covers every repository under the configured logs directory and names the host. It lists each live Command with:

• its issue and title;
• its Harness, Model and Effort;
• its stage and the stage's age (CI watch · 52 min).

A record with no outcome counts as live only while its process id is running with the recorded start time. Otherwise it shows as died at . The check works on both Linux and macOS.

status --json prints the same information as versioned JSON in the glossary's terms. The README documents it as the API that agents and the coming Console rely on (ADR 0016).

A record that can't be written gives one warning per Command and never changes the Run's outcome. A reader ignores stage names it doesn't know.

See #711's Implementation Decisions for the record's design.

Acceptance criteria

• A live Run started on an Issue URL appears in thirdshift status with its issue, title, Harness, Model, Effort, stage and stage age, and the host's name.
• The stage advances through implement, pull request, CI watch, Repair and Self-merge as the Run does, each with when it began.
• After the Run ends, its record keeps the outcome, the cause, and the branch and pull request left behind. status no longer lists it as live.
• After kill -9, the Command shows as died at its last stage.
• A record whose process id now belongs to a process with a different start time shows as died, not live.
• status --json carries a version field, and the README documents its shape.
• When the record can't be written, one warning appears and the Run's outcome is unchanged.
• End-to-end tests drive the binary with the existing fakes, using a fake Harness that waits. The recorder's tests for the effects adapter cover a write failure and a reused process id.