Cockpit on jira-ink's board with gh-ink PR rows: bottom-up placement, behind, ownership fences, hybrid transitions

[kud]

Project: kud/gh (@kud/gh-ink) — with steps in kud/jira-ink, ambre's cockpit host, and kud/jira-cli. Order is the user's: jira first, then gh, then mix them in ambre's cockpit. gh-cockpit (GitHub only) stays on gh-ink's inbox and is not touched.

Direction (2026-09-14, the user's)

The work-laptop cockpit becomes @kud/jira-ink's IssueBoard as the surface, with each ticket's PRs drawn as child rows by a PrRow exported from @kud/gh-ink, and the drills reusing the detail views that already exist (IssueBody from jira-ink; PrView / DrillView from @kud/gh-cockpit, which ambre already imports). "Improve gh-ink and jira-ink, then use them in cockpit; gh-cockpit is already amazing."

The rules

Placement — bottom-up. The tree never changes: an epic is always over its tasks. A tab decides which tasks and stories show — a task sits in the tab of its own status — and a parent comes along as the head of whatever it has there, selectable, children beneath. An epic's own status never picks a tab: an epic In Development whose tasks are all in Backlog heads them Off board and is absent from In progress; split tasks → the epic heads a group in each tab. An epic of mine with no tasks of mine on the board sits Off board. The epic's own status, when it differs from the tab, is a dim note on its head (In progress), and behind when it lags.

Fences. A fence appears only over tasks whose parent is not on this board — someone else's epic, or nobody's. A group label, never a row: not counted, never a cursor stop, opens nothing. Trailing segment says where the parent is: a tab name when it is on this board in another tab (· Off board, a promise that pressing through finds it), the owner when it is not (· @Priya, · unassigned) — @ is the house glyph for scope, as in the title bar's @you. On a mine board a tab name means yours and @name means not yours; no fence says both. On a multi-assignee board fences carry the owner as rows do. behind goes on a fence only when the parent is yours; behind and @name never share a fence. If the owner lookup lands after first paint, the segment stays empty until it does. (jira needs one extra key in (…) search for parents it holds no row for; cockpit's foreign-epics pass already knows the assignee.)

Notes and behind. A head whose children are partly elsewhere carries a dim note naming those tabs with counts (2 Off board, 1 In progress · 1 Review); omitted when all are here. behind — bright, a word not a glyph — when a row's own status lags the evidence: an epic Off board with any child started; an epic still open with every child Done; in cockpit only, a task whose PR is ahead of it (open while the task is To do / Off board; merged while it is still In progress). Notes and behind count only rows the board holds, never the epic-children query.

Transitions — hybrid. The row stays put with ⋯ → QA; on the 204 its status / statusId / category are rewritten locally and the tab follows, sub-second; on failure the marker clears and the flash carries Jira's own first line. The board refetch stays as reconciliation. Not optimistic.

Steps, in the user's order

1 · jira — @kud/jira-ink

• Leaf seam. — 303eee1, tree grammar per Iris (├─/└─ by last-ness, │ stems, 3 cols a level, no ┬).
  blocksFor(rows, under?) emits { kind: "leaf"; parent; depth: 1 | 2; data: L } for an opaque L; the board's cursor walks issues ∪ leaves so ↵ opens a leaf. IssueBoardProps.leaves?: { under(row) → L[]; keyOf(l); render(l, { active, width }); onOpen(l) }. jira-ink draws the tree cell for every row, leaf included, so the tree is one drawing; depth becomes 0 | 1 | 2. jira-ink stays GitHub-free. The depth-2 connector glyph is the designer's.
• Notes, behind, fences with tab name / @owner per the rules above; BoardRow.behind?: string host-filled and meaning-named; IssueBoard draws them. jira-cli gains the one key in (…) search for missing parents. — 1d1b094. Placement is bottom-up: placementOf / rowsInTab / headNote, and countsFor counts by it. The head's own-status note is prefixed own (Iris) so it cannot be read as a child count. The search is parentsOf in jira-ink, called by both hosts.
• Transitions. transitionsOf carries the full JiraStatus (id + name + category — @kud/jira already returns it). BoardRow.pending?: string; pendingRow / transitionRow / settleRow on BoardModel, tested beside board.test.ts; IssueBoard draws ⋯ → <tab>. — 1d1b094.
• subtreeOf(blocks, i) — pure, for C / O URL walking in the host. — in 303eee1.
• priorityMarker(name) → { marker, color } beside priorityGlyph, used by issue-board.tsx. — shipped in 0.7.0.
• Release. — 0.9.0 (the above) and 0.10.0 (onCursor, added because the board owned its cursor and no host could learn which row it was on — the move menu and C/O both need it).

2 · gh — @kud/gh-ink

• Export PrRow (src/components/pr-row.tsx, props { item: GHItem; active; login?; cols; icon? }) lifted from ItemRow's PR branch; transient/merged/leaving frames stay in the inbox; useBackdropped to its own module so both read it. Standalone render test. Release. — ad28295, @kud/gh-ink 0.61.0 (gh-cockpit 0.8.0 alongside). The seam is three declarative props — icon, motion, announcements — so every ramp and sparkle stays in the inbox. truncate and the backdrop context moved to their own modules. It takes cols; the leaf seam hands it width, which is the columns left after the cursor and tree cells.
• q → Ink's exit() — already shipped. inbox.tsx:4116 and 4761 both call Ink's exit(), rationale at 4114. The three remaining process.exit(0) sites are not quit bindings and must stay: two in inbox.tsx (1485, 4386) fire after spawning a detached osascript that writes git switch into iTerm, and ai-panel.tsx:175 after runHere() — a shell command is taking over the terminal. Whether Ink's async unmount can be sequenced ahead of a detached process claiming the tty is a separate, unsolved question, with a failure mode (terminal left in the alternate screen) only a manual pass catches.
• Adopt useAppKeys at the cockpit root — done, 4d5f45b + 2e307ca. Neither of the two shapes first sketched was right: @kud/ink-ui's AGENTS.md prescribes that a *-ink view binds neither key and the host mounts the hook once with a peel. hidden was left intact (its listen guard sits below a deliberate idle-pulse re-arm, so splitting it would stop an idle return re-arming). Closed a hole where phase: "loading" bound q nowhere, and a live ordering bug where esc cleared the filter and left an inner layer standing. Awaiting a manual pass — ~/__tmp/qa-gh-113-keys.md.

3 · ambre cockpit, slice 1 — a second entry point, not a replacement

• Mount Page + useAppKeys + IssueBoard: fetchJira → BoardRow[]; fetchInbox → fileTicketPRs → under; rows sorted by mostUrgent so blocksFor's order-preservation gives urgency-ordered groups for free (whose-move headers dropped); ↵ on a ticket → IssueBody, ↵ on a PR → PrView with the app's q stood down while it is mounted (PrView binds its own back); r, q. Transitions via pendingRow / transitionRow / settleRow around the jira issue move --json shell-out, reading transition.to. No menu, rail, Jenkins, mute, CI, cache yet. CONTAINER_ISSUE_TYPES already gone; PILL_VARIANTS → jira-ink's pillVariantFor. — app/src/cockpit-board.tsx, reachable as cockpit --board, beside the old one.
• ticket-tree-probe.ts probes the sort and under instead of block assembly. — not done; the old probe still tests the old assembly, which is still in use.

4 · ambre cockpit, slice 2 — parity, then delete the old one

Scoped down, deliberately — see Cut for good below.

• M actions via the exported ActionMenu / buildActions (PR leaves unchanged; tickets a three-item list); C / O over subtreeOf; signalPath + fs.watch + r; Jenkins J, mute (z, not m — m was wrong in this list), ticket T. — T needed no binding: ↵ on a ticket already mounts IssueBody, which is what the ticket extension existed to do. Moves live inside M rather than on their own key.
• Delete the old cockpit.tsx. Held — see the escalation below. Everything else in slice 2 is done or cut.

Cut for good, not deferred:

• The rail (SidePanel / railsOf). A full-width tree is the right shape for rows this indent-hungry, not a reduced one — the rail was earning its column on a flat list.
• readCache / writeCache. Typed around gh-ink's CachedCockpit, which cannot hold BoardRow[]. A local cache for a board nobody has opened yet is machinery against an unmeasured cold start.
• CiStatusLine. Replaced by one word in Page's own status slot, off the same fetchJenkinsJobBuilds poll — that is what the line was actually for, and without a rail beside it the full line reads as an orphan. J still opens the explorer.

Already dropped for good: transient/merged/leaving ramps, the budget notice.

5 · jira-cli

• In-frame busy on transition (the detail stays mounted; only the transition key locked; error in-frame). Pin jira-ink. — b2ddc4f. Pinned 0.5.0 → 0.10.0, so it also picks up 0.6–0.8. No refetch after a move at all: the status is written from the transition's own target.

Out

Optimistic moves. A single-issue reload after a transition. A status word on rows that agree with their tab. Which statuses cockpit's stage tabs claim (the To do / Backlog question). Migrating gh-cockpit off the inbox. A plugin seam in jira-ink.

Acceptance

1. Move an epic to In Development while its stories stay in Backlog: the epic is absent from In progress and heads the two stories Off board with the note In progress. Same in both boards.
2. Leave an epic in Backlog while a story goes to Code Review: Review shows the epic heading that story with behind · Off board (bright behind); Off board shows it heading its remaining stories with 1 Review.
3. Cockpit only: a task Off board with an open PR reads behind · PR #… open; the PR is a leaf row under it, ↵ opens PrView.
4. Transition a row: within a second it reads ⋯ → <tab> then sits in the new tab, before any refetch; a rejected transition leaves it where it was with Jira's message in the flash. In jira, the detail stays on screen throughout.
5. Notes and behind count only rows the board holds.
6. A high-priority ticket shows ▲ before its key in both boards, in the same colour; a story pill is the same colour in both — trivially, since it is one component.
7. Under a story whose epic is assigned to someone else, the fence reads · @<first name> and no tab name; under a story whose epic is yours and in another tab, the fence reads that tab's name and no @.
8. Slice 1 runs beside the old cockpit; the old one is deleted only when slice 2 reaches the parity table.

Next steps

One, and it needs the work account: run cockpit --board on the work laptop, check it against the parity list, then delete app/src/cockpit.tsx. Nothing else is outstanding.

[kud]

Step 2's key-contract bullet rests on a premise that isn't true any more, and the half that remains is bigger than the bullet suggests. Traced today before touching anything.

q → Ink's exit() already shipped. inbox.tsx:4116 and 4761 both call exit(), with the rationale at 4114 — "Ink's exit, not process.exit: it unmounts and hands the terminal back (alternate screen included)". The three remaining process.exit(0) sites are not quit bindings: two in inbox.tsx (1485, 4386) fire after spawning a detached osascript that writes git switch into iTerm, and ai-panel.tsx:175 fires after runHere(). They exit because a shell command is taking over the terminal. Whether Ink's async unmount can be sequenced ahead of a detached process claiming the tty is a real and unsolved question, but it is a different one, and its failure mode — terminal left in the alternate screen — only a manual pass catches.

"Drills close on esc rather than q" is not five one-line deletions. The drill renders as an overlay beside BrowseScreen, not instead of it, and the host passes hidden={overlay !== null} (inbox.tsx:5607) — which makes the app-level useInput return early at 3923 and the screen render null at 4498. So while a drill is open, the app's q is already stood down. Strip || input === "q" from the five drill views (pr-view, issue-view, file-picker, check-log-view, ai-panel) and q in a drill does nothing at all — breaking the contract in kud/ink-ui#5 ("q quits from anywhere, at any depth") in the opposite direction from the one being fixed.

The real choice is between each drill binding q → useApp().exit() itself — five bindings restating one contract five times — or narrowing the hidden gate so the app-level quit survives an overlay while everything else stays suppressed. The second is cleaner, but hidden also drives the null render, so it is not a one-liner either.

Worth splitting the bullet in two, as kud/ink-ui#5 already does when it lists cockpit as "two items not one".

[kud]

Follow-up to the note above, and it changes the answer rather than refining it. @kud/ink-ui already ships the mechanism, and its AGENTS.md prescribes a shape neither of the two options I sketched matches.

useAppKeys exists and is exported — ink-ui 0.28.2, already installed in this workspace, present in dist/index.d.ts. kud/ink-ui#5 still shows its checkbox unticked, so it is the issue that is stale, not the package. gh uses it zero times.

Its AGENTS.md states the contract directly:

Three keys belong to the app, never to a screen: q, esc, backspace. useAppKeys({ onBack, onQuit, atRoot, isActive }) binds them, and it is mounted once, at the root. Ink runs every active useInput on every key with no order and no propagation, so "who gets esc" is only ever solved by there being one claimant.

and, on exactly the five files in question:

A view exported from a *-ink package takes onBack and never binds esc or q itself. The host's peel routes to it.

So the correct shape is not each drill binds q → exit(), and not hoist q above the hidden gate. It is: the five drill views bind neither q nor esc, and the host mounts useAppKeys once with a peel function — onBack closing the topmost layer it owns and returning true, false when there is nothing left to pop. isActive: false while a text field has focus, which is the same guard that stops q quitting mid-search and is why this is safer than hoisting the key by hand.

That is a larger change than this bullet describes and it lands squarely on the hidden flag, which is currently doing two jobs — don't render (inbox.tsx:4498) and don't listen (3923) — off one boolean. Untangling those is the actual work.

It also reaches past this repo: useAppKeys is the mechanism kud/ink-ui#5 exists to spread, and gh adopting it is one host's half of that, not a local key tidy-up.

It should not ship without a manual pass. A keyboard contract across five mount depths with a text input in the blast radius, in a TUI whose failure mode is the app quits when you did not mean it to. No test here covers pressing q in a search box, and the Ink tests that mount a real terminal are already the flaky ones — so the likeliest failure is also the one least likely to be caught automatically.

[kud]

Checked step 1's actual state against the published package rather than assuming, because step 2's PrRow is defined by it. The leaf seam has not landed, so PrRow stays blocked.

@kud/jira-ink@0.8.0 (published 2026-09-15, six releases today), inspecting dist/index.d.ts from the tarball:

step 1 bullet	state
Leaf seam — blocksFor(rows, under?), IssueBoardProps.leaves	✗ blocksFor is still (rows: BoardRow[]) => Block[], and IssueBoardProps has no leaves
Notes, behind, fences — BoardRow.behind	✗ no behind on BoardRow
Transitions — BoardRow.pending, pendingRow / transitionRow / settleRow	✗ none present
subtreeOf(blocks, i)	✗ not exported
priorityMarker(name)	✓ shipped — exported, returns { marker, color }

So one of six.

That matters specifically because PrRow's props are the seam's output contract. This issue specifies PrRow taking cols, while the seam it plugs into is specified as render(l, { active, width }) — and width versus cols is exactly the kind of detail that gets settled when the seam is actually written. Extracting PrRow now means guessing, publishing, and republishing when the guess is wrong.

Erwann's ordering — jira first, then gh, then mix them in ambre's cockpit — is doing its job here. Nothing to do on this bullet until IssueBoardProps.leaves exists.

Worth noting there is no local checkout of jira-ink on this machine, so that work is happening elsewhere; the versions above came from the registry.

[kud]

The key contract is built and pushed — 4d5f45b (root) and 2e307ca (drills). Body updated. It is not verified in a running terminal, and that is the one step left on this half.

Neither of the two options in my previous comment turned out to be right. @kud/ink-ui's AGENTS.md prescribes a third shape: "A view exported from a *-ink package takes onBack and never binds esc or q itself." So the five drills bind neither, and the app root mounts useAppKeys once with a peel — each screen publishing a priority order over its own booleans as a plain function, never a back stack.

Three corrections found while tracing, all of which would have cost a commit:

hidden is not the defect and must not be split. Four lines above its listen guard re-arm the idle pulse deliberately — a key pressed at a hidden tab is still evidence of a person at the keyboard. Move that job to isActive and an idle return to a hidden tab stops re-arming. Both jobs stay on the one boolean.

There was a hole nobody had noticed: during phase: "loading" nothing bound q at all. App returns above BrowseScreen, and NoRowsScreen only mounts on empty or failed — so a slow cold fetch could be left only with ctrl+c. Mounting at the root closes it for free.

A live ordering bug in the browse arms: they were written in source order rather than priority order, so with an inner layer open and a filter set, one esc cleared the filter and left the inner layer standing. The peel fixes it, and a regression pins it.

Two automated tests now cover what is mechanically checkable (packages/gh-ink/src/inbox/app-keys.test.tsx): q typing into the search box rather than quitting, and one esc peeling one layer. Writing them turned up a harness trap worth recording — a lone ESC byte is the prefix of every arrow key, so Ink's parser waits before calling it an escape. Two microtask flushes are not a wait; the press needs a real ~20ms delay. sidebar.test.tsx had already documented this and I rediscovered it the slow way.

Gate green: 590 tests across four packages.

What stays manual is in ~/__tmp/qa-gh-113-keys.md — ordered likeliest-failure-first, which is q inside the search box, not q inside a drill. The step I am genuinely least sure of is the AI launcher's "here" placement: the process.exit(0) behind it was left alone on the reasoning that Ink's async unmount would race the terminal handover, and that reasoning is untested.

[kud]

decision-needed · external-action — Deleting the old app/src/cockpit.tsx needs one live run of cockpit --board on the work laptop, which only the work Claude account can reach — this session is on the personal account, and everything shipped is verified by typecheck and invented fixtures only.

Clears when: cockpit --board has been opened on the work account and checked against slice 2's list: tabs and counts, an epic heading its children in more than one tab, a PR leaf under a task with enter opening PrView, M on both a ticket and a PR, C and O, z on a PR, J, r after a signal write, and a real transition landing in its new tab within the second.

Escalated by atelier.

[kud]

Loading states and a full-screen frame landed in the board host (kud/ambre):

• 55e172c bumps @kud/ink-ui to 0.32.0 and @kud/jira-ink to 0.11.0 together, so the board and its host share one ink-ui copy.
• 82621ce wires them in:
  • cold load draws IssueBoardSkeleton through the same frame as the board, with ⠋ reading the board
  • every Page takes fill and sizes from Ink's useWindowSize()
  • status slot precedence: error, then ⠋ refreshing, then ⠋ pull requests…, then the CI word, then freshness
  • a failed refresh keeps the board and its cursor, showing ✗ refresh failed · r retry with the message in the flash line
  • a cold-load error gets a full-size page with a real r retry
  • the ticket drill renders inside a nested Page with the key as scope
  • fixes a render loop: an inline leaves.under made onCursor re-fire forever ("Maximum update depth exceeded")

Rendered against a local fake Jira only, not a real instance. New items for the work-laptop manual pass:

• Cold load shows the skeleton (tabs with (–), placeholder rows) and the turning reading the board, then the rows replace it without the frame moving
• Resizing the terminal re-fits the frame and the board, both loaded and on the skeleton
• A refresh that fails (e.g. network off, then r) keeps the rows and the cursor and shows ✗ refresh failed · r retry; r once the network is back recovers
• A cold-load error shows the full-size ✗ … page, and r there really retries (skeleton, then the board)
• enter on a ticket opens the drill inside the cockpit frame (key as scope, ⌫ back in the hints); ⌫ returns to the board on the same row

[kud]

Land and submit are now wired into the board cockpit (cockpit-board.tsx) in ambre at 26a03c4f.

• L (land) and S (submit) work on a PR leaf, and they show up in the M menu too. Eligibility stays in the extensions; the board only hides S on a PR it has just submitted.
• The confirm replaces the board inside the cockpit's full-screen frame, the same way mute and Jenkins do it. While it is open, q, esc and backspace go to the confirm, so they cancel and never quit or go back.
• The submit lockout clears whenever a fresh inbox arrives.

So far this has only been checked against a fake Jira and a stubbed gh. Nothing has run against a real PR yet. Checks still to do on the work laptop:

• L on my own approved PR → the preview paints → y → merged, ticket moves to QA, and the row updates after the refetch
• S on my own draft. The cockpit can't pass --no-slack, so run gh pr-submit <url> --no-slack from the terminal first. Then in the cockpit, the preview shows the channel and the message → type send ↵ → marked ready, ticket moves to review
• Double-press guard: straight after a submit, S on the same row does nothing and M doesn't offer Submit until the next refresh brings in fresh pull requests
• A blocked PR (failing checks, or a head that moved) shows its reasons with no confirm line, and any key closes it
• n, esc and q on the preview each cancel without running --go, and q doesn't quit the cockpit

One known cost: closing the confirm remounts the board, so the cursor and tab go back to their defaults. Mute and Jenkins already do this. Fixing it needs a way to switch IssueBoard's keys off from outside, and it doesn't have one yet.

[kud]

The board cockpit no longer unmounts the board under a screen, so closing one lands on the same tab and row.

• kud/jira-ink@d8e2cae adds isActive?: boolean (default true) to IssueBoard. When it is false, the board still renders but binds no keys: tabs, cursor, Enter, /, ?, a, r, x, and typing into an open search box are all off. Cursor, tab, search and scroll state are kept. Released as @kud/jira-ink@0.12.0.
• ambre c0ec107 bumps the cockpit to 0.12.0. IssueBoard now stays mounted under every screen: land L, submit S, mute z, Jenkins J, and both drills (IssueBody and PrView). It sits in a <Box display="none"> sibling, so the tree keeps the same shape and React keeps the instance. It gets isActive={false} while a screen is up or the M menu is open, which also fixes the old bug where ↑↓ in the menu moved the board underneath. useAppKeys is unchanged.

Checked with a fake Jira and a stubbed gh driven through expect, rendered by a headless terminal. Before the change, closing L dropped the cursor back to the first row of the first tab, and two ↑ presses in M moved the board from #11 to #12. After it, the cursor stays on #11 in In progress through L, z, M (arrows included) and both drills.