[JacobStephens2]

Closes #212

Summary

thirdshift pickup starts a Pickup run: one pass, with no Issue URL, that takes the lowest-numbered Ready issue and dispatches it as thirdshift <Issue URL> would. The operating system's scheduler starts each pass (ADR 0009).

thirdshift pickup [base <branch>] [merge|no-merge] [base-fix|no-base-fix] [parallel <n>] [email [<address>]|no-email]
  arguments, User config
  the Run notification's checks          # no address or key: exit 1, every pass
  the preflight checks of an Architect run
  the lock shared with an Architect run  # held: skipped
  the Sweep                              # in-progress off closed issues
  the Claim limit (pickup.limit, 3)      # at or over: skipped
  search open issues labelled ready-for-agent, lowest number first
    each passed over: one stderr line, the first reason that applies
    none is a Ready issue: skipped
  dispatch: a Spec run if it has sub-issues, a Run otherwise
    makes the Claim: in-progress in place of ready-for-agent
  ends as the dispatched run does, with one Run notification if asked

A skipped pass exits 0, with stdout empty, one line of reason on stderr and no Run notification.

The Claim is made by every Run and Spec run but a Ticket's Run and a Base fix, however it was started:

Run or Spec run on an issue
  preflight checks pass
  make the Claim                 # one request; creates the label if missing
  worktree, sessions, ...
  ended merged, issue closed  -> in-progress removed
  ended ready for review      -> Claim kept
  failed, issue was started   -> Claim kept    # an Issue branch on origin, or a pull request from one
  failed, never started       -> Claim released, labels as they were

Where the work lives:

src/
├── pickup.rs        # the search, the Ready issue rule, the skips
├── claim.rs         # make, release, remove on close, the Sweep, the open count
├── launch.rs        # the start an Architect run and a Pickup run share: checks and lock
├── args.rs          # the pickup command; one dispatch for architect and pickup
├── config.rs        # pickup.limit
├── notification.rs  # one checked core for the three Run notifications
└── github.rs        # issues by label and state, parent, timeline, label requests
.agents/skills/      # Day shift: ready-for-agent on a Spec means its Tickets are published
README.md, CONTEXT.md, docs/agents/triage-labels.md, thirdshift help

What the Spec review changed

 release the Claim after a failed Run
-  unless this Run's own branch is on origin, or has a pull request
+  unless the issue was ever started: any Issue branch for it on origin,
+  or a pull request from one, open, merged or closed

• A failed retry on issue-<n>-branch-2 used to release its Claim though issue-<n> had left a pull request. The Spec releases only with "no Issue branch on origin and no pull request for the issue", which is now the same question the Ready issue rule asks.
• in-progress is taken off as the issue spells it in the release and after a Self-merge too, as the Sweep already did. The case rule for a label has one home, in github.rs.
• thirdshift help names the Sweep and drops "cleaned up", which the glossary lists under Avoid.
• The glossary's Ready issue now says it carries no Claim, as the code, the README and the help do.

Seam tested: the thirdshift binary run against the fake gh and the fake claude.

Evidence

• Before: a_failed_retry_keeps_its_claim_when_an_earlier_issue_branch_left_a_pull_request failed: the issue's labels were ["ready-for-agent"], not ["in-progress"].
  After: it passes.

issue #7 labelled ready-for-agent, with a closed pull request from issue-7
thirdshift <Issue URL of #7>, and the session exits 1
  -> a Failed run, nothing of issue-7-branch-2 on origin
  -> #7 is labelled in-progress, and stderr has no "releasing the Claim"

• cargo test: every test binary passes, 0 failed, among them the 68 tests of tests/pickup_run.rs. cargo fmt --check and cargo clippy --all-targets are clean.
• Not tested, as the Spec says: the crontab recipe in the README. Try it on a real machine when reviewing.

Merge Danger

Door: two-way

Reverting the merge takes pickup away again. What it leaves on GitHub is the in-progress label on issues and in the repository, which is removed by hand.

Blast Radius: labels

• Every Run and Spec run started by hand or by an Architect run now relabels its issue: in-progress in place of ready-for-agent. Anything else that reads ready-for-agent on a running or reviewed issue no longer finds it.
• The Architect run's skip reason is reworded to an Architect run or a Pickup run is already running on <owner>/<repo>: a script that matches the old line breaks.
• A Pickup run on a schedule starts agent sessions unattended. The Claim limit, the lock and the Ready issue rule bound it, and nothing runs until a crontab line is added.

Unaddressed findings

Spec

• A failure before the Claim is retried on every pass, and blocks the queue. A dispatched run that fails before it makes the Claim leaves no Claim, branch or pull request, so the issue stays the lowest-numbered Ready issue: each pass takes it again, exits 1 and sends its notification, and the Claim limit never engages. Two lasting cases: a local Issue branch a Failed run kept after its push failed, and an open ready-for-agent Spec whose Tickets are all closed with no Spec branch. Skipped because the fix changes the Ready issue rule the Spec fixed ("no Issue branch for it on origin"), which is the Day shift's decision. Worth an issue of its own.
• A ready-for-agent Ticket whose Spec is a Ready issue gets no passed-over line, where the Spec says each issue that isn't a Ready issue gets one. Skipped: it was a deliberate choice in the Ticket's review, since "its Spec is not ready" would be false, and the README says so.

Standards

• The Sweep's warnings are formatted by hand, not through progress::warn. Skipped: warn prints two lines and names a command to run by hand, and the Sweep's one warning: ...: <error> line is what the README documents and the next pass retries.
• createdAt is parsed in two places in github.rs, and tickets() inlines label names. Skipped: the two sites report different sources in their errors, and tickets() reads GraphQL nodes, not the list label_names reads.
• tests/pickup_run.rs copies seven helpers and four constants from tests/architect_run.rs. Skipped: helpers per test file are the practice here (KEY, ACCEPTED and the_one_notification were in several files before this branch). Moving them to tests/support is a refactor of its own.
• pickup::run and architect each match on launch::start with the same AlreadyRunning arm. Skipped: three lines, mapping to two different outcome types.
• dispatched takes parallel beside dispatch.parallel, and email beside the args it came from. Skipped: a Pickup run overrides parallel for an issue that is not a Spec, so the two differ on purpose.
• Launch has a field git, while launch elsewhere names a &Git. Skipped: a rename across modules this Spec did not write, with no behaviour in it.
• READY_FOR_AGENT lives in spec_run and is imported by four modules. Skipped: it sits with the other triage labels there, the one home the Spec names for the Unready Ticket labels.

Tickets

• The Claim: a Run or Spec run marks its issue in-progress #280 landed with The Claim: a Run or Spec run marks its issue in-progress #291
• Releasing a Claim, and removing it when thirdshift closes the issue #281 landed with Releasing a Claim, and removing it when thirdshift closes the issue #294
• thirdshift pickup: take the lowest-numbered Ready issue and run it #282 landed with thirdshift pickup: take the lowest-numbered Ready issue and run it #293
• The rest of the Ready issue rule, and saying why an issue was passed over #283 landed with The rest of the Ready issue rule, and saying why an issue was passed over #296
• The Claim limit, and taking in-progress off closed issues #284 landed with The Claim limit, and taking in-progress off closed issues #297
• One Run notification for a Pickup run that took an issue #285 landed with One Run notification for a Pickup run that took an issue #298
• Day shift skills: ready-for-agent on a Spec means its Tickets are published #286 landed with Day shift skills: ready-for-agent on a Spec means its Tickets are published #290
• README: running a Pickup run on a schedule #287 landed with README: running a Pickup run on a schedule #299

🤖 Generated with Claude Code