Markdown tickets in.
Pull requests out.

01 · How it works

┌────────┐   claim    ┌─────────────┐   run    ┌────────────────────────┐
│ inbox/ │ ─────────► │ processing/ │ ───────► │ agent in a worktree    │
└────────┘  (atomic   └─────────────┘          │ run → verify → critic  │
     ▲       rename)         │                 └───────────┬────────────┘
     │                       │ transient                   │ push
     │                       │ failure,                    ▼
     │                       │ no commits        ┌───────────────────┐
     └── requeue ◄───────────┘                   │ draft PR → done/  │
         retry_count++ · not_before              └───────────────────┘

1. Claim is one atomic rename — inbox/ to processing/ — so two workers can never own the same ticket.
2. Four loop guards watch the agent's event stream; a supervisor nudges, escalates, then kills. A killed or timed-out run still gets its commits salvaged into a draft PR.
3. junco runs the ticket's verification blocks in the worktree, then a critic reads the diff against the spec — a MISSING verdict buys exactly one corrective pass.

02 · One ticket, end to end

$ junco submit fix-tide-rounding.mdsubmitted: ~/junco/inbox/fix-tide-rounding.md $ junco logs -f14:02:03 INFO  worker online {"pid":51423}14:02:07 INFO  claimed {"src":"inbox/fix-tide-rounding.md","dst":"processing/fix-tide-rounding.md"}14:14:41 INFO  [fix-tide-rounding] spec verification: 2/2 checks passed14:14:58 INFO  [fix-tide-rounding] critic: pass14:15:02 INFO  [fix-tide-rounding] pushed junco/fix-tide-rounding (3 new commits)14:15:09 INFO  [fix-tide-rounding] opened PR https://github.com/acme/reef-api/pull/5714:15:10 INFO  [fix-tide-rounding] finalized (pr-flow) {"dst":"done/fix-tide-rounding.md","status":"completed"}14:15:11 INFO  idle▌

03 · The ticket

---
id: fix-tide-rounding
priority: normal
timeout_minutes: 30
repo: ~/code/reef-api
base_branch: main
pr_title: "fix: round tide heights to one decimal"
draft: true
---

# Round tide heights to one decimal

`TideTable.render()` prints raw floats. Round display values
to one decimal; leave the underlying data untouched.

## Steps

- [ ] Add `formatHeight()` in src/tideTable.ts; use it in `render()`.
- [ ] Commit: `git add -A && git commit -m "fix: round tide heights"`

## Verification

```bash
npm test
```

## Done when

- [ ] 1 commit on the branch; `npm test` green.

Without a repo: field this is a Q&A ticket — answered in place, read-only, no git. junco schema prints the full frontmatter contract.

04 · Capabilities

Atomic claiming

A ticket moves inbox/ → processing/ in one rename; ownership is never ambiguous.

Plans before code

In GitHub mode the plan is an issue comment; nothing runs until a verified junco:approved label.

Supervised sessions

Four loop guards on the event stream: nudge → escalate → kill. Every run leaves a JSONL transcript.

Timeout salvage

Commits made before the cutoff are pushed and opened as a draft PR instead of thrown away.

Requeue with backoff

Transient endpoint failures set retry_count and not_before, then return the ticket to the inbox.

Offline outbox

Comments, labels, and PR pushes queue durably while GitHub is unreachable, then drain on reconnect.

Local-first

Your machine, your git, your gh auth, any OpenAI-compatible inference endpoint. No third service.

A dashboard worth living in

Repos, plans, approvals, queue, and open PRs in one fullscreen terminal UI with a command palette.

05 · Sixty seconds to a running worker

Node ≥ 22.19, git, and an authenticated gh for PR flows.

npx @ironforgesoftware/junco   # first run → setup wizard; afterwards → the daemon
junco submit my-task.md        # a repo: field opens a PR; without one it answers in place
junco status                   # daemon · endpoint · queue at a glance
junco dashboard                # or drive everything from the TUI

06 · Contribute

junco is young, and the codebase is still small enough to hold in your head. ~1,100 tests run in a few seconds; ARCHITECTURE.md is accurate and maintained. For features, open an issue first — plans are cheap, rework isn't. junco dogfoods: it submits tickets against its own repository.

git clone https://github.com/ironforgesoftware/junco && cd junco
npm install && npm test       # vitest, ~1,100 tests, a few seconds