docs(agents): the two multi-agent failure modes that cost this branch the most rounds

[os-zhuang]

Docs only — two entries appended to AGENTS.md § Multi-agent working discipline. Both written from one branch's lifetime (the #3843 envelope line, 16 PRs), so every row is something that actually happened rather than something that might.

#9 — refresh a long-lived worktree's build state after merging main

Four distinct stale artefacts, each of which fails as if your change broke something — naming other people's exports, other packages' files, or config you never touched:

stale artefact	how it presents
packages/spec/dist	check:api-surface reports other people's exports as "5 breaking (removed/narrowed)"; check:i18n-coverage rejects an example config for a chart type the spec allows
node_modules	a package fails to resolve a dependency it plainly declares (Cannot find package 'hono')
packages/runtime/.objectstack/	datasource-autoconnect sees each row 6×
.cache/objectui-*	pnpm lint reports 61 errors in files you have never opened

I hit the first one three separate times before writing it down, and diagnosed it from scratch on two of them. The message that names someone else's export as a breaking change is a genuinely alarming thing to read on your own PR.

Also records that OS_SKIP_DTS=1 — the flag that keeps local builds fast — leaves no .d.ts, so gen:api-surface cannot run under it at all, failing with Could not resolve module symbol … Is the package built?. That reads as a broken build rather than a missing flag.

None of this is CI-visible: CI checks out fresh and installs clean. The entire cost lands on whoever is debugging, which is the argument for recognising it in one step rather than re-diagnosing per gate.

#10 — a clean merge is not a working merge

Git conflicts on overlapping lines. Nothing warns you when two changes are individually fine and jointly wrong. Two real cases from this branch:

• dispatcher 其余服务域仍只判槽位占用、不读 handlerReady —— #4000 在 analytics 一域落地后剩下的类推面 #4058 added a test asserting /ai/agents's body is exactly { agents: [] } while GET /ai/agents is SDK-addressable but unenveloped, and the SDK compensates — making it conformant without a coordinated change silently returns an empty agent list #4053 was enveloping that body one commit earlier. Merged clean, failed CI.
• fix(runtime,hono,plugin-dev): 退役 dispatcher 的 /storage bridge —— 它从来没按契约调用过 storage (#4087) #4112 deleted runtime/src/domains/storage.ts while check-route-envelope.mjs's table still declared it — caught only because that guard exists and treats an undeclared/missing module as an error.

A third was a genuine textual conflict (#4133 and I both removed the same stale ledger entry), and that one git did flag — which is the contrast worth internalising: the conflicts git catches are the ones where two people touched the same line, not the ones where the result is broken.

So: pull main and re-run before opening a PR, and again before merging. Much of scripts/check-*.mjs exists precisely because this class of breakage is invisible to git merge.

Verification

check:doc-authoring · check:role-word · check:org-identifier · check:nul-bytes · check:release-notes — all clean. Empty changeset: docs, releases nothing.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Jul 30, 2026 12:40pm