docs: record agent submission diagnosis

.project-docs/30-worklog/tasks/20260831-diagnose-agent-submit-f90e1b3f.md

@@ -0,0 +1,83 @@
+# Task: Diagnose local Agent submission stall
+
+## Identity
+
+- Task ID: 20260831-diagnose-agent-submit-f90e1b3f
+- Mode: Feature
+- Branch: codex/20260831-diagnose-agent-submit-f90e1b3f-diagnose-agent-submit-f90e1b3f
+- Worktree: /Users/inmanx/Documents/makelore-diagnose-agent-submit-f90e1b3f
+- Base commit: 38f85f6b5e4dc4e2c5e5b9f8f4506554cfd578f5
+- Owner: codex
+- Status: Ready for Integration
+
+## Scope
+
+- Diagnose the Makelore Code conversation shown with three settled
+  `处理失败` groups and one accepted message remaining at `正在提交…`.
+- Correlate the screenshot timestamp with the live Electron/Main/Pi process
+  state, persisted Main logs, Renderer request reconciliation, and AI proxy
+  error classification.
+- Make no product-source, dependency, runtime, account, or external-service
+  changes.
+
+## Intent And Constraints
+
+- Preserve the Main-owned Pi `0.84.2` boundary and do not replay an accepted
+  mutation while diagnosing it.
+- Treat the separate development worktree and running Electron process as
+  read-only evidence.
+- Distinguish expected background runtime sleep from an unexpected Agent
+  Server crash.
+
+## Outcome
+
+- Identified the immediate failure as upstream Token Point exhaustion. At
+  `2026-08-31T11:25:18Z`, `11:25:22Z`, `11:25:32Z`, and `11:25:59Z` (19:25
+  Asia/Shanghai), the Main-owned AI proxy reached
+  `https://token.nianxx.cn/v1/chat/completions` and received `403 Forbidden`
+  with code `token_point_balance_exhausted` and message `词元点数余额不足`.
+- Correlated the first three responses with the three settled failure groups.
+  The final bubble had already received Host/Pi acceptance, so Renderer showed
+  `1 条消息已被本地 Agent 接收。`; the screenshot was taken before the fourth
+  provider failure terminal patch replaced the optimistic `正在提交…` state.
+- Confirmed the later Agent Server disappearance was intentional
+  `background_sleep` after the app lost foreground programming activity, with
+  exit code 0 and `server.stopped`; no `server.invalidated` or unexpected crash
+  occurred in the incident window.
+- Found a secondary UX classification gap: the quota helper recognizes
+  `token_balance_exhausted` and the proxy remaps quota only when upstream status
+  is 429, while the observed service contract used status 403, code
+  `token_point_balance_exhausted`, and Chinese `词元点数余额不足`. The response
+  therefore remained a generic provider failure and the collapsed timeline
+  exposed only `处理失败` instead of an actionable balance message.
+- No product source or dependencies were changed.
+
+## Verification
+
+- Inspected the supplied screenshot at original resolution and matched its
+  19:25 conversation time to the persisted Main log.
+- Read `/Users/inmanx/Library/Application Support/niancode/logs/niancode-2026-08-31.log`;
+  confirmed seven occurrences of the same balance-exhaustion contract during
+  the current day, including all four requests in the screenshot window.
+- Verified Electron PID `98444`, Host API port `13210`, and Vite port `5173`
+  remained live while the Pi Agent Server later stopped through the expected
+  background lifecycle.
+- Inspected `src/stores/coding-conversations.ts`,
+  `src/pages/Chat/CodingChatPanel.tsx`,
+  `src/pages/Chat/CodingConversationTimeline.tsx`,
+  `electron/api/routes/ai-proxy.ts`,
+  `shared/ai-gateway-error-kind.ts`, and the Pi runtime/projector path.
+- No tests were run because this task was diagnosis-only and made no behavior
+  change.
+
+## Follow-ups
+
+- Restore sufficient Token Point balance before retrying the model request.
+- If a product fix is requested, recognize the observed
+  `token_point_balance_exhausted` contract independently of its 403/429 status,
+  project a stable non-retryable quota error, show actionable Chinese copy, and
+  add focused proxy/projector/Renderer regressions.
+
+## Promotion Candidates
+
+- None recorded.