[objectstack-fleet]

domain:server#5 · os-project-manager · session_01FEkQ5oc56xChD6Wrc4cGSt

Requested by Leehom · project thread

Fixes #28963

Clause-②: no
Metadata-protocol: none

维护者速读

• 改了什么：连接器连接被标成「需要重新连接」后，之后的每一次调度都回答该行存下的原因（上一张卡让每条刷新路径存下真实原因：服务器拒绝、没发 refresh token、没有可用 client）。以前只有标记它的那一次说对，之后每次（换副本、重启、重试）都说「授权服务器拒绝了授权」。刷新标记连接时写的服务器日志也改为这句存下的原因，三条路径各说各的原因。
• 为什么改：管理员从调度拒绝和服务器日志里读到的原因，在没发 refresh token 或没有 client 的情况下是错的（fix(service-automation): a connection marked reconnect required says the cause that actually happened (#28863) #28955 开发者发现，seat 1 立卡）。
• 风险与回滚：低。只改拒绝文字和一行日志；503 SERVICE_UNAVAILABLE、状态值、错误码、写入都不变。没存原因的行仍回答原来的拒绝句。回滚即 revert。
• 先看：packages/services/service-automation/src/oauth2-grant/grant-handle.ts 的 markedReason 及其两处调用；plugin.ts 的 onGrantRefused 日志行；grant-handle.test.ts 末尾的 [#28963] 四条。
• 两分钟验证：pnpm --filter @objectstack/service-automation exec vitest run src/oauth2-grant/grant-handle.test.ts src/connector-connection-door.test.ts，预期 Tests 46 passed (46)（main 上 6 条红）。
• 需要你做的：无，席位落地。

What changes

• grant-handle.ts: a connection already marked reconnect_required answers what it stores. A new private markedReason(connector, record) returns the row's statusReason, and the default refusal sentence (reconnectRequiredReason(connector, organizationId), unchanged) only when the row stores none. Both places that refuse a marked row use it: select (every dispatch's first read) and refreshOnce's first check (the re-read under the cluster lock, which sees a row another replica marked while this one waited). The stored reasons are the per-path sentences PR fix(service-automation): a connection marked reconnect required says the cause that actually happened (#28863) #28955 introduced, so the first dispatch and every later one now answer the same sentence.
• onGrantRefused carries the reason. OAuth2GrantHandleDeps.onGrantRefused is now (organizationId, reason): grantRefused passes the sentence it just stored. The interface is internal: oauth2-grant/ is not re-exported from the package entry (src/index.ts has no oauth2-grant export, and no other package names it), so no published member changes.
• plugin.ts: the log line is that reason. The warn line was "connector instance 'X': the authorization server refused the grant of organization 'Y'; it needs to be reconnected there" on all three refresh paths. It is now [Automation] + the stored reason, which names the instance, the organization and the cause in PR fix(service-automation): a connection marked reconnect required says the cause that actually happened (#28863) #28955's words. Still warn; it is distinct from the hold's own "… is degraded: …" line.
• Changeset .changeset/28963-reconnect-required-stored-cause.md: patch on @objectstack/service-automation, both declaration lines.
• No new status value, error code or published member; no packages/spec/**; no docs page change (connectors.mdx already says the connection's statusReason names the cause).

Why Clause-②: no. Nothing that was accepted is refused and nothing refused is accepted: the 503 stays a 503 SERVICE_UNAVAILABLE, only its message on an already-marked row and one log line's text change.

Tests

Four new cases at the end of src/oauth2-grant/grant-handle.test.ts ([#28963]), on the file's in-memory connection store:

• A row marked because no refresh token was issued answers the stored no-refresh-token sentence on the first dispatch, on two later gets and a refresh, and from a second handle that never saw the marking (another replica, a restart). None says refused; no token request is made.
• A row another replica marked while this one waited for the lock (the lock double marks it no_client before running the refresh): the dispatch answers that stored sentence. This is the refreshOnce first check.
• A marked row that stores no cause still answers reconnectRequiredReason's refusal sentence, at select and under the lock (control; green on main too).
• Each refresh path tells the plugin its own cause: no refresh token, no client and invalid_grant each call onGrantRefused('org_a', stored) once, with the stored sentence naming that cause.

Two existing cases now also read the second argument (invalid_grant gets the refusal message; the kept-client case gets the no-client sentence).

src/connector-connection-door.test.ts (real plugin, real ObjectQL on SQLite, local OAuth server):

• New: a connect whose code exchange issues no refresh token, then a dispatch the upstream answers 401. The row stores the no-refresh-token sentence, the 503 message equals it, the log carries [Automation] REASON. and nowhere refused the grant, and the instance is held with that same cause. The rig gains idp.exchangeIssuesRefreshToken (default true, reset after each case).
• Updated: the no-leak case's "the logs did record it" assertion reads the refused path's new line, [Automation] connector instance 'crm' needs to be reconnected for organization 'org_a': its authorization server refused the grant.

Red on main, green on head

• Main (the tests at 9ae5df9d, before the fix): Tests 6 failed | 40 passed (46). The reds: the two existing cases and the per-path case (expected "vi.fn()" to be called with arguments: [ 'org_a', …(1) ]), the no-refresh-token and replica cases (Expected: "…its authorization server issued no refresh token…" / "…keeps no client to refresh with…", Received: "…its authorization server refused the grant (revoked, or expired with no usable refresh)…"), and the door case (expected '…' to contain '[Automation] connector instance \'crm…'). The no-stored-cause control is green both ways.
• Head: Test Files 2 passed (2), Tests 46 passed (46).

Ablation, one per site

Each through node scripts/ablation-replace.mjs (anchor 1 → 0, blob moved, restored; git diff HEAD empty after all four), running both files. The package's tests import ./grant-handle.js and ./plugin.js from src/, so no build sits between the mutation and the run.

Site	Mutation	Result
select	markedReason(connector, record) → reconnectRequiredReason(connector, record.organizationId)	1 failed: the no-refresh-token "every later dispatch" case
refreshOnce first check	markedReason(connector, current) → reconnectRequiredReason(connector, organizationId)	1 failed: the replica-marked-under-lock case
grantRefused callback	onGrantRefused?.(record.organizationId, reason) → onGrantRefused?.(record.organizationId)	3 failed: the per-path case and the two updated cases
plugin log line	`[Automation] ${reason}.` → the old "the authorization server refused the grant of organization" line	2 failed: the new door case and the no-leak case

Acceptance notes

• The plugin's hold-reason fallback (plugin.ts, the holdConnectorUntilConnected call in the reconcile) already met ruling 1 on main, so it is unchanged: it reads state.reconnectRequiredReason, the first marked row's statusReason, and falls back to reconnectRequiredReason(name, org) only when that row stores none. The new door case pins it: the hold names the no-refresh-token cause.
• onGrantRefused keeps its name although it now also fires for the two paths that never asked the server; renaming an internal callback is outside this card.
• Who read the old log text: only connector-connection-door.test.ts (the no-leak case), updated here. Searched objectstack, objectui and hotcrm for refused the grant of organization: no other hit.

Verification

All readings at head 543224b1: the change (9ae5df9d tests, d40bcfaf fix, d5ba4f70 changeset) merged once with origin/main ab085a04, a clean merge. One later main commit, 0be247ce, touches only ui/ (plugin-detail).

Package suite, typecheck, lint

• Dependency closure: pnpm turbo run build --filter='@objectstack/service-automation...' --concurrency=2, Tasks: 32 successful, 32 total, lock VERDICT command-exit 0.
• pnpm --filter @objectstack/service-automation test at 543224b1: Test Files 256 passed (256), Tests 3303 passed (3303), lock VERDICT command-exit 0 (before the merge, at d5ba4f70: 255/255, 3289/3289).
• pnpm --filter @objectstack/service-automation typecheck (tsc + test-typecheck) at d5ba4f70: lock VERDICT command-exit 0. The merge touched no file of this diff.
• The repo's pnpm lint command scoped to packages/services/service-automation: exit 0.

Derived gates (`dispatch-gates.mjs --commands`, 61 families)

• All 61 exit 0 at 543224b1; dispatch-gates --ran: 61 derived famil(ies) accounted for — 61 run, 0 NOT-MEASURED. Record: pm-orders/server/28963-gates-ran.txt in the project.
• The same list at d5ba4f70 before the merge: 60 exit 0 and check:dual-build-cjs-loads exit 3 (PREREQUISITE NOT MET, other packages' dist/ missing); at 543224b1 it ran and exits 0. check-plugin-teardown-shape.mjs --self-test needs its pinned fixture commit on this shallow clone (git fetch --depth=1 origin 621a4876…), then exits 0.
• Repo-wide pnpm lint and the CI-only families are CI's; see the PR's check-runs.

test:repo: not run locally (no repo-project test or derived list names it); CI's Test Core is the record. Dogfood battery: not owed (no !, no narrowing arm) and not run.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-automation, touching 6 documentable anchor(s).

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/connectors.mdx (via reconnect_required (literal, a string literal in createOAuth2GrantHandle))

What this run could not see

• the SDK route bridge reached 60 of 216 client-bound route-ledger rows — the other 156 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 156: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 101 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 10 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json c708de67b2c00c095afbf5fb36c6c093dbe85458 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from e5d8d0175eb5dbbf183c7e7e79308d2a51e58ffa — the merge of head 543224b14eabb7b0ddff6b1cc1c793b296eef1e8 into base c708de67b2c00c095afbf5fb36c6c093dbe85458, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin e5d8d0175eb5dbbf183c7e7e79308d2a51e58ffa && git checkout e5d8d0175eb5dbbf183c7e7e79308d2a51e58ffa
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin c708de67b2c00c095afbf5fb36c6c093dbe85458 543224b14eabb7b0ddff6b1cc1c793b296eef1e8 && git checkout -B drift-repro c708de67b2c00c095afbf5fb36c6c093dbe85458 && git merge --no-ff 543224b14eabb7b0ddff6b1cc1c793b296eef1e8

node scripts/docs-audit/affected-docs.mjs --json c708de67b2c00c095afbf5fb36c6c093dbe85458

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs c708de67b2c00c095afbf5fb36c6c093dbe85458 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

domain:server#5 · os-project-manager · session_01FEkQ5oc56xChD6Wrc4cGSt

席位核对

ACCEPT · domain:server seat 5 · os-project-manager · session_01FEkQ5oc56xChD6Wrc4cGSt · 2026-11-02T06:45Z · head 543224b1 · #28963

The maintainer's standing authorisation for landing reviewed PRs, verbatim: 「按照 pm-dispatch 规则复核过的都授权」.

席位意见:与 diff 相符。已标成「需要重新连接」的连接，之后每次调度都回答该行存下的原因(没存原因时才说「授权服务器拒绝」);刷新标记连接时的日志也改为这句原因，三条路径各说各的。状态、错误码、503 拒绝本身不变。

1. Shape: draft against main, Fixes #28963, patch changeset for @objectstack/service-automation; Clause-②: no, Metadata-protocol: none. No contract review owed. check-governed-merges --pr 29065: NOT governed, 5 paths, +158 / -16. git merge-tree against main: clean. The claim (6569737082) names the PR's branch claude/project-thread-30pu5h, and the dev started after PR fix(service-automation): a connection marked reconnect required says the cause that actually happened (#28863) #28955 merged.
2. Against the order:
   • Ruling 1. select and refreshOnce's first check both refuse a marked row with the new private markedReason, which is record.statusReason ?? reconnectRequiredReason(...). The stored text is the sentence fix(service-automation): a connection marked reconnect required says the cause that actually happened (#28863) #28955 wrote on each path (refused, no_refresh_token, no_client), so a later dispatch now says what the first one said.
   • Ruling 2. onGrantRefused gets the stored reason, and the plugin logs [Automation] <reason>.. Each of the three paths logs its own cause. The reason already names the instance and organization, so the line loses nothing the old one had.
   • Ruling 3. No new status, code or published member: oauth2-grant/ is not re-exported from the package entry, and the callback's added argument is internal.
   • The plugin's hold-reason fallback already read statusReason on main. It is unchanged, and a new door case pins it.
   • The docs-drift flag on content/docs/automation/connectors.mdx was read: the page already says "The connection's statusReason says which", and this PR makes that true at every dispatch. No doc edit is owed.
3. Accepted deviations:
   • None from the order. The PR carries no labels (the order named none, and the diff has a changeset).
   • The missing body signature is supplied by this seat.
4. Gates: 6 red on main, 46/46 on head. 4 ablations, one per site, each red. Package suite 3303/3303. Typecheck and scoped lint exit 0. 61/61 derived gates exit 0, --ran 0 NOT-MEASURED. Check-runs on this head were still running at ACCEPT, and auto-merge waits on every required one.
5. Out of scope: the callback keeps the name onGrantRefused although two of its three paths never ask the server. It is an internal name, noted and not filed.
6. Landing: pr_ready + automerge_enable through the relay.