signed/docs/PLAN.md

PLAN — PR contribution flows: fork compare + GRASP-06 hosting + checkout suggestions

Status (2026-09-03): implemented. Steps 1-9 and 11 are done on feat/fork; step 10 (sidebar "Ready to contribute" group) remains deferred as planned (v2, optional). See docs/PR_FLOW.md for the resulting flow; the per-step sections below record what shipped and where the plan was refined during implementation.

Combined implementation plan for three coordinated improvements to Signed's pull request experience:

• A. Fork-aware compare — the New PR panel's compare side can come from an announced fork repository's branch (fetched into the base repo's GitCache mirror), instead of only from a user-picked local checkout.
• B. GRASP-06 hosting — PR tips are pushed to the author's own grasp servers under /prs/<author-npub>/<repo-id>.git and advertised in the PR's clone tag, so contributing to someone else's project never depends on their servers accepting anything from you.
• C. Checkout associations & suggestions — remember/derive which local folders are checkouts of which announced repos, auto-prefill the New PR panel (no folder picker for the common case), and suggest creating a PR when a branch is ahead with no open PR (GitHub-like nudge, NIP-34-native dedupe).

Guiding principles (agreed): follow nostr + grasp + ngit, not GitHub; NIP-34/GRASP-06 event surface stays untouched (no new tags/kinds, forks never appear in events); every flow keeps the patch series as the source of truth; no over-engineering — reuse existing stores, patterns and git helpers.

---

1. Protocol grounding (what we may and may not do)

1.1 NIP-34 facts used by this plan

• A PR (kind-1618) is addressed to the base repo coordinate (a tag) and carries c (tip), merge-base (common ancestor with the target branch), branch-name, clone (≥1 URL where the tip commit can be downloaded), e → root patch event, r (EUC), p (base owner). Patches are NIP-10-chained kind-1617 events, ≤60 KB each. Statuses 1630–1633 resolve the PR.
• Repository announcements (30617): u tag marks a subordinate fork (30617:<pubkey>:<id> coordinate or git URL); the r/euc tag identifies the earliest unique commit, shared by every repo of the same project family (forks, mirrors). Both are read-only inputs for discovery.
• Kind-10317 is the user grasp list (g tags, in preference order) — read-only input for hosting.
• Anybody may open a PR on any announced repo; only the author may update it (1619); only the author or a maintainer may set status; merge is the maintainer's action.
• "Patches and PRs to a repository SHOULD be sent to the relays specified in that repository's announcement" — i.e. the base repo's relays, always.

1.2 GRASP-06 facts (as ngit implements it — verified against ngit-cli)

• GRASP-06 servers expose a contributor namespace: http(s)://<host>/prs/<contributor-npub>/<repo-id>.git (input ws:///wss:// base URLs normalize to http(s)://; npub in the URL, hex on the server's disk — a server detail). Anyone can push there; no announcement, no maintainer rights, no fork repo required.
• The author's server is tried first; the base repo's announcement grasps still receive the same refs/nostr/<event-id> push as redundancy.
• The PR event shape is unchanged; only which URLs the clone tag lists differs.

1.3 Consequences (locked decisions)

• Publishing keeps today's event set and tag semantics. The fork changes only where the patch series is generated from; GRASP-06 changes only where the tip is pushed and advertised; suggestions change nothing on the wire.
• We never publish a reference to the fork or to /prs/ hosting beyond legal clone URLs.
• The PR clone tag is fixed before signing (the refs/nostr/<event-id> ref name embeds the event id), so it carries the full candidate URL set (author /prs/ URLs + base announcement clone URLs). Dead URLs are inert — patch events remain the truth — and ngit readers fail over across URLs. (ngit instead rebuilds the event per server to keep a single clone URL; we deliberately do not copy that.)

---

2. Workstream A — Fork-aware compare

2.1 Model

The panel keeps today's behavior as the default source and adds a second:

• Checkout (existing): both selectors list a user-picked local checkout's branches; git ops + tip push run in the checkout.
• Fork (new): the flow runs against the base repo's GitCache mirror P_base = GitStore::global(cx).cache().repo_path(&base_addr) (ensured via GitCache::ensure_clone(&base_addr, &base_clone_urls) + fetch_all):
  • "Merge Into" lists P_base branches (refs/remotes/origin/*);
  • "Pull From" lists the chosen fork's branches, imported into P_base;
  • merge-base, range commits/diff, format-patch, and the tip push all run against P_base — both histories share one object store, and commit-diff rows work because fork commits live there.

2.2 Git mechanics (import namespace)

Fork heads are fetched into P_base under a private namespace:

git -C P_base fetch <fork-clone-url> '+refs/heads/*:refs/fork/<owner-hex>/<sanitized-id>/*'

• refs/fork/… keeps imported refs away from refs/remotes/* and refs/heads/*, so the repo browser, repo_branches and DWIM checkout never see them.
• Fetch tries each announced clone URL until one works (grasp:// → https:// rewrite, GIT_TERMINAL_PROMPT=0), like clone_repo / push_commit_ref.
• Switching fork or refreshing: prune the old refs/fork/<owner>/<id>/* prefix first (git update-ref --stdin fed by for-each-ref), then re-import. All-heads import in one fetch; subsequent branch switches within the same fork are offline.
• Range work uses full refs: merge_base(P_base, "refs/remotes/origin/<base>", "refs/fork/…/<compare>"), then the existing worktree_commit_range_commits/worktree_commit_range_diff / format_patch_between. None of these touch the checkout state.
• Base main and fork main are different refs: the "choose different branches" guard compares full refs, display names stay short.

2.3 Fork discovery

Candidates = RepoListStore::global(cx).read(cx).announcements (already deletion-filtered, latest-wins) where Announcement::is_fork_of(base_addr, base_euc):

• upstream.addr == Some(base_addr) (the u tag — also covers permanent forks whose EUC changed), or
• euc == base announcement's euc (shared earliest-unique-commit family), excluding the base repo itself.

Ordering (identity-coherent, ngit-style): your own forks first (30617 owner == signed-in user), then other authors' related repos (same mechanics, marked, niche). Announcements without clone URLs are excluded (unfetchable). Restricting to your own forks only later is a one-line ownership filter.

2.4 Panel behavior

• Defaults mirror apply_checkout: base = announced store.head if present in mirror branches, else main, else first; compare = fork's main, else first fork branch.
• submit: format_patch_between(P_base, merge_base, compare_ref); published branch-name = compare short name; push_from = Some(P_base) (fork objects are there after import). Publishing itself is workstream B.
• open_commit_diff uses P_base in fork mode.
• Errors: no common ancestor → existing message; unreachable base mirror or fork → inline error; empty range → existing "no commits to propose".

---

3. Workstream B — GRASP-06 author hosting

Applies to every PR publish from a repo path that has the objects — checkout mode and fork mode alike. RepoStore::open_pull_request keeps its signature; internals change:

1. Resolve author grasp servers (new shared helper): latest kind-10317 grasp list of the signed-in user from the local DB (filters::grasp_list, g tags in order) → fallback to settings defaults (GraspServersSettings.default_servers / DEFAULT_GRASP_SERVERS, the same source the create-repo dialogs use) when no list is published.
2. Build /prs/ URLs: grasp_base_url(server) + "/prs/" + user_npub + "/" + base_repo_id + ".git" (npub form, like ngit; grasp_base_url maps wss→https, ws→http).
3. clone tag = dedup of /prs/ URLs plus the current base-announcement clone URLs (order: /prs/ first — the author's servers are the most likely to be alive and author-controlled).
4. Push loop = author /prs/ servers first (guaranteed writable — the point of GRASP-06), then the base announcement grasp servers (existing behavior), all refs/nostr/<event-id> from push_from. Best-effort; zero successes → existing last_warning banner; publishing always proceeds.

Effect: a repo announced with relays but no reachable grasp hosting still gets a downloadable tip (on the author's own hosting), and git-native clients (ngit, git-remote-nostr) can fetch Signed PR tips from the clone URL.

1619 updates are out of scope for v1: the update dialog is paste-only, so no repo path holds the new tip's objects. Deferred until the existing "local-checkout generation for the update-PR dialog" TODO lands; then push the new tip to the same /prs/ set under the PR's stable ref (refs/nostr/<root-pr-event-id>, advanced per revision — convention to verify against ngit-grasp first).

---

4. Workstream C — Checkout associations & suggestions

Three tiers: Remember → Auto-pick → Suggest.

4.1 Remember (associations)

A local folder ↔ announced repo association comes from two sources:

• Explicit (persistent settings records {path, addr, last_used}): recorded when the repo header Clone action succeeds (addr known) and when a folder pick succeeds in the New PR panel (store addr known).
• Implicit (derived, no persistence): among LocalReposStore scan results (settings local_repos.scan_paths), a repo whose
  • origin URL matches an announcement clone URL (compare host+path, ignoring scheme: ws/wss/http/https/grasp are equivalent transports of the same grasp URL), or
  • root commit equals the announcement EUC is a checkout of that announced repo.

Resolution order per repo: remembered (freshest first) ∪ scanned-matched, deduplicated by path, skipping missing directories.

4.2 Auto-pick (New PR panel prefill)

open_new_pull_panel(…) gains a suggested-checkout parameter, resolved by the caller from the association store:

• Exactly one checkout → auto-apply it: selectors populate, base = announced HEAD, compare = current branch, diff loads. The folder button becomes "Change…".
• Several → a small folder combobox instead of the modal folder picker.
• None → today's flow unchanged.
• Successful manual folder picks are recorded back (learning).

4.3 Suggest (status + surfaces)

A small checkout-status computation (part of the association store), scoped to the bounded set of associated checkouts, on background threads:

• Triggers: app open, window focus (debounced ~5 s), LocalReposStore rescan, BackendEvent::Synced.
• Per checkout: current branch; commits ahead of the base branch (announced HEAD name if present locally, else main, else first local branch — the same rule as apply_checkout), via rev-list --count; whether the user has an open PR from that branch on the target repo (author == me, branch-name tag == branch, fallback: tip c tag == local HEAD).
• Result states: ReadyToCreate { target, branch, ahead, base } / HasOpenPr { … } / Idle.
• Noise rules: only when ahead > 0 and branch ≠ base; nothing for dirty worktrees; one entry per target repo.

Surfaces:

Surface	Shows	Dedupe data source	Scope
Repo PR list banner (PullRequestsView)	"branch feature is 3 commits ahead of main — Create pull request →" (opens prefilled New PR)	live open RepoStore (precise)	v1
Sidebar "Ready to contribute" group	row per ReadyToCreate: target repo, branch ↑N → opens target repo + prefilled New PR	v1: only targets with a live open store, else a local-DB query refreshed after a lazy per-target bootstrap activity sync; if the repo has no data yet, the group omits it (no false "ready")	v2 (after v1 proves out)
Repo detail header chip	tiny feature ↑3 on the repo whose checkout is ahead	as PR-list banner	optional

The PullRequestsView banner reuses the existing dismissible Alert banner pattern already used for store errors/warnings.

---

5. Combined flow (fork mode, end to end)

sequenceDiagram
    participant U as User (New PR panel)
    participant P as Base mirror (GitCache)
    participant F as Fork grasp server
    participant A as Author grasp (GRASP-06 /prs/)
    participant B as Base repo grasps
    participant R as Nostr relays

    U->>U: pick fork repo (u/EUC relation, yours first) + branch
    U->>P: ensure_clone(base) + fetch_all
    P-->>F: fetch +refs/heads/*:refs/fork/<owner>/<id>/*
    P-->>U: base branches (origin/*) + fork branches (refs/fork/…)
    U->>P: merge-base, range commits, range diff (Files/Commits tabs)
    U->>P: submit: format-patch merge-base..fork-ref
    U->>R: publish kind-1617 series (root + NIP-10 chain, ≤60 KB each)
    U->>R: sign kind-1618 (a=base, c=fork tip, merge-base, branch-name, clone=[/prs/…, base clone URLs], e=root patch, r=EUC)
    U->>A: push tip → refs/nostr/<event-id>  (author servers, first)
    U->>B: push tip → refs/nostr/<event-id>  (best-effort redundancy)
    U->>R: publish kind-1618
    Note over R: zero successful pushes → last_warning banner only

Checkout mode is identical except the fork-import step; suggestions (workstream C) only add entry-point shortcuts into this flow.

---

6. Step-by-step implementation

Phases are ordered so each step lands on green: foundations first, then the publish-side change (benefits the existing checkout flow immediately), then the fork UI, then the UX layer. Every step compiles, passes its tests, and keeps existing behavior unchanged.

Phase 0 — Foundations

Step 1 — signed_core: fork relation predicate

• File: crates/signed_core/src/model.rs.
• Add Announcement::is_fork_of(&self, base: &RepoAddr, base_euc: Option<&str>) -> bool: upstream.addr == Some(base) OR (base_euc present AND self.euc == base_euc), excluding self (same owner + id).
• Tests: u-tag coordinate match; shared EUC match; permanent fork with different EUC matched via u; no-match; base-self exclusion.
• Done when: predicate + tests green; used by Step 5.

Step 2 — signed_git: mirror/import primitives

• File: crates/signed_git/src/lib.rs.
• fetch_repo_refs(repo_path: &Path, urls: &[String], refspec: &str) -> Result<()> — CLI git fetch <url> <refspec>, grasp:// → https rewrite, GIT_TERMINAL_PROMPT=0, try each URL until one works (last-error on all failing, like clone_repo).
• refs_with_prefix(repo_path: &Path, prefix: &str) -> Result<Vec<String>> — full refnames under prefix (git for-each-ref --format=%(refname)), sorted.
• delete_refs_with_prefix(repo_path: &Path, prefix: &str) -> Result<()> — collect via for-each-ref, delete via git update-ref --stdin lines.
• origin_url(workdir: &Path) -> Result<Option<String>> (used by Step 7).
• Tests (existing file:// fixture infra): import under a target prefix; URL fallback to the working server; prefix listing; prefix deletion; origin URL read.
• Done when: helpers + tests green.

Phase 1 — GRASP-06 hosting (publish side)

Step 3 — author grasp-server resolution

• File: crates/signed_state/src/backend.rs (or a small new module).
• resolve_user_grasp_servers(cx, user) -> Vec<RelayUrl>: latest kind-10317 of user from the local DB (filters::grasp_list; latest event wins; g tags in order) → fallback to settings GraspServersSettings defaults/DEFAULT_GRASP_SERVERS when the user has no grasp list.
• Refactor the create-repo/init dialogs to share it (optional, keeps one resolution path).
• Tests: latest-wins selection; missing list falls back; g order preserved.
• Done when: helper + tests green.

Step 4 — open_pull_request hosting

• File: crates/signed_state/src/repo.rs (open_pull_request, ~L657).
• Pure helpers (unit-testable): grasp06_prs_url(base_url: &str, npub: &str, repo_id: &str) -> String; push-target assembly (author /prs/ URLs first, then announcement grasp URLs; dedup).
• clone tag = /prs/ URLs (author npub from Backend::current_user(), repo id from self.addr().identifier) + base announcement clone URLs.
• Push loop extended: existing per-relay loop stays; author servers push to the /prs/ URL instead of the repo URL. Warning semantics unchanged.
• Tests: URL building; target order; dedup. Behavioral coverage of the full publish is manual/e2e (see §8) until a harness exists.
• Done when: checkout-mode PRs push to the author's grasp list (/prs/<npub>/<repo-id>.git) first and the clone tag carries those URLs; all-servers-fail still publishes with a warning.

Phase 2 — Fork-aware compare

Step 5 — fork candidates

• File: crates/workspace/src/views/repo_detail/new_pull_request.rs (helper) or crates/signed_state.
• fork_candidates(cx) -> Vec<Announcement>: filter RepoListStore::global().announcements with is_fork_of (Step 1); exclude empty clone; sort own forks (owner == current user) first, then others, each group by recency/name. Re-read each time the picker opens.
• Done when: helper returns the expected ordering for a mixed list.

Step 6 — New PR panel fork mode

• File: crates/workspace/src/views/repo_detail/new_pull_request.rs.
• State: CompareSource { Checkout, Fork { announcement } }; per-mode item sets for both selectors; mirror_path; fork branch list; full-ref base/compare tracking (display keeps short names).
• choose_fork(announcement) + prepare_fork (mirror choose_checkout / apply_checkout async shape, compare_generation guard): ensure base mirror (ensure_clone + fetch_all), prune previous refs/fork/… prefix, import fork heads (fetch_repo_refs), list both ref sets (refs_with_prefix), populate selectors with defaults, reload_compare.
• reload_compare / submit / open_commit_diff become mode-aware (path + base ref + compare ref resolution; format_patch_between and push_from on P_base; published branch-name = short name).
• UI (compare bar): source control next to "Pull From" (local checkout / announced fork), fork-repo combobox (grouped, own forks first), refresh affordance, "Change…" back to checkout; loading spinner; inline errors.
• Done when: checkout mode is byte-identical in behavior; fork mode shows base/fork selectors, Files/Commits tabs, commit diffs, and publishes with the correct tags (manual §8).

Phase 3 — Checkout associations & suggestions

Step 7 — association store

• Files: crates/settings (extend the settings model like local_repos.scan_paths with remembered checkouts {path, addr, last_used}); new crates/signed_state/src/checkouts.rs (global store, Arc + debounce pattern from LocalReposStore/ RepoListStore).
• API: associations_for(addr) -> Vec<PathBuf> (remembered freshest-first ∪ scanned-matched by origin URL/EUC via Step 2's origin_url + signed_git::root_commit; scheme-insensitive URL compare; dedup; skip missing dirs); record(path, addr).
• Recording hooks: repo header clone_to_folder success (repo_detail/mod.rs) and choose_checkout success (panel).
• Tests: matching by origin URL (scheme variants), by EUC, no match; dedup and ordering.
• Done when: associations resolve correctly and persist.

Step 8 — New PR prefill

• Files: new_pull_request.rs (open_new_pull_panel + new); callers repo_detail/mod.rs header and pull_requests.rs.
• Entry param suggested_checkout: Option<PathBuf> (default None); panel applies it on construction when the folder still exists, else falls back to the empty state. When several candidates exist the caller passes the freshest and the panel offers the others through a folder combobox (new small control next to the source button).
• Done when: opening New PR on a repo with a remembered/matched checkout never shows the folder dialog; manual picks get remembered.

Step 9 — status computation + PR-list banner

• Files: checkouts.rs (status states + triggers + debounce), workspace pull_requests.rs (banner), new_pull_request.rs (accepts the banner's "create" click by opening prefilled).
• Status rules from §4.3; banner dedupe against the live open RepoStore (author + branch-name, fallback tip match, open status only).
• Done when: after committing on an associated checkout and opening the target repo's PR list, the banner appears exactly when ahead > 0 and no open PR exists, and disappears after creating/merging/evening.

Step 10 — sidebar "Ready to contribute" group (v2, optional)

• File: crates/workspace/src/views/sidebar/mod.rs (+ checkouts.rs support).
• Only list targets with reliable dedupe data (live open store, else a local-DB activity query refreshed after a lazy per-target bootstrap activity sync); omit everything uncertain. Clicking a row opens the target repo (open_repo_panel) + prefilled New PR.
• Done when: rows appear without false "ready" entries (dedupe-uncertain targets omitted).

Phase 4 — Docs & validation

Step 11 — documentation and final validation

• Update docs/PR_FLOW.md: fork compare path, GRASP-06 server set + clone tag, suggestion surfaces; the mermaid sequence in §5.
• Update docs/TODO.md: tick "Fork-aware compare…", "GRASP-06 …"; add the checkout-suggestions item; keep deferred items (1619 update push, sidebar group, reading-side clone-URL fetch) explicit.
• Run the manual validation checklist (§8) end to end.

---

7. Error handling & edge cases (all inline or warnings, as today)

• Base mirror unreachable / no base clone URLs → panel error in fork mode; checkout mode unaffected.
• Fork unreachable / without clone URLs (excluded from candidates) → panel error.
• No common ancestor → existing error (range flow needs shared history; Send Patch remains the fallback).
• Author has no 10317 list and no default servers → GRASP-06 adds nothing; today's warning stands.
• Author's grasp server does not implement /prs/ → its push fails silently in the loop; its URL in clone is inert; base grasps still tried.
• Fork branch deleted upstream / fork switched → prune prefix + re-import; generation guard discards stale compares.
• Concurrency on P_base with the repo browser: we never checkout; git ref locks make overlapping fetches safe (same class as today's browser refresh).
• Multiple checkouts of one repo → freshest first, "Change…"/combobox for the rest.
• Branch renamed after a PR → dedupe falls back to tip-commit matching; otherwise a duplicate suggestion may appear once (accepted v1 tradeoff).
• Suggestions never block UI; results arrive as Arc swaps.

8. Non-goals / deferred (explicitly out of scope)

• 1619 update hosting (depends on the local-checkout update-dialog TODO).
• Paste/Send-Patch flow keeps no git push (no object store; patches = truth; no scratch-apply resurrection).
• Reading side: fetching other clients' PR tips from clone URLs into the mirror (ngit pr checkout analog) — only needed for patch-less PRs.
• Fork creation UI (Signed still cannot announce forks; they come from ngit or by publishing a clone) — fork candidates simply won't include non-existent ones.
• GitHub-isms rejected: no fork-network browser, no per-fork PR pages, no fork identity in events, no "compare across forks" for strangers' branches beyond what is listed above.
• The panel never auto-submits anything; suggestions only navigate and prefill.

9. Validation checklist (manual e2e)

1. Checkout mode regression: clone a repo to disk, branch + commit (external git), New PR → choose folder → diff/commits → Create → PR appears on the target repo's PR list; tip pushed to the author's /prs/ server(s) from the 10317 list (fallback: defaults); clone tag lists /prs/ URLs first.
2. All grasp servers down/absent → PR still publishes; warning banner shows.
3. Fork mode: with a fork announcement related to the base (own fork first, other author's fork listed), pick repo + branch → selectors, Files/Commits tabs, commit-diff rows correct; published 1618 carries a = base coordinate, c = fork tip, merge-base = fork point, branch-name = fork branch; tip fetchable from the advertised /prs/ URL via a plain git fetch.
4. Prefill: reopen New PR for the same repo → folder auto-chosen, selectors populated; "Change…" works.
5. Banner: with the repo's PR list open and an associated checkout ahead with no open PR → banner appears; disappears after publishing a PR, after merging, and when the branch is even.
6. Interop: an ngit/git client fetches a Signed PR's tip from the /prs/ clone URL (requires a GRASP-06-enabled server).

10. Implementation log (2026-09-03, branch feat/fork)

All steps below landed with unit tests; cargo test across signed_core (44), signed_git (61), signed_state (15), workspace (14) and settings (9) is green, and cargo check on the whole workspace passes. The manual e2e checklist above still needs a real GRASP-06 server run.

• Step 1 — Announcement::is_fork_of (signed_core::model) + 4 tests.
• Step 2 — signed_git: fetch_repo_refs, refs_with_prefix, delete_refs_with_prefix, origin_url, GitCache::root() + 4 tests (import/list/prune against file:// fixtures incl. URL fallback).
• Step 3 — backend grasp-list resolution: grasp_list_servers, latest_grasp_list_servers, user_grasp_list_servers (DB query, latest wins) + grasp06_prs_url and pr_clone_urls (author-first, dedup) + 4 tests. signed_state gained a settings dependency for the defaults fallback.
• Step 4 — RepoStore::open_pull_request (signature unchanged): resolves the author's grasp servers (10317 → settings defaults) inside the publish task, builds the clone tag from /prs/ URLs first, pushes author /prs/ targets before the base announcement's servers, deduped; all-fail keeps the last_warning banner. 1619 updates untouched (deferred, as planned).
• Step 5 — fork_candidates ordering helper + 2 tests (own forks first; base/unrelated/no-clone excluded; EUC-less base still matches via u).
• Step 6 — New PR panel fork mode: ForkCompare state, choose_fork/ apply_fork (mirror ensure_clone → prune refs/fork → import → list both ref sets), mode-aware base_ref/compare_ref/work_path used by reload_compare/submit/open_commit_diff, stale-result guard, refresh-by-re-picking + refresh button, and a "Source" picker menu (checkout rows + forks) replacing the folder button. Checkout mode stays byte-identical in behavior. Deviations from the plan: selectors and the source picker keep one shared layout (no separate fork-repo combobox — the source menu lists forks grouped own-first, matching the ordering requirement); IconName::GitBranch does not exist upstream so fork rows use the project's CustomIconName::GitBranch.
• Step 7 — settings CheckoutRecord/CheckoutsSettings group + new signed_state::checkouts::CheckoutsStore global (observe settings / local scan / announcements; debounced, coalesced, Arc-swapped): scheme-insensitive same_repo_url, resolve_associations (remembered freshest-first ∪ scanned origin/EUC matches, dedup, mirror-cache paths excluded), record(), per-repo request_statuses/statuses_of with CheckoutStatus (branch/head/base/ahead; dirty and detached checkouts never suggested; 15 s poll while any PR list is open). 7 tests. Deviations: settings records store the address as a string (the settings crate stays free of nostr types); mirror exclusion uses the cache root (new GitCache::root()); statuses are computed per requested repo with the announced HEAD supplied by the open list panel rather than from a 30618 DB query.
• Step 8 — New PR panel prefills the freshest associated checkout on construction (no folder dialog); apply_folder_path applies a given path; successful folder picks and header clones are recorded back; the Source menu lists associated checkouts (checked when applied) plus "Choose another folder…". Deviations: instead of a separate folder combobox, the alternatives live in the Source menu (fewer controls, same outcome); open_new_pull_panel needed no signature change because the panel reads the association store itself.
• Step 9 — "ready to contribute" banner: RepoDetailView requests the statuses while the repository panel is open (re-requested when the announced HEAD lands or changes) and renders the banner under the repo header; the first ready checkout not covered by an open PR of the signed-in user (branch-name, fallback c-tag tip) and not dismissed (per-panel dismissal set) is offered with a Create button opening the prefilled panel. The dedupe predicate is the tested pr_proposes_checkout in signed_state::checkouts. Deviation from the plan: the surface is the repository panel (not the PR-list panel, as the user requested after v1; the PR list keeps only its error/warning banners), and there is no window-focus trigger (no precedent in the codebase; the 15 s poll plus open/rescan/settings triggers cover the plan's "done when" cases).
• Step 10 — deferred (v2, optional), per plan; the banner is the v1 surface.
• Step 11 — docs/PR_FLOW.md rewritten for the current panel flow (fork import, GRASP-06 hosting, suggestions, deferred items explicit); docs/TODO.md updated; this log added. Manual e2e (§9) not yet run against a live GRASP-06 server.
• Fix (after e2e, user report) — creating a repository left the project only inside the app's GitCache mirror: the announcement, state event and push happened, but the folder chosen in the Create Repository dialog was just remembered as a settings default. Backend:: create_repository now also materializes a working copy at <folder>/<sanitized-name> (cloned from the mirror via a file:// URL so it shares the announced history exactly, then origin re-pointed at the first grasp server through the new signed_git::set_origin), and the dialog records it as a checkout (CheckoutsStore, so the New PR panel pre-fills it), opens it in the system file manager and opens the repository panel. Materialization runs before any event is published, so a failure aborts creation cleanly with nothing announced. Two new signed_git tests (set_origin_creates_or_replaces_the_remote, working_copy_cloned_from_the_mirror_matches_head_and_origin).
• Add (after e2e, user request) — "ready to push" watch for the user's own repositories: local commits made in a checkout (external git) surface as a sidebar badge on the repository row (a CountBadge with the unpushed commit count) and, when the repository panel is open, as an info banner with a Push button. The CheckoutsStore gains a second status family (request_push_statuses/ push_statuses_of): per checked-out branch it refreshes the remote view (git fetch of the checkout's origin, offline-tolerant) and counts origin/<branch>..<branch> (origin/HEAD for branches the remote does not have yet); dirty/detached checkouts are skipped like the PR suggestions. Poll cadence: 15 s while a repository panel is open (status_requested), 60 s for the sidebar-only background watch; request sets are cleared on signer change. The repo panel's ready-to-contribute banner now applies only to repositories of other authors — owned repositories get the push banner instead, whose Push action calls the new Backend::push_checkout (shared body with the existing mirror-based push_repository): publishes a fresh 30618 state event (keeping the announced HEAD branch when the checkout is on a side branch) then pushes every branch and tag to the announced grasp servers. New test checkout_push_status_counts_unpushed_commits_only. The mirror's file browser stays a snapshot (new commits appear after a branch switch), like the rest of the browser.
• Fix (after e2e, user report) — a push warning "cannot lock ref 'refs/heads/main': is at X but expected Y" (server-side compare-and- swap rejection, incorrect old value provided). Reproduced locally: two concurrent plain pushes of the same ref from the same base make the loser fail exactly this way — the app can race itself when two push sources for one repository run at once (two panels of the same repo, or the banner Push racing the header's Republish; each guard was per-view only). Fix: pushes are now single-flight per repository in Backend::push_repo_from via an Arc<Mutex<HashSet<RepoAddr>>> guard (PushGuard, RAII: the lock is released on completion, on error and on task cancellation alike); a second concurrent push fails fast with "A push to this repository is already in progress" instead of racing. Racing an external git push against the same server remains possible (benign: the ref converges; the loser logs a warning only).
• Fix (after e2e, user report) — after a successful push the repository panel's commit list stayed on the old commit (even across restarts): the browser reads the GitCache mirror, and a fetch never moves a mirror's local branches — origin/main advanced while local main (what the commit list walks) stayed behind. ngit/nak never hit this because they operate on real clones the user git pulls; nak also publishes the updated 30618 state before each push, which Signed already did. Fixes, mirroring a git pull --ff-only on the browser clone: new signed_git::fast_forward_branches(workdir) (per local branch, when it is an ancestor of its refs/remotes/origin/* counterpart: the checked-out branch is merged so its worktree follows, dirty worktrees and local-only commits are never touched; returns whether anything moved); RepoDetailView::load_repo's background refresh fast-forwards after fetch_all and rebuilds the explorer, previews and commit list (reload_worktree) when anything moved; push_unpushed_checkout reloads the mirror on success so an owned repo's pushed commit appears immediately; ensure_origin now also configures the standard remote.origin.fetch refspec (create-flow mirrors otherwise never map heads on fetch). New test fast_forward_branches_moves_the_mirror_and_keeps_local_work; the remote-only-branch limitation stays (a branch the mirror has never checked out is not listed), as documented.