docs(spec): ConnectorConnectionState.status JSDoc drops "expired" from the no-refresh-token reconnect reason (#29238)

<!-- claude-projects-attribution: {"github_login":"os-steve"} -->
_Requested by **Steve** · [project
thread](https://claude.ai/code/project/chan_01FdL1XeUyvVNxLreh3F4Qi9?thread=cmsg_01FdL1XeUyvVNxLreh3F4Qi9RGMtg21zGTLxCeQagf8SHa)_
Fixes #28961

Clause-②: no
Metadata-protocol: none

## 维护者速读

- 改了什么：只改 `ConnectorConnectionState.status` 的一段 JSDoc
注释，去掉「过期（expired）」一词，外加一个 spec patch changeset。
- 为什么改：没有 refresh token（或没有 client）的连接，在缓存未命中或请求遇到 401
时也会尝试刷新并被标为需要重连，此时 access token 可能仍然有效；旧注释把原因说成「token 过期」，与运行时不符。
- 风险与回滚：零运行时风险，只是注释文字；回滚即还原这一个 commit。
- 先看：`packages/spec/src/contracts/automation-service.ts`（第 1145–1148 行）。
- 两分钟验证：在本分支运行 `git grep -n "access token it has to renew with" --
packages`，应看到 3 处：运行时 2
处（connector-connections.ts、sys-connector-connection.object.ts）和 spec 1
处，说法一致。
- 需要你做的：无，席位落地。

## What changes

- `packages/spec/src/contracts/automation-service.ts`: the
`reconnect_required` arm of the `ConnectorConnectionState.status` JSDoc
said a connection is marked when it "keeps nothing to renew an expired
access token with". A refresh also runs on a cache miss (a fresh
replica, or a `revision` another replica moved) and on a dispatch's 401,
so a connection with no refresh token, or no client to refresh with, is
marked while its access token may still be valid. The arm now reads
"keeps nothing to renew an access token it has to renew with", the
wording the runtime already uses for the same fact in
`ConnectorConnectionStore.markReconnectRequired`
(`packages/services/service-automation/src/connector-connections.ts`)
and in the `sys_connector_connection.status` description, and the sense
of the reasons the runtime stores (`no_refresh_token` / `no_client` in
`oauth2-grant/grant-handle.ts`: "an access token the connection has to
renew cannot be renewed"). The runtime sentence from PR #28955 is on
`main`, so no wording waits on it. No new claim is added.
- `.changeset/28961-connector-connection-status-doc.md`:
`@objectstack/spec` patch, with the two declaration lines.

Comment only: no schema, type, export or runtime string changes. No
forced test edits.

## Tests

Run in the card worktree at head `8d3ba747`, each under
`scripts/pm/os-verify-lock.sh`:

<details><summary>packages/spec build, test, typecheck,
check:generated</summary>

- `pnpm --filter @objectstack/spec build` (plus the `@objectstack/lint`
closure for the formula gate): `VERDICT command-exit 0`.
- `pnpm --filter @objectstack/spec test`: `VERDICT command-exit 0`, Test
Files 790 passed (790), Tests 23370 passed, 1 todo (23371).
- `pnpm --filter @objectstack/spec typecheck`: `VERDICT command-exit 0`.
- `pnpm --filter @objectstack/spec check:generated`: exit 0, "All 14
generated artifacts are up to date" against the dist just built. A JSDoc
on an interface field is not a `.describe()`, so
`content/docs/references/**` does not move.

</details>

No consumer tests: the claim is `Metadata-protocol: none` and the public
surface is byte-identical (`check:api-surface` green).

## Acceptance notes

None.

## Verification

<details><summary>dispatch-gates derived set at 8d3ba74: 73 derived, 71
run green, 2 NOT MEASURED</summary>

- `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` derived 73 commands for the 2 paths; every
one was run and recorded with its exit code; `--ran` reconciles: "73
derived famil(ies) accounted for, 71 run, 2 NOT-MEASURED".
- 71 exit 0, including `check:doc-authoring`, `check:api-surface`,
`check:docs`, `check:changeset-no-major --base origin/main`,
`check:empty-changeset --base origin/main`, `check:adr-0087-registration
--base origin/main`, `check:nul-bytes`, `check:issue-citations`,
`check:spec-docblock-symbol-anchors`.
- `check-plugin-teardown-shape.mjs --self-test` first exited 3 on the
shallow clone (its pinned fixture commit was unreachable); after
fetching that one commit it exits 0, 48 cases pass.
- NOT MEASURED locally, exit 3 PREREQUISITE NOT MET: `pnpm
check:dual-build-cjs-loads` and `pnpm check:lean-entry-closure`. Both
load every package's built `dist/`, which this card did not build (no
package's code changes). CI's `Lint & Repo Gates` runs them.

</details>

---
_Generated by [Claude
Code](https://claude.ai/code/session_01ADHkmQs2bVYuybG5pYYUg2)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

.changeset/28961-connector-connection-status-doc.md

@@ -0,0 +1,10 @@
+---
+'@objectstack/spec': patch
+---
+
+docs(spec): `ConnectorConnectionState.status` no longer says a connection with no refresh token is marked because its access token expired
+
+Clause-②: no
+Metadata-protocol: none
+
+Comment only. The `reconnect_required` JSDoc said such a connection "keeps nothing to renew an expired access token with". A refresh also runs on a cache miss (a fresh replica, or a `revision` another replica moved) and on a dispatch's 401, so a connection with no refresh token, or no client to refresh with, is marked even while its access token is still valid. The JSDoc now reads "keeps nothing to renew an access token it has to renew with", the wording the runtime's own `markReconnectRequired` doc and the `sys_connector_connection.status` description use, and the sense of the `status_reason` the runtime stores ("an access token the connection has to renew cannot be renewed").

packages/spec/src/contracts/automation-service.ts

@@ -1151,9 +1151,9 @@ export interface ConnectorConnectionState {
      * dispatches nothing for this organization); `connected`; or
      * `reconnect_required` — the grant stopped working: the authorization
      * server refused it on refresh, the connection keeps nothing to renew an
-     * expired access token with (no refresh token was issued, or no client to
-     * refresh with), or the upstream refused the connection's token while an
-     * `mcp` instance discovered its tools. `statusReason` says which.
+     * access token it has to renew with (no refresh token was issued, or no
+     * client to refresh with), or the upstream refused the connection's token
+     * while an `mcp` instance discovered its tools. `statusReason` says which.
      */
     status: 'not_connected' | 'connected' | 'reconnect_required';
     /** Why the grant stopped working, when `status` is `reconnect_required`. */