pi-mono/packages/coding-agent/docs
Petr Houška b2cb629237
fix(coding-agent): wait for a started OAuth refresh to be saved before exit (#11812)
Fixes #11692.

## Problem

In RPC mode the startup catalog refresh runs in the background and also
refreshes an expired OAuth credential. If pi exits after the token
request went out but before the new token is written, the provider has
already spent the old single-use refresh token and auth.json keeps only
that one. The next request fails with `invalid_grant`.

Trace: `pi --mode rpc` starts, `get_state` is answered, catalog refresh
sends the token request, the client sends SIGTERM (or closes stdin),
`shutdown()` runs `runtimeHost.dispose()`, which does not know about the
refresh, and the process exits. Same for print and interactive mode, and
for a prompt-time refresh cut off by an exit.

## Fix

- `RuntimeCredentials.modify()` tracks every pending modification (same
idiom as the MCP `track()` / `McpAuthProvider.settled()`).
- `RuntimeCredentials.settled()` /
`ModelRuntime.settleCredentialWrites()` wait for them.
- `AgentSessionRuntime.dispose()` waits for them. All modes exit through
`dispose()`. No extra timeout: the OAuth refresh (15 s) and the
auth.json lock wait (30 s) are already bounded, and a second signal
still exits at once.

Not changed: the catalog refresh still refreshes expired OAuth
credentials, also for providers whose catalog does not use them (the
pi.dev catalog for `openai`, `anthropic`, ...). Skipping that would need
a per-provider "catalog needs auth" signal in pi-ai; it is optional now
that exits wait.

`docs/rpc.md` now says that pi waits for pending work before exiting.

## Testing

- `test/runtime-credentials.test.ts`: `settled()` waits until a pending
modification is written, and resolves after a failed one.
-
`test/suite/regressions/11692-dispose-waits-for-oauth-refresh.test.ts`:
`dispose()` waits until the token from a background catalog refresh is
saved. Fails without the fix.
- Real process: `pi --mode rpc` with an extension OAuth provider
(expired credential, 400 ms refresh), SIGTERM about 100 ms after the
token request started. Without the wait: 3 of 3 runs kept the spent
refresh token. With the fix: 3 of 3 saved the new one (exit 143).
Closing stdin instead of SIGTERM: new token saved, exit 0.
- `npm run check`; `test/rpc*`, `test/print-mode`,
`test/model-runtime*`, runtime and regression suites pass.
2026-11-05 00:32:41 +01:00
..
images docs(coding-agent): refresh documentation (#9898) 2026-09-22 16:48:19 +02:00
cli-integration.md fix(coding-agent): warn and exit non-zero in print mode on truncated response 2026-10-12 16:06:42 +02:00
cli.md feat(coding-agent): add PI_SELF_UPDATE_COMMAND and selfUpdateCommand for pi update (#11629) 2026-10-30 22:30:39 +01:00
codemode.md fix(coding-agent): queue codemode scripts at the worker limit 2026-10-20 20:50:27 +02:00
compaction.md fix(coding-agent): remove fixed output limits from summary requests (#11036) 2026-10-16 13:53:16 +02:00
configuration.md feat(coding-agent): codemode and MCP 2026-09-29 09:12:50 +02:00
containerization.md docs(coding-agent): refresh documentation (#9898) 2026-09-22 16:48:19 +02:00
custom-provider.md docs(coding-agent): shorten device-code login guidance 2026-10-22 21:38:58 +02:00
docs.json docs(ai,coding-agent): generate models.json reference from schemas (#11038) 2026-10-16 21:53:00 +01:00
environment-variables.md feat(coding-agent): add PI_SELF_UPDATE_COMMAND and selfUpdateCommand for pi update (#11629) 2026-10-30 22:30:39 +01:00
extensions.md fix(coding-agent): stream the read tool instead of loading whole files (#11750) 2026-11-04 23:14:52 +01:00
how-pi-works.md docs(coding-agent): refresh documentation (#9898) 2026-09-22 16:48:19 +02:00
index.md docs(coding-agent): add Radius to providers page, rename provider docs sections 2026-10-01 17:06:00 +02:00
json.md feat(tui,coding-agent): report program status via OSC 7501 2026-10-07 19:05:41 +00:00
keybindings.md fix(coding-agent): keep ctrl+v as a paste key on Windows and WSL (#11780) 2026-11-04 09:33:31 +01:00
llama-cpp.md docs(coding-agent): llama.cpp tweaks (#11624) 2026-11-04 11:07:48 +01:00
mcp.md feat(coding-agent): prefer the client ID metadata document for MCP OAuth 2026-10-30 10:36:22 +01:00
message-types.md feat(ai): carry responseModel on pi-messages terminal events (#11265) 2026-10-23 10:54:18 +02:00
models-configuration.md fix(ai): allow prompt cache keys for compatible proxies (#9442) 2026-11-04 11:36:35 +01:00
models.md feat(ai): add Microsoft-Decision-1 classifier to GitHub Copilot (#11679) 2026-11-02 16:12:43 +01:00
nvidia-rtx-llama-cpp.md docs(coding-agent): restructure NVIDIA RTX llama.cpp prerequisites 2026-10-13 15:04:38 +01:00
packages.md docs(coding-agent): document how -e packages are cached and refreshed 2026-10-29 21:43:11 +01:00
prompt-templates.md docs(coding-agent): refresh documentation (#9898) 2026-09-22 16:48:19 +02:00
providers.md feat(ai): add Qwen Token Plan Individual CN provider (#7989) 2026-11-04 11:32:45 +01:00
quickstart.md docs(quickstart): add Windows installer tab (#11231) 2026-10-28 10:10:44 +01:00
rpc-commands.md feat(coding-agent): report prompt disposition in RPC responses 2026-09-25 14:53:11 +02:00
rpc-extension-ui.md docs(coding-agent): refresh documentation (#9898) 2026-09-22 16:48:19 +02:00
rpc.md fix(coding-agent): wait for a started OAuth refresh to be saved before exit (#11812) 2026-11-05 00:32:41 +01:00
sdk.md docs(coding-agent): add Radius to providers page, rename provider docs sections 2026-10-01 17:06:00 +02:00
security.md feat(coding-agent): codemode and MCP 2026-09-29 09:12:50 +02:00
session-format.md feat(coding-agent): Virtual models (#10035) 2026-09-28 23:30:45 +02:00
sessions.md docs(coding-agent): document which working directory resumed sessions use (#11617) 2026-10-30 17:22:05 +00:00
settings.md feat(coding-agent): add PI_SELF_UPDATE_COMMAND and selfUpdateCommand for pi update (#11629) 2026-10-30 22:30:39 +01:00
shell-aliases.md docs(coding-agent): refresh documentation (#9898) 2026-09-22 16:48:19 +02:00
skills.md docs(coding-agent): refresh documentation (#9898) 2026-09-22 16:48:19 +02:00
slash-commands.md docs(coding-agent): document which working directory resumed sessions use (#11617) 2026-10-30 17:22:05 +00:00
terminal-setup.md fix(tui): treat ESC+Return with native Shift held as Shift+Enter 2026-10-29 20:17:54 +01:00
termux.md docs(coding-agent): refresh documentation (#9898) 2026-09-22 16:48:19 +02:00
themes.md feat(coding-agent): use pi.dev configuration schemas (#10751) 2026-10-11 14:48:42 +01:00
tmux.md docs(coding-agent): list external limitations as known issues with remedies (#11647) 2026-10-31 17:55:58 +01:00
tui.md feat(coding-agent): let inline ctx.ui.custom() components report blocked program status (#11471) 2026-10-27 09:27:28 +01:00
usage.md feat(coding-agent): configure session share destination 2026-10-13 15:41:13 +02:00
virtual-models.md feat(coding-agent): Virtual models (#10035) 2026-09-28 23:30:45 +02:00
windows.md docs(coding-agent): list external limitations as known issues with remedies (#11647) 2026-10-31 17:55:58 +01:00