Skip to content

feat(external-work): add contribution interface - #1688

Merged
joryirving merged 7 commits into
mainfrom
courier/misospace/dispatch/issue-1539
Nov 22, 2026
Merged

joryirving merged 7 commits into
mainfrom
courier/misospace/dispatch/issue-1539

Conversation

@itsmiso-ai

@itsmiso-ai itsmiso-ai commented Nov 21, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Adds the operator browser surface for external contribution requests (#1539): a Contributions nav entry and /contributions page that renders the Courier admission config (endpoint presence, approved namespaces, and credential presence only — never the endpoint URL or any credential value), a submission form that holds one client-generated idempotency key per form session, the stored-request queue with delivery + lifecycle state, a bounded "Refresh tracking" action, and a durable "Retry delivery" action that replays an unsettled request's recorded idempotency key from the ledger row — across a page reload, and across a Dispatch crash that leaves a recoverable in_flight row.

It is a pure consumer of the four /api/external-contributions routes — POST /api/external-contributions, GET /api/external-contributions, GET /api/external-contributions/[id] and POST /api/external-contributions/[id]/refresh — plus the shared projection in external-contribution-view.ts. No new write path, no new authority, no second state machine. An unconfigured surface still renders: the config panel names the exact missing piece (DISPATCH_COURIER_ADMISSION_URL / _TOKEN / _NAMESPACES / DISPATCH_COURIER_READ_TOKEN) and the form disables itself, so a half-configured instance is an explanation, not a wall of controls that can only fail. The page is nav-present on every instance — the nav entry is not a secret, the auth gate is.

Invariants this change must keep, and every path that enforces them

  1. Namespace is the only privileged choice, and it is select-only. Only POST /api/external-contributions accepts namespace, and it validates against config.namespaces (src/app/api/external-contributions/route.ts); the endpoint is never client-selectable. The UI renders the list as a <select> from projectCourierSurface().namespaces, so the client offers nothing outside the list.
  2. The UI's namespace list is the same implementation the server gates on. external-contribution-view.ts parses DISPATCH_COURIER_ADMISSION_NAMESPACES with parseDelimitedList from @/lib/config-parsers — re-exported at src/lib/config.ts, which is where courier-admission.ts imports it. One parser, so no UI option the server can reject. Kept by src/lib/config-parsers.ts being Prisma-free (client-safe) and the single source for both sides.
  3. Lane is bounded free text, never a lane-privilege input; the client mirrors the server's shape rules only. parseContributionInput (src/lib/external-contribution.ts) requires lane non-empty, ≤64 chars, no control characters, and relays it verbatim — Dispatch never interprets lane. validateForm mirrors those same bounds, and both sides call one shared hasControlChars (src/lib/config-parsers.ts). The UI constrains lane's SHAPE, never its VALUE; Courier owns lane semantics.
  4. Nothing on this surface invents execution, publication, or their absence. Delivery state is the ledger's deliveryStatus (pending | in_flight | accepted | rejected | uncertain), surfaced only through the single shared projection projectExternalContribution used by every route (POST, stored reads, refresh), so no route can drift — and the client's row type is now derived from that projection (ExternalContributionWire, the projection's JSON form) instead of a hand-written mirror, so a server-side shape change cannot silently diverge from what the browser assumes. The Courier run identity is shown as admission proof only; lifecycle state (including expired) is derived only from feat(external-work): track Courier lifecycle #1538 tracking evidence via projectTracking. The retry notice distinguishes only what the wire proves: a 201 answer says Courier created the run; any other 2xx answer says the identity is settled and the retry "created nothing new" — and because the 200 answer covers BOTH a genuine resume and a replay of an already-settled identity with no per-call marker (route.ts maps resumed and replay_accepted to the same 200), a recorded resume is stated as a fact of the identity, never credited to the click.
  5. No secrets and no transport endpoint cross this surface. projectCourierSurface() returns endpointConfigured / credential booleans and named reasons only. The admission endpoint URL is deliberately not part of the view: getCourierAdmissionConfig validates scheme/host but not userinfo or query, so an operator URL may legally carry a credential (https://user:pass@host/...?token=***, and feat(external-work): add contribution interface #1539 forbids placing arbitrary admission endpoints in browser state. The only remaining consumer of admission.endpoint is the server-side fetch client (courier-admission.ts). The other writer of the same rule — the API's 503 reasons and tracking diagnostics — names env vars and redacts the bearer token; no client path serializes any of it.
  6. Auth has no special path. /api/external-contributions* is absent from WORKER_ALLOWLIST (src/lib/auth.ts), so worker-tier bearer tokens get 403 and every caller goes through authorizeRequest like the rest of the API. The server-rendered /contributions page is guarded by the global middleware (src/middleware.ts): its matcher covers all non-public routes, Basic Auth guards page routes, Bearer passes only /api/*, and OIDC redirects unauthenticated page renders to /login. disabled and legacy (unset) are instance-wide posture choices, identical for /board, /agents, and /projects — the config panel's names/booleans inherit exactly that posture and nothing looser (also stated in page.tsx and docs/external-contributions.md).
  7. Exactly-once identity discipline stays with the ledger; the UI replays it, never forks it. The form keeps the key across in-flight/uncertain answers and rotates only on a settled answer. The durable half lives in the ledger row: "Retry delivery" is offered for every unsettled row inside the attempt budget — pending, uncertain, AND in_flight — and rebuilds the canonical POST from the row's stored fields + recorded idempotencyKey, so a retry after a reload replays the SAME identity (the acceptance case that failed at ec10cc8). The in_flight case is the crash-recovery path of the feat(external-work): persist and submit requests #1537 state machine: the atomic claim re-accepts a same-identity POST once the row's inFlightUntil lease expires, and while the lease is still live that POST is answered in_flight with no second Courier call and no consumed attempt — so the affordance can never fork a delivery, and hiding it would strand a recoverable row (the blocker filed at ad5b701). The one claim-adjacent case left un-offered (attempt budget spent with a live final attempt) can only be answered in_flight / retry_exhausted, so a click there would be a provable no-op. While any unsettled retryable row exists, the submission form says so and points at the stored request's retry: the form always carries a fresh identity, so it is for deliberately new work only, never for repeating an unsettled one. The same rule is enforced by, and kept safe against, every other writer of this state: the atomic conditional-claim updateMany in submitExternalContribution (two concurrent retries collapse — the loser gets in_flight with no network call), the payload-digest guard (classifyExisting answers 409 payload_conflict before any attempt if a rebuilt body ever mismatched), and MAX_DELIVERY_ATTEMPTS (which now reaches the UI only through projectCourierSurface().maxDeliveryAttempts — one source, also enforcing the claim bound and the retry_exhausted answer). A deliberately new contribution remains a fresh form submission with a fresh key.
  8. Outbound links require a parsed http(s) URL. PrLink renders an href only when isHttpUrl (WHATWG new URL, protocol http:/https:) accepts Courier's recorded tracking.publication.pr; anything else stays visible as text, never an href — the same gate now shared by the upstream-issue link (isHttpUrl in contributions-client.tsx). Provenance is not scheme safety; the upstream-issue text is stored verbatim and relayed to Courier by parseContributionInput, which never dereferences it.
  9. The listing is a bounded ledger read and says so. The page requests the API's widest single page (?limit=200, the shared bound EXTERNAL_CONTRIBUTION_LIST_MAX_LIMIT in src/lib/external-contribution-list.ts, which the route validator enforces and the page imports — one source, no drift) and renders a visible note when the ledger is that wide; older stored requests remain readable through the same API. The listing still performs no Courier call and re-submits nothing.

docs/external-contributions.md carries the operator-facing copy of these rules; AGENTS.md's Subsystem Map row lists app/contributions/ as a consumer of the four routes.

Test plan

  • Full local Vitest suite (cwd /workspace): 7702 passed / 68 skipped / 1 todo, 0 failed (279 files; skipped are environment-gated suites). The final comment-only edits were re-validated with lint, typecheck, and the client suite.
  • npm run lint (--max-warnings=0) and npm run typecheck clean
  • contributions-client.test.tsx — 23 tests, incl.: a 401/403 list response surfaces the failed-read honestly; an invalid owner/repo value is rejected client-side with no POST; reload/remount retry replays the recorded idempotency key with the canonical body and exactly one POST (no forked identity); retry on an already-settled identity says "created nothing new"; a retry replaying an identity whose original admission was a resume never says "Re-delivered" (regression for the 200-resume-vs-replay mislabel); a crashed in_flight row offers Retry delivery and replays the recorded key + canonical body with exactly one POST (regression for the stranded-recovery blocker); a live-lease in-flight retry says the attempt is already running and started no second one; no retry affordance on an in_flight row at budget; the form names the durable retry path while unsettled rows exist; the listing requests limit=200 and flags the cap when the ledger is wider; retry not offered once the attempt budget is spent; attempt bound rendered from config, not a client constant; non-http(s) recorded PR renders as text with no javascript: href; config panel asserts the endpoint URL never appears in the DOM
  • external-contribution-view.test.ts — 6 tests, incl. a userinfo/token-bearing DISPATCH_COURIER_ADMISSION_URL proving nothing of the URL serializes into the surface view, and the nullable-wire pin (WireValue nullability)
  • The POST/GET/refresh route suites green (route.test.ts re-run at this head — the listing-cap refactor is behavior-preserving)
  • src/app/layout.test.tsx covers the nav link

Review follow-up (round 3, commit 4dfc342)

Independent review (ec10cc8, REQUEST_CHANGES) — all three findings acted:

  1. Blocking: reload broke the exactly-once retry identity. Fixed with the durable "Retry delivery" action (invariant 7) + the reload/remount regression named above. Chosen shape: retry from the stored row (the ledger is the durable identity); the form-session key stays as the within-session path.
  2. Blocking: full admission endpoint in browser state. CourierSurfaceView now carries endpointConfigured: boolean only (invariant 5); the URL string no longer crosses the boundary in any mode. Endpoint-URL sanitization at the config resolver (userinfo/query rejection) is not added here — with the URL out of every client projection the remaining exposure is the server-side fetch itself, tracked as a follow-up (see Handoff).
  3. Link safety: PrLink href unvalidated. http(s)-only parse gate with a hostile-scheme regression; the upstream-issue link shares the gate (invariant 8).

AI-review nits at ec10cc8: hardcoded "of 5" → server constant via the surface view; hand-written ContributionRow mirror → derived ExternalContributionWire; this body's test counts and endpoint claims corrected.

Handoff (coordinator run 6, commit ad5b701)

Scope: head 13f56ee had been AI-APPROVED with two minor + two info findings; all older threads resolved. ad5b701 acts on all four:

  1. Minor (bug): resumed-replay mislabel. The retry's 200-resumed branch credited the click ("Re-delivered … Courier resumed run") even when the response was a no-op replay of an already-resumed identity — indistinguishable on the wire (route.ts answers 200 identically for resumed and replay_accepted). The two 200 branches are merged into one neutral notice that states the settled identity, states a recorded resume as a fact of the identity, and claims only "created nothing new"; tone is info, not success, because nothing in the answer is provably a delivery by this click. 201 and in_flight branches untouched. Regression test asserts "Re-delivered" is absent for the resumed-replay shape. (Invariant 4 restated above accordingly.)
  2. Minor (docs): AGENTS.md Subsystem Map. Row now lists app/contributions/ (operator UI page + client, feat(external-work): add contribution interface #1539) as a consumer of the four routes.
  3. Info: 50-row listing ceiling. The page fetches ?limit=200 (the API's own LIST_MAX_LIMIT) and renders a visible cap note at 200 rows, pointing at the API for older entries. Docs updated. (Superseded by run 7: the bound is now a shared constant.)
  4. Info: legacy-mode page exposure. No code change: with DISPATCH_AUTH_MODE unset or disabled the middleware enforces no page auth on ANY route — an explicit instance-wide posture identical to /board /agents /projects, verified against src/middleware.ts. The page's docstring and invariant 6 now state this explicitly. Request data itself still requires maintainer-tier auth on every route.

Handoff (coordinator run 7, commit 9101401)

Scope: the independent re-review at ad5b701 (CHANGES_REQUESTED) filed one blocker plus a secondary copy ask; the AI review at ad5b701 APPROVED with one open info nit. All acted:

  1. Blocking: a crashed in_flight row was unrecoverable from the UI. The server's atomic claim explicitly re-accepts a same-identity POST once the row's inFlightUntil lease expires, and reports live-lease attempts as in_flight with zero Courier calls (src/lib/external-contribution.ts, claim updateMany + the live-attempt rule) — but the client excluded in_flight from retryable, so after crash + reload the recoverable row sat stranded while a fresh form submission could only fork a new identity. retryable now covers pending / uncertain / in_flight inside the attempt budget (invariant 7); the retry handler already replayed row.idempotencyKey and already ordered its in_flight answer ahead of the 2xx delivery branches, so a live-lease click is honestly reported as "already running". Regressions: crashed-in_flight replay asserts the recorded key + canonical body with exactly one POST; live-lease asserts the already-running notice; no affordance at budget spent. The server-side reclaim semantics were already pinned (external-contribution.test.ts: stale-lease recovery reuses the key for exactly one extra attempt; never recovers past budget; live final attempt reports in-flight). Docs updated.
  2. Secondary copy ask (same review). The submission form now shows the unsettled count and points at "Retry delivery" whenever retryable unsettled rows exist. Deliberately not a hard disable: the form can never repeat-submit an identity (it always holds a fresh key), and blanket-blocking would make legitimate new contributions impossible while an unsettled row can sit for hours — the notice names the durable path without adding a gate.
  3. AI info nit: mirrored listing cap. The client's LIST_FETCH_LIMIT = 200 and the route's LIST_MAX_LIMIT are now one constant: EXTERNAL_CONTRIBUTION_LIST_MAX_LIMIT in the new dependency-free src/lib/external-contribution-list.ts, imported by both (invariant 9). Nothing server-side is dragged into the browser bundle; the route's default (50), cap, and 400 message are byte-identical.

Local validation receipts (cwd /workspace, worktree at 9101401): vitest run src/app/contributions/contributions-client.test.tsx src/app/api/external-contributions/route.test.ts 46/46; full npm run test 7702 passed / 68 skipped / 1 todo, 0 failed; npm run lint (--max-warnings=0) PASS; npm run typecheck PASS. Independent bounded review of the delta (fresh session, verified against the server claim code): APPROVE; its two comment-accuracy minors (gate-congruence wording, the courierNamespace ?? namespace replay-safety note) are included in 9101401 and re-validated with lint + typecheck + the 23-test client suite. Limitations: next build not run locally (CI covers it); DB-backed suites follow the normal skip/CI pattern.

Remaining external verification: CI at 9101401 (pending at exit — not observed), AI re-review, and the independent reviewer's re-approval of the open CHANGES_REQUESTED state. The follow-up issue for the pre-existing lastError URL-echo surface stays open (not introduced here).

Add the operator surface over the #1537/#1538 external-contribution APIs:
a submission form holding one request identity per form session (uncertain
delivery retries replay the SAME idempotency key; a settled identity is
rotated so an edit is a deliberately new contribution), the stored-request
queue, one request's details, and a bounded tracking refresh. The
configuration panel shows endpoint, approved namespaces, and credential
presence via a new server-side projection - never credential values. The
shared response projection now also carries lane and goal so every surface
shows the recorded request.
its-saffron[bot]

This comment was marked as outdated.

… rules

Review follow-up on #1688. The form mirrored the submission validator's
bounds but not its control-character rule, so a pasted tab could pass the
client and earn a server 400. Move hasControlChars into the Prisma-free
config-parsers module - the same single implementation now runs in
parseContributionInput and in validateForm for lane, baseRef, and
upstreamIssue - so the two sides cannot drift, and the UI's only
privileged choice (namespace) stays select-only while lane remains
bounded free text relayed verbatim.

Document that the server-rendered /contributions page is guarded by the
global middleware (basic/oidc), like every other operator surface.
@itsmiso-ai

Copy link
Copy Markdown
Collaborator Author

Handoff (round 2, head ec10cc8)

Settled decisions: lane stays bounded free text by contract (Courier owns values; relayed verbatim) — invariant 3 in the body now says so precisely and the old "no lane-privilege input" overclaim is gone; shape rules (required, ≤64, no control chars) are enforced by ONE shared hasControlChars in src/lib/config-parsers.ts, called by the server validator and the form, so they cannot drift. Server-render auth for /contributions confirmed via the global middleware (documented in page.tsx). Parser identity confirmed (config.ts re-export → same function as courier-admission.ts); no change needed there.

Local checks on ec10cc8 (all run against the integrated worktree): lint clean, typecheck clean, npx vitest run 279 files / 7687 tests passed (0 failed; +4 tests this round), npm run build succeeds with /contributions dynamic. One bounded independent review over the delta: APPROVE (its wording nit was fixed before push).

External verification pending (not run locally): CI on ec10cc8 and thread resolution by the reviewer. No known unresolved validation failures.

its-saffron[bot]

This comment was marked as outdated.

@joryirving joryirving left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Independent review at ec10cc8: REQUEST_CHANGES.

I found two blocking correctness/security gaps that the automated review did not catch, plus one smaller link-safety gap.

  1. Blocking: reload breaks the exactly-once retry identity required by #1539. The form initializes idempotencyKey with useState(newClientKey) and keeps it only in React state. A 502/504 correctly retains that key within the current page session, but a browser reload loses it and creates a fresh key. The stored request list has no "retry this same delivery identity" action. So the acceptance case reload ... and retry after an uncertain response preserve the same request fails: after an uncertain admission, reloading and re-submitting the same work uses a different idempotency key, creates a second Dispatch ledger identity, and Courier can legitimately admit a second run because its dedupe key changed. This is exactly the fork the UI is supposed to prevent.

Please make retry-after-reload operate from durable identity. The cleanest shape is a retry action on an existing uncertain / recoverable stored row that rebuilds the canonical POST from that row and reuses its recorded idempotencyKey; persisting the active form identity across reload is also possible, but it must be tied safely to the same canonical payload. Add a reload/remount regression proving the retry sends the original key and does not create a new request identity.

  1. Blocking boundary violation: the full Courier admission endpoint is sent into browser state. #1539 explicitly says never place arbitrary admission endpoints in browser state, but projectCourierSurface() returns admission.endpoint.toString() and ConfigPanel renders it client-side. More importantly, getCourierAdmissionConfig() accepts any http(s) URL with a host and does not reject URL userinfo, query parameters, or fragments. An operator configuration such as https://user:pass@courier.internal/... or a URL with a token-like query therefore crosses the same browser boundary the PR claims can carry no credential. Do not serialize the full endpoint into the client projection. A simple endpointConfigured: boolean / named availability state is enough for this UI. If the endpoint must ever be displayed elsewhere, sanitize and validate it separately from the credential-bearing transport URL.

  2. Smaller but real safety gap: the authoritative PR value is not validated before becoming an outbound link. PrLink uses tracking.publication.pr directly as href, while parseContributionStatus() accepts any bounded non-empty string for publication.pr. "Authoritative tracking supplied it" establishes provenance, not URL safety. Restrict rendered PR links to a parsed http(s) URL (and render anything else as text/unavailable), with a hostile-scheme regression. The upstream-issue rendering already at least applies an http(s)-only link gate; the PR link should not be weaker.

The rest of the implementation looks good: namespace selection is fail-closed against the same parsed config as the server, lane shape validation now matches the server, maintainer auth remains on the existing middleware/API tier, delivery/tracking state remains ledger-owned, and exact-head Security Audit / CI / image build / smoke / AI review are all green. The branch is current with main (2 ahead / 0 behind).

The AI review's hard-coded of 5 and hand-written ContributionRow findings are maintainability nits, not blockers compared with the issues above.

…oint URL out of the browser

- "Retry delivery" on stored pending/uncertain rows rebuilds the canonical
  POST from the ledger row and replays its recorded idempotency key, so a
  retry after a reload never forks a second request identity (#1539)
- the surface view carries endpoint PRESENCE only; the credential-bearing
  admission URL (userinfo/query may hold secrets) never crosses into the
  client tree
- PR and upstream-issue links render only for parsed absolute http(s)
  URLs; any other recorded value stays visible as text, never an href
- the client derives its row type from the shared projection's wire type
  and reads the attempt bound from the server constant (no drift)
@itsmiso-ai

Copy link
Copy Markdown
Collaborator Author

Round 3 — all three review findings acted (4dfc342)

1. Blocking: reload broke the exactly-once retry identity. Stored rows with unsettled pending/uncertain delivery now offer Retry delivery, which rebuilds the canonical POST from the ledger row's own fields and replays the row's recorded idempotencyKey — so a retry after a reload reuses the SAME request identity instead of forking a second ledger row. Deliberately narrower than the server's claim (attempt-budget gate; expired-lease in_flight recovery stays a server concern), and kept safe by the existing atomic claim (concurrent retries collapse; the loser gets in_flight without a network call) and the payload-digest guard (a mismatching rebuild is 409 payload_conflict before any attempt). Regression: replays the durable identity from the stored row after a reload instead of forking a new one (unmount → fresh mount → exactly one POST, original key, canonical body).

2. Blocking: full admission endpoint in browser state. CourierSurfaceView carries endpointConfigured: boolean only; admission.endpoint.toString() no longer exists outside the server-side fetch client. Since getCourierAdmissionConfig accepts userinfo/query-bearing URLs, the URL was credential-bearing transport config and is now out of the client projection in every configuration (pinned by a https://user:pass@…?token=*** test on the view and a no-courier.internal DOM assertion in the client suite). Endpoint-URL validation at the config resolver is tracked separately as #1690 (pre-existing diagnostics-surface gap, not introduced here).

3. Link safety. PrLink renders an href only for a value parsing as an absolute http(s) URL (new URL + protocol check); any other recorded value renders as visible text — honesty without a hostile href. The upstream-issue link now shares the same isHttpUrl gate (it previously used a looser regex). Regression: renders a recorded non-http(s) PR value as text, never as an href.

Nits: attempt cap renders from MAX_DELIVERY_ATTEMPTS through the projection (maxDeliveryAttempts), no client constant; the hand-written ContributionRow mirror is gone — the client derives ExternalContributionWire from the shared projection; PR body test counts and endpoint claims corrected.

Independent review of this delta: GO; its minors are included (retry notice distinguishes delivered 201 / resumed / already-settled replay; retry hidden once attempts ≥ max).

Local receipts at 4dfc342 (cwd /workspace, after mise run bootstrap): npm run typecheck PASS · npm run lint (--max-warnings=0) PASS · full npm test: 7693 passed / 68 skipped / 1 todo, 0 failed. next build not run locally (CI covers it; no server-module value import added to the client). CI at ec10cc8 was green; CI at 4dfc342 pending — operator verifies after this run exits.

its-saffron[bot]

This comment was marked as outdated.

…ape rule

Closes the AI review's minor finding on 4dfc342: the client tests never
exercised a 401/403 listing response or an invalid owner/repo value in
validateForm.
@itsmiso-ai

Copy link
Copy Markdown
Collaborator Author

Round 4 handoff — 4dfc342 → c43a6f2

Scope settled this round: the only open finding at head 4dfc342 was the AI review's minor test-coverage item (approved recommendation, one minor): the client tests never exercised a 401/403 list response or an invalid owner/repo value in validateForm.

  • c43a6f2 adds both tests to src/app/contributions/contributions-client.test.tsx: a denied list read renders contribution listing failed: HTTP 401 / HTTP 403 honestly with no invented rows, and an invalid base/work repo value blocks submission with the server-mirrored shape message (no POST is issued).
  • The earlier AI findings (Lane free-text vs. select-only namespace, /contributions auth tier, parseDelimitedList sharing) stay resolved as replied; joryirving's three ec10cc8 blockers stay fixed by 4dfc342 (durable ledger-sourced retry, endpointConfigured boolean, http(s)-only PR link). No production code changed this round.

Local checks (actual head c43a6f2, clean tree):

  • npm run lint (eslint --max-warnings=0) — pass
  • npm run typecheck — pass
  • npm test (vitest, full suite) — 279 files, 7695 passed / 68 skipped / 1 todo

CI on this head was just triggered by the push and remains pending — not observed green. The independent review's CHANGES_REQUESTED state predates 4dfc342; re-approval is the reviewer's call. PR left open, non-draft, unmerged.

its-saffron[bot]

This comment was marked as outdated.

…utes

Review round on c43a6f2: WireValue's null fallthrough was verified sound
(strict is on; the naked conditional distributes and null maps to null),
so pin it with a compile-time regression assertion instead of changing
the helper. Correct the Operator UI section to name all four consumed
routes (POST submit plus the three stored-evidence routes).
@itsmiso-ai

Copy link
Copy Markdown
Collaborator Author

Round handoff (head 13f56ee)

This round's scope — the two unresolved review threads on c43a6f2:

  1. WireValue nullability (external-contribution-view.ts:56) — verified sound, pinned with a test. strict: true is set (tsconfig.json:6), and the naked conditional distributes, so null maps to null (not string) on every nullable wire field. A compile-time regression assertion now assigns null to all six nullable fields; mutation-checked (NonNullable<T> fallthrough → 6 TS2322 errors; shipped helper → clean).
  2. Docs route count (docs/external-contributions.md:276) — fixed: "four routes above — the POST /api/external-contributions submission route plus the three stored-evidence routes".

Carried context: the earlier blocking finding (idempotency key lost on reload, REQUEST_CHANGES at ec10cc8) was resolved in 4dfc342/c43a6f2: retry-after-reload rebuilds the canonical POST from the durable ledger row (Retry delivery on unsettled rows), the browser keeps only the form-session key, and the endpoint URL never enters the browser projection. The three earlier automated nits were resolved in previous rounds.

Local validation receipts (all at head 13f56ee, cwd /workspace):

  • npm run lint (eslint . --max-warnings=0) — pass
  • npm run typecheck (tsc --noEmit) — pass, plus the mutation check above
  • npm run test (vitest) — 293 files: 279 passed / 14 skipped; 7696 tests passed / 68 skipped / 1 todo, 47s

Invariants this change keeps (unchanged surfaces listed for the reviewer):

  • One shared projection (projectExternalContribution) for POST submit, GET listing, GET [id], and POST [id]/refresh — this round changed no projection code, only a type-level test pinning its nullability.
  • No credential or endpoint URL in the browser tree (projectCourierSurface presence-only) — untouched; existing tests assert it.
  • Exactly-once delivery identity: form-session key in React state, durable identity in the ledger row with Retry-delivery replay — untouched this round.
  • Docs-only fix aligns the Operator UI section with the four routes the PR body claims; no other doc or code path restates the route count.

Remaining external verification: CI on 13f56ee was pending at push time (no check runs reported yet) — explicitly pending, not claimed green.

its-saffron[bot]

This comment was marked as outdated.

…n the listing page

- merge the retry's resumed/replayed 200 branches: the wire carries no
  per-call marker, so the notice states the settled identity and the
  recorded resume without claiming this click delivered anything
- fetch the listing at the API's page cap (?limit=200) and say so when
  the ledger is wider
- AGENTS.md subsystem map gains the app/contributions/ operator surface
@itsmiso-ai

Copy link
Copy Markdown
Collaborator Author

Coordinator handoff (run 6, head ad5b701). All four findings on the APPROVED review at 13f56ee are acted: (1) the retry's 200 answer no longer credits the click — a recorded resume is stated as a fact of the identity, since 200 cannot distinguish genuine resume from replay (route.ts maps both to the same answer), with a regression test asserting "Re-delivered" never appears on the resumed-replay shape, notice tone info not success; (2) AGENTS.md Subsystem Map now lists app/contributions/ (#1539) as a consumer of the four routes; (3) the listing fetches the API's page cap (?limit=200 = LIST_MAX_LIMIT) and shows a cap note pointing at the API for older rows when the ledger is wider; (4) the legacy-mode page-exposure info gets no code change — verified against src/middleware.ts: with DISPATCH_AUTH_MODE unset or disabled no route has page auth, an instance-wide posture identical to /board /agents /projects; the page docstring, docs, and PR-body invariant 6 now state it, and all request data still requires maintainer-tier auth per route.

Local validation at ad5b701 (cwd /workspace): vitest src/app/contributions/ 19/19 · npm run lint PASS · npm run typecheck PASS · full npm run test 7698 pass / 0 fail. Independent bounded review of the delta: APPROVE; both non-blocking nits (tone, docs indentation) folded into the commit. CI at ad5b701 explicitly pending at exit, not observed. Still open externally: the reviewer's CHANGES_REQUESTED state predates 4dfc342; the durable retry identity, endpoint-out-of-browser, and http(s) link gate are all in at this head for their re-check.

@joryirving joryirving left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Independent re-review at ad5b701: REQUEST_CHANGES.

The three findings from my prior review are fixed on this head:

  • reload/remount retry for a stored pending / uncertain request rebuilds the canonical POST from the durable ledger row and reuses that row's recorded idempotencyKey;
  • the admission endpoint URL no longer crosses into browser state (projectCourierSurface exposes presence only);
  • PR and upstream-issue links now require a parsed absolute http(s) URL before becoming an href.

I found one remaining blocker in the same exactly-once/reload recovery contract:

A Dispatch crash after the atomic delivery claim leaves a recoverable in_flight row that the UI cannot recover.

The server state machine explicitly supports this case. submitExternalContribution may reclaim an in_flight row once its inFlightUntil lease expires, using the SAME persisted idempotency key and payload. That is the restart/recovery path for a process that dies after claiming the attempt but before settling it to accepted, rejected, or uncertain.

But the browser deliberately excludes in_flight from retryable:

const retryable =
  (row.status === "uncertain" || row.status === "pending") &&
  row.attempts < config.maxDeliveryAttempts;

The comment even notes that a crashed in_flight row remains recoverable only through a deliberate resubmission of the same identity. The problem is that after the reload which follows that crash, the form has generated a fresh client key and exposes no way to resubmit the old identity. So the durable row is visible but stranded in the UI. Re-entering the same work through the form can create a new request identity, exactly the fork #1539's "reload ... preserve the same request" acceptance is trying to prevent.

This path is not hypothetical state-machine trivia: the row is created, then atomically flipped to in_flight before the Courier network call. A process/pod death in that window is precisely why the server carries inFlightUntil recovery semantics.

Please make the durable retry affordance cover the recoverable in_flight state as well. The simplest safe shape is to allow "Retry delivery" for in_flight rows inside the attempt budget: while the lease is still live the server already returns in_flight with zero second network call; once the lease expires the same POST can reclaim it atomically. If you prefer to expose the lease and only enable after expiry, that also works, but it is more UI/state plumbing.

Add a regression that mounts a stored in_flight row, invokes Retry delivery, and proves:

  1. the recorded idempotency key/canonical body are reused;
  2. a live lease answers as already in flight without forking;
  3. after the server-side lease is recoverable, the same identity is the one re-attempted.

I would also align the page copy with #1539's "disable repeat submission while pending / deliberate new work is a separate explicit action" intent once this is fixed; right now the fresh submission form remains available alongside unsettled rows. I am treating that as secondary to the concrete stranded-in_flight recovery bug above.

Everything else I rechecked looks good: namespace fencing still uses the same parser/config as the server, lane/repo shape validation is mirrored, request data stays maintainer-tier, delivery/tracking remain ledger-owned, max attempts come from the server projection, and the latest listing/link/config changes are bounded and honest.

Exact-head Security Audit, CI, image build, and PR smoke are green. The exact-head AI review is still in progress at the time of this review. Branch is mergeable and current with main (6 ahead / 0 behind).

its-saffron[bot]

This comment was marked as outdated.

…e retry

The server's atomic claim re-accepts a same-identity POST once an
in_flight lease expires, but the UI excluded in_flight from its retry
gate, stranding the recoverable row after a crash + reload while a
fresh form submission forked a new identity. Offer Retry delivery for
in_flight rows inside the attempt budget, name the durable retry path
on the form while unsettled rows exist, and share the listing page cap
with the route instead of mirroring it.
@itsmiso-ai

Copy link
Copy Markdown
Collaborator Author

Coordinator handoff (run 7, head 9101401) — the ad5b701 re-review's blocker is fixed.

Stranded in_flight recovery. retryable now covers pending / uncertain / in_flight inside the attempt budget, matching the server's atomic claim (verified against src/lib/external-contribution.ts before acting): a live-lease replay is answered in_flight with no second Courier call and no consumed attempt; an expired lease re-claims under the SAME recorded key + payload. The one un-offered claim-adjacent case (budget spent with a live final attempt) can only answer in_flight/retry_exhausted — a provable no-op. Regressions added in contributions-client.test.tsx: crashed-row replay asserts the recorded key-1 + canonical body with exactly one POST; live-lease asserts the "already running … did not start a second one" notice; no affordance at budget spent. Server-side reclaim was already pinned (external-contribution.test.ts — stale-lease same-key recovery consumes exactly one extra attempt; never past budget; live final attempt reports in-flight).

Secondary copy ask. The form now names the unsettled count and points at "Retry delivery" while retryable rows exist. Not a hard disable — the form always holds a fresh key and can never repeat-submit, and blocking new work while an unsettled row ages would hurt legitimate use; the notice names the durable path instead.

Open AI nit. The mirrored 200 is now the shared EXTERNAL_CONTRIBUTION_LIST_MAX_LIMIT in src/lib/external-contribution-list.ts, imported by the route and the page (replied on the thread).

Local receipts (cwd /workspace, worktree 9101401): targeted vitest 46/46; full suite 7702 passed / 68 skipped / 1 todo, 0 failed; npm run lint (--max-warnings=0) PASS; npm run typecheck PASS. Independent bounded review of the delta: APPROVE, both comment-accuracy minors folded into the commit and re-validated (lint/typecheck/23-test client suite). Limitation: next build not run locally; CI covers it.

Pending externally at exit: CI on 9101401 (explicitly pending, not observed green beyond the prior head), AI re-review, and re-approval lifting the CHANGES_REQUESTED state. PR body updated with the corrected invariants (7 and 9) and this run's handoff; no new authority, write path, or state machine was introduced.

@its-saffron its-saffron Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

{"schema":"review-handoff/v1","review_id":"19a0292efcfaf908","head_sha":"910140159759624e827e3335ca14bc12a7abfa64","verdict":"approve","review_result":"clean","required_checks":"none","items":[],"items_total":0,"items_truncated":false,"unresolved_requirement_ids":[],"unresolved_requirement_ids_total":0,"unresolved_requirement_ids_truncated":false,"unresolved_requirement_ids_source_total":0,"unresolved_required_checks":[],"unresolved_required_checks_total":0,"unresolved_required_checks_truncated":false,"unresolved_required_checks_source_total":0,"unresolved_review_obligations":[],"unresolved_review_obligations_total":0,"unresolved_review_obligations_truncated":false,"derived_obligation_state":null}

AI Automated Review

✅ Automated recommendation: APPROVE

Full PR review.

Analysis engine: MiniMax-M3.1-Flash (anthropic) — primary route · pr-reviewer-action v3.10.0

Approve: the current head resolves the durable-retry blocker and introduces no remaining blocking or major findings.

  • Claims 1–4 held across 4/4 visible items: the page is a consumer of the four existing routes, configuration projection exposes presence only, namespaces remain select-only and server-gated, and lane validation uses shared client-safe rules. The omitted fifth claim remains unverified because its text was not included in the corpus.
  • Human request 6009744491 is addressed: in_flight rows remain retryable within the attempt budget, and the replay reuses the ledger row’s recorded identity and canonical payload.

Tool Harness Findings

Relevant source reads confirmed the durable replay uses the persisted idempotency key and payload, the server atomically recovers expired in_flight leases, and API routes retain maintainer-tier authorization; shared listing limits are dependency-free and imported by both route and browser.

Unknowns or Needs Verification

The tool investigation stopped before all 34 planned requests completed, and no linked issue body was supplied, so the exact PR 1539 issue acceptance list could not be independently compared beyond the current PR description.

Outstanding Human Change Requests

  • @​joryirving's change request (ad5b701, head moved since) judged addressed at this head: The current client now includes `in_flight` in its unsettled/retryable states and replays the stored row’s recorded key and canonical fields in `src/app/contributions/contributions-client.tsx:+1-903`; `src/app/contributions/contributions-client.test.tsx:+1-637` includes coverage for recovering a cr…

@joryirving joryirving left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Independent re-review at 9101401: APPROVE.

The remaining blocker from review 6009744491 is fixed.

The durable retry affordance now covers every unsettled row the server can actually reclaim inside the attempt budget, including in_flight. That matches the existing server state machine: a replay while the lease is still live returns in_flight without a second Courier call or another consumed attempt; after the lease expires, the same persisted idempotency key + canonical payload can atomically reclaim the row for one bounded retry. The browser therefore no longer strands the exact crash window where Dispatch dies after the claim and before settlement.

The new client regressions cover both sides of that behavior: the crashed-row path replays the stored key/canonical body, and the live-lease path reports the existing attempt rather than claiming a new delivery. The attempt-budget guard remains consistent with the server.

I also checked the small list-limit cleanup. EXTERNAL_CONTRIBUTION_LIST_MAX_LIMIT now lives in a dependency-free shared module imported by both the API route and the client, eliminating the previous hardcoded 200 mirror without pulling server-only dependencies into the browser bundle.

One non-blocking wording/UX nit remains: the new unsettled-work notice says "This form always starts a NEW request", but within the same browser session after an in_flight or uncertain response the form intentionally retains its existing idempotency key, so resubmitting that same form replays the existing identity. The smaller help text below the button correctly says this. Also, #1539 says "disable repeat submission while pending", while the button remains enabled and relies on server idempotency for correctness. I am not holding the PR for that because the exactly-once behavior is safe and I previously treated this as secondary UX polish, but the copy should be tightened in a follow-up so the page does not contradict itself.

The prior endpoint-browser-state and outbound-link-scheme findings remain fixed.

Exact-head Security Audit, CI, image build, PR smoke, and AI review are all green. The branch is mergeable and current with main (7 ahead / 0 behind).

@joryirving
joryirving merged commit 434723e into main Nov 22, 2026
15 checks passed
@joryirving
joryirving deleted the courier/misospace/dispatch/issue-1539 branch November 22, 2026 03:41
@its-miso its-miso Bot mentioned this pull request Nov 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants