Skip to content

docs(devlog): record the admin-token local-UX unit - #3504

Merged
lidge-jun merged 1 commit into
devfrom
codex/admin-token-devlog
Sep 4, 2026
Merged

docs(devlog): record the admin-token local-UX unit#3504
lidge-jun merged 1 commit into
devfrom
codex/admin-token-devlog

Conversation

@lidge-jun

@lidge-jun lidge-jun commented Sep 4, 2026

Copy link
Copy Markdown
Owner

Summary

Records the devlog unit for the admin-token local-UX work merged in #3491, #3496, and #3493. Documentation only — no runtime, test, or build path reads from devlog/.

Five documents:

  • 000 — why a plain local user was shown a token box: resolveTokenAfter401 treated any definitive session refusal as "ask the human", but on loopback the only refusals are Host/Origin mismatches that no token can repair.
  • 010 — the suppression design, including why the predicate had to be the bind (isApiAuthRequired) rather than runtimeRole.
  • 020 — the two dialog defects, the CSS cascade mechanism behind Dashboard: admin token dialog shows an empty red error notice before validation #3483, and why testing it needed a stylesheet oracle rather than a DOM assertion.
  • 030 — the Windows baseline finding: 179 failures on Bun 1.3.14 became 25 on 1.4.0, and 161 of them were one preload ordering bug that also let two suites reach live PowerShell and Task Scheduler state. Carry-forward work is named, not silently dropped.
  • 040 — delivery record: merge SHAs, ancestry proof, the stack-parent close race that cost fix(gui): never ask a local dashboard for an admin token #3492, and both trailing CI flakes classified with evidence.

Verification

bun run privacy:scan — passed. tests/repo-hygiene.test.ts constraints respected: no gitlink, no vendored reference clones, no pre-disclosure security material (every defect described here is already public in merged diffs, which is the AGENTS.md test for what may live in devlog/).

Checklist

  • Documentation only; no code paths touched
  • No credential, token, or request-body values recorded
  • Targets dev

Summary by CodeRabbit

  • Documentation
    • Added guidance explaining when local dashboards may request an administrator token and how to locate or configure that token.
    • Documented clearer handling for unavailable sessions across different dashboard runtime modes.
    • Added localized help content for the administrator-token dialog.
    • Recorded Windows testing results, known limitations, verification coverage, and delivery details for the local dashboard experience.

@lidge-jun
lidge-jun requested a review from Ingwannu as a code owner September 4, 2026 18:32
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Sep 4, 2026
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 4, 2026

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review Completed 2026-09-04T18:35:40.412921Z 200498e PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@github-actions

github-actions Bot commented Sep 4, 2026

Copy link
Copy Markdown
Contributor

Deterministic PR hygiene checks passed.

@coderabbitai

coderabbitai Bot commented Sep 4, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Team

Run ID: c3dd2d76-2581-4504-8867-1939ab66d774

📥 Commits

Reviewing files that changed from the base of the PR and between 8b961b1 and 200498e.

📒 Files selected for processing (5)
  • devlog/_plan/260905_admin_token_local_ux/000_research.md
  • devlog/_plan/260905_admin_token_local_ux/010_suppress_local_prompt.md
  • devlog/_plan/260905_admin_token_local_ux/020_dialog_repair.md
  • devlog/_plan/260905_admin_token_local_ux/030_windows_baseline.md
  • devlog/_plan/260905_admin_token_local_ux/040_delivery_record.md

📝 Walkthrough

Walkthrough

This PR adds planning and delivery records for the admin-token local UX work. It documents authentication behavior, dialog repairs, localized token guidance, Windows test baselines, merged changes, and verification results.

Changes

Admin token local UX

Layer / File(s) Summary
Authentication flow and prompt behavior
devlog/_plan/260905_admin_token_local_ux/000_research.md:1-120, devlog/_plan/260905_admin_token_local_ux/010_suppress_local_prompt.md:1-101
Documents session bootstrap failures, host and origin mismatches, prompt suppression for non-hub roles, session cancellation, and non-blocking notices.
Dialog visibility and token guidance
devlog/_plan/260905_admin_token_local_ux/020_dialog_repair.md:1-63
Records the hidden-notice CSS correction, admin-token file and environment-variable guidance, localized copy, and related tests.
Windows baseline and delivery record
devlog/_plan/260905_admin_token_local_ux/030_windows_baseline.md:1-82, devlog/_plan/260905_admin_token_local_ux/040_delivery_record.md:1-64
Records Windows test failures and guard-cascade evidence, carry-forward work, merged PRs, CI results, and the corrected isApiAuthRequired prompt predicate.

Estimated code review effort: 2 (Simple) | ~10 minutes

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/admin-token-devlog

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@lidge-jun
lidge-jun merged commit 2fb11f4 into dev Sep 4, 2026
16 of 17 checks passed
@lidge-jun
lidge-jun deleted the codex/admin-token-devlog branch September 4, 2026 18:33
@lidge-jun

Copy link
Copy Markdown
Owner Author

리뷰 · 우선순위 50 / 80

이 PR은 이미 dev에 들어간 관리자 토큰 로컬 UX 묶음(#3491 빈 빨간 알림, #3496 루프백에서 토큰 상자 안 띄우기, #3493 대화상자 안내·문서 앵커)을 나중에 다시 읽을 수 있게 devlog/_plan/260905_admin_token_local_ux/에 다섯 장으로 남기는 문서만의 기록입니다. 런타임·테스트·빌드 경로가 devlog/를 읽지 않는다는 전제와 tests/repo-hygiene.test.ts·privacy:scan 제약을 지키려는 형태입니다. 지금 dev HEAD 8b961b198의 마지막 머지가 바로 #3493이라, 이 기록은 “방금 끝난 유닛을 닫는 장부”에 가깝고 제품 코드를 바꾸지 않습니다.

000은 왜 로컬 사용자에게 토큰 상자가 떴는지 설명합니다. 루프백에서는 세션이 issueGuiSession으로 자동 발급되는데, resolveTokenAfter401이 재발급 실패(unavailable)를 “사람에게 토큰을 물어라”로 넘겼고, 그 401의 실제 원인은 Host/Origin 불일치라 토큰으로 고칠 수 없다는 줄기입니다. 010은 그래서 억제 신호를 runtimeRole이 아니라 서버와 같은 isApiAuthRequired(바인드)로 맞춘 이유를 남깁니다. 020은 #3483의 CSS 캐스케이드(작성자 .notice { display: flex }가 UA [hidden]을 이김)와 happy-dom이 레이아웃을 못 봐서 스타일시트 오라클 테스트가 필요했던 점, 그리고 #3353 안내 문장·9개 로케일·문서 링크를 적습니다. 030은 Windows 베이스라인 숫자(Bun 1.3.14에서 179실패 → 1.4.0에서 25)와, 그중 161개가 tests/preload.ts에서 가드보다 먼저 락을 잡아 SID 조회 타임아웃 뒤 가드 없이 돌며 라이브 PowerShell/Task Scheduler까지 건드린 한 버그였다는 증거입니다. 040은 머지 SHA·조상 증명·#3492 스택 부모 브랜치 삭제 레이스·두 건의 CI 플레이크 분류까지 배달 기록입니다.

지금 체크아웃과 맞춰 보면, gui/src/api.tsresolveTokenAfter401은 이미 adminTokenPromptAllowed() 분기가 들어간 뒤 형태이고, src/server/gui-session.ts·src/server/auth-cors.tsisApiAuthRequired·gui/src/styles.css.notice:not([hidden])·대화상자 도움말/admin-api-token 안내는 HEAD에 있습니다. 폴더 자체는 #3491/#3496assets/(before/after 스크린샷)만 먼저 생긴 상태라, 이번 PR이 본문 마크다운 다섯 장을 채우는 마무리입니다. CI는 docs-only라 무거운 테스트 샤드는 skip이고 hygiene·enforce-target·ci aggregate는 통과했습니다.

라인 1 - 000_research.md가 고치기 전 resolveTokenAfter401 스케치를 “around line 247”로 적었는데, 현재 HEAD에서는 함수가 약 266행이고 그 사이에 adminTokenPromptAllowed 분기가 있습니다. 역사 기록으로는 괜찮지만, “지금 파일을 열어 같은 줄”로 읽으면 어긋납니다. 연구 문서 상단에 “이 줄 번호는 수정 전 스냅샷”이라고 한 줄 박아 두면 이후 기여자가 덜 헷갈립니다.

경로/030_windows_baseline.md - preload 가드 순서·multi-account auth store·keep-native-v1 argv 단언 세 가지는 “따로 유닛으로 가져가라”고만 적혀 있고, 아직 이슈 번호가 없습니다. 증거가 강한 안전 결함(가드 없이 스케줄러/PowerShell)인데 장부에만 있으면 다음 주 트리아지에서 다시 발굴해야 합니다.

경로/000·040 - 세션 메타 예시가 ocx_session_CO-4g0m5B_...처럼 잘렸고 본문도 토큰 전문을 안 넣었다고 해서 hygiene 방향과는 맞습니다. 다만 curl 재현 블록이 실제 프록시 출력을 베낀 형태라, 나중에 비슷한 문서를 쓸 때 잘림 길이를 더 짧게 두는 습관만 유지하면 됩니다.

경로/전체 - 제품 코드·테스트·워크플로 변경이 없고 documentation 라벨·dev 타깃이라 types/config 분할 캠페인과도 충돌하지 않습니다. 머지 상태 UI는 BLOCKED(리뷰/정책)로 보이지만 mergeable은 MERGEABLE이고 필수 hygiene 계열은 초록입니다.

메인테이너의 판단이 필요한 지점

  • 030의 Windows 캐리포워드 세 건을 지금 이슈로 열어 번호까지 문서에 박을지, 아니면 다음 Windows 하네스 유닛으로 미룰지
  • 줄 번호가 빠른 속도로 흔들리는 연구 문서에 “고정 SHA 기준” 문구를 넣을지, 심볼 이름만 남기고 줄 번호를 줄일지
  • devlog/_plan에 남길지, 유닛이 끝났으니 곧 _fin으로 옮길지(지금 PR 범위 밖이어도 다음 정리 규칙)

너의 추천
문서만이고 이미 머지된 #3491/#3496/#3493의 장부를 정확히 채우므로, CI 초록 확인 뒤 머지하세요. 머지 직후(또는 같은 날) 030의 preload 가드 순서 안전 결함만이라도 이슈 하나 열어 번호를 030에 한 줄 보강하거나 후속 PR로 링크하면 장부가 실행 목록으로 이어집니다. types/config 분할과 무관하니 close-don't-rebase 대상이 아닙니다.

이 댓글은 grok-bot이 작성했습니다

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 200498e812

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +73 to +75
1. Arm `OCX_TEST_HOME_GUARD` before `acquireTestRunLock`, or make the SID lookup
fail closed instead of proceeding unguarded. Highest value: it is a safety
defect, not just a flake.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Remove the unfixed safety finding from tracked devlog

This publishes an explicit remediation for a defect that the document says is not fixed, after explaining how the failure leaves the test guard off and permits suites to reach the developer's live Task Scheduler. That is pre-disclosure bypass reasoning and a patch plan for an unfixed fail-open safety issue; keep these details in .tmp/ until the fix ships, then publish the closed outcome.

AGENTS.md reference: AGENTS.md:L103-L110

Useful? React with 👍 / 👎.

@@ -0,0 +1,64 @@
# 040 — Delivery record

Work-phase `wp4`. All three PRs merged to `dev` with admin authority.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Move the completed unit to _fin

This delivery record says every phase PR merged and the associated issues closed, so the unit has a terminal outcome rather than remaining open. Keeping the directory under _plan incorrectly advertises completed work as active; move the closeout record to _fin and split any genuinely open follow-up into its own plan.

AGENTS.md reference: AGENTS.md:L83-L86

Useful? React with 👍 / 👎.

Comment on lines +31 to +33
The rule: **the admin-token prompt is for a deployment that actually requires a
typed credential.** That is the non-loopback bind, which is the `hub` role. Any
other role — `standalone`, `client`, or an absent tag — must not prompt.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Replace the rejected role-only authentication design

The shipped gui/src/api-targets.ts:51-60 consumes opencodex-management-auth-required; a non-loopback standalone must prompt, while a loopback hub can mint a session. 040_delivery_record.md:58-64 also identifies this role-only rule as the rejected first implementation. Presenting it here as the phase's rule, code, and test plan makes the new record internally contradictory and gives future maintainers the wrong authentication invariant; rewrite this section around bind metadata or clearly mark the design as superseded.

Useful? React with 👍 / 👎.

lidge-jun pushed a commit that referenced this pull request Sep 4, 2026
Records PR #3507 (`663fdbb0a`) as the closure of carry-forward item 1 from the
Windows baseline triage, and adds `031` explaining why that fix mattered
independently of the failure count it removed.

The count was the wrong headline. 161 red tests were the alarm; the damage was
the handful that went green by doing something to the developer's machine,
because the guard those suites rely on to refuse live elevation and Task
Scheduler mutation had been skipped. A luckier run would have shown fewer
failures and made the same writes.

Also records what the plan audit changed — arm-then-lock became
sandbox → arm → lock, because the first still leaves a worker able to read the
real home — and the delivery-record rows for #3504 and #3507.
lidge-jun added a commit that referenced this pull request Sep 4, 2026
…ix (#3514)

Records PR #3507 (`663fdbb0a`) as the closure of carry-forward item 1 from the
Windows baseline triage, and adds `031` explaining why that fix mattered
independently of the failure count it removed.

The count was the wrong headline. 161 red tests were the alarm; the damage was
the handful that went green by doing something to the developer's machine,
because the guard those suites rely on to refuse live elevation and Task
Scheduler mutation had been skipped. A luckier run would have shown fewer
failures and made the same writes.

Also records what the plan audit changed — arm-then-lock became
sandbox → arm → lock, because the first still leaves a worker able to read the
real home — and the delivery-record rows for #3504 and #3507.

Co-authored-by: jun <jun@lidge.dev>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant