GET /api/v1/repos/:owner/:name/pulls/:number/looks lists a pull's looks, with its row in the OpenAPI contract #8435

GET /api/v1/repos/:owner/:name/pulls/:number/looks now answers { items: [{ id, width, says, by, commit, url, at }] }, newest first. These checks pass:

• bun x tsc --noEmit
• bun scripts/gate.ts
• test/openapi-coverage.test.ts, test/openapi-routes.test.ts and test/openapi-oa-pull-review.test.ts
• the new test/pull-looks.test.ts
• test/mcp-size.test.ts

I did not run the full suite. The forge runs it on the push.

• Route: it sits beside the POST in src/http/api.ts. It reads the pull's own preview environment through looksForEnv, so another app's looks never appear. url is built with lookUrl exactly as the POST builds it.
• Access: loadPull gives a reader who may not read the repository a 404. A pull with no app, or no looks, answers items: [].
• Contract: the new row is getApiV1ReposOwnerNamePullsNumberLooks.ts, and I regenerated the route index with bun scripts/openapi-routes.ts.
• Old test changed: test/openapi-oa-pull-review.test.ts asserted the GET was undefined. That described the old world, so it now expects the row.
• Tests: test/pull-looks.test.ts covers an empty list for a pull with no app, and a look attached through the POST being listed by the GET. It also checks that an outsider and an anonymous caller get 404 on a private repository.

I added one filter you didn't ask for. The list is limited to looks the reader may fetch as pictures (mayFetchLook from src/web/pages/looks.ts, imported into api.ts). Errored looks and the owner-only looks are left out for non-writers, as on the pull page, so the API does not show what the page hides.

I did not add an MCP read, since attach_look is the only MCP look tool and I left the tool surface alone. To try it, attach a look with the POST, then curl -H "authorization: Bearer $TOKEN" $FORGE_URL/api/v1/repos/<owner>/<name>/pulls/<n>/looks.

Closes #8424

GET /api/v1/repos/:owner/:name/pulls/:number/looks now answers { items: [{ id, width, says, by, commit, url, at }] }, newest first. These checks pass:

• bun x tsc --noEmit
• bun scripts/gate.ts
• test/openapi-coverage.test.ts, test/openapi-routes.test.ts and test/openapi-oa-pull-review.test.ts
• the new test/pull-looks.test.ts
• test/mcp-size.test.ts

I did not run the full suite. The forge runs it on the push.

• Route: it sits beside the POST in src/http/api.ts. It reads the pull's own preview environment through looksForEnv, so another app's looks never appear. url is built with lookUrl exactly as the POST builds it.
• Access: loadPull gives a reader who may not read the repository a 404. A pull with no app, or no looks, answers items: [].
• Contract: the new row is getApiV1ReposOwnerNamePullsNumberLooks.ts, and I regenerated the route index with bun scripts/openapi-routes.ts.
• Old test changed: test/openapi-oa-pull-review.test.ts asserted the GET was undefined. That described the old world, so it now expects the row.
• Tests: test/pull-looks.test.ts covers an empty list for a pull with no app, and a look attached through the POST being listed by the GET. It also checks that an outsider and an anonymous caller get 404 on a private repository.

I added one filter you didn't ask for. The list is limited to looks the reader may fetch as pictures (mayFetchLook from src/web/pages/looks.ts, imported into api.ts). Errored looks and the owner-only looks are left out for non-writers, as on the pull page, so the API does not show what the page hides.

I did not add an MCP read, since attach_look is the only MCP look tool and I left the tool surface alone. To try it, attach a look with the POST, then curl -H "authorization: Bearer $TOKEN" $FORGE_URL/api/v1/repos/<owner>/<name>/pulls/<n>/looks.

I've pushed the changes for all five of sentinel's points. The local run was green except test/looks.test.ts, whose three capture tests need Chromium and fail in this sandbox ("socket() failed: Operation not permitted"). scripts/fast.ts named 1265 of 1898 test files, so I ran the ones that cover this change instead of that set.

What changed

• Layering: mayFetchLook now lives in src/looks/readable.ts, taking (app, repo, record, look, user). src/web/pages/looks.ts keeps a thin wrapper, so the pictures route and the studio feed are unchanged. src/http/api.ts no longer imports a page module.
• Shared list: the same file has pullLooks(app, repo, pull, user), which holds the scoping to the pull's own preview environment and the gating. The API route is now a one-line call to it.
• MCP: the pull tool answers a looks array with the same items as the GET. I added it to the answer rather than adding a tool or an argument, so tools/list is unchanged and test/mcp-size.test.ts passes without touching the ceilings.
• Terminal: I on a pull in an app repository opens src/tui/screens/pulllooks.ts, which lists the looks. L was already "land past the gate", so I used I.
• Docs: docs/features/pull-looks.md is new, and the README is untouched.
• Tests: test/pull-looks.test.ts now also covers:

- an errored look is omitted; - an owner-taken look is omitted for a non-writer, though a writer sees it; - another pull's look is omitted, and that pull lists its own; - a private app's look is hidden from an unnamed reader; - a public repository answers a guest; - a nonexistent pull number answers 404; - MCP pull and the terminal screen show the same lists, gated the same.

• Earlier test change: test/openapi-oa-pull-review.test.ts asserted the GET was undefined and now expects it to be defined. That test described the old world.

On the direction point: I agree the repo is pipeline-first and kept this small. It goes ahead of the pipeline items because #7915 has failed twice (pulls #8227, #8411) and an agent has no way to read back a look it attached, which keeps the attach-then-verify loop open.

Not done

• The terminal screen has no key to open a picture, because the terminal can't draw one.
• The terminal screen has no test for the I key itself. The test pushes the screen directly.

I merged main into this branch and pushed it. The merge had one conflict, in src/http/mcp/tools/pull.ts.

Why it conflicted: main had added a looks field to the MCP pull tool, built inline for writers. This branch builds the same field with the shared pullLooks helper in src/looks/readable.ts. The merge kept both, so the result had the field twice.

Resolution: I kept pullLooks, so the MCP tool, the /looks API route and the terminal all filter looks the same way. I removed the inline copy and the imports it needed. The tool's doc text is this branch's version. main and this branch return the same fields, { id, width, says, by, commit, url, at }, so the output shape doesn't change.

Checks:

• bun x tsc --noEmit is clean.
• scripts/gate.ts printed nothing, which I read as passing but did not confirm with an exit code.
• 13 tests pass across test/attach-look.test.ts and test/pull-looks.test.ts.
• 776 tests pass across the test/mcp*.test.ts files and test/oauth-refresh.test.ts.
• scripts/fast.ts called the diff too broad to name tests, so I picked these myself. I did not run the full suite, which the forge's check runs on the push.
• The sandbox reported denied connections to a localhost port during the MCP test run. No test failed.

Left #8424 open: 5 unticked items remain (GET /api/v1/repos/:owner/:name/pulls/:number/looks answers { items: [{ id, width, says, by, commit, url, at }] }, newest first, from the pull's preview environment (looksForEnv in src/core/looks.ts), url built with lookUrl as the POST answers it.; Repository read access, the rule src/web/pages/looks.ts uses for the pictures: a reader who may not read the repository gets 404. A pull with no app or no looks answers items: [].; Its OpenAPI row: src/contract/openapi/routes/getApiV1ReposOwnerNamePullsNumberLooks.ts, then bun scripts/openapi-routes.ts to regenerate the index. test/openapi-oa-pull-review.test.ts currently asserts the GET is undefined: change that assertion to expect the row, and say so in the pull (the test described the old world).; …).