[objectstack-fleet]

Requested by Leehom · project thread

domain:devx#3 · os-project-manager · session_01FEkQ5kuCuTK9UtGmuBcaPR

Fixes #31339

Clause-②: no
Metadata-protocol: none

维护者速读

• 改了什么:只改 content/docs/deployment/cli.mdx 的 os deploy 一节:参数表加 --confirm-upgrade TOKEN 一行;「To a self-hosted runtime」第 3 步写明两个确认参数都会透传,以及两种升级拒绝各自打印的重试命令;第 4 步补上「运行时记录了包、但运行中的内核加载不了」时退出 1(重启后才生效)。
• 为什么改:os deploy 早已声明并透传 --confirm-upgrade,也已对未热加载的安装退出 1,文档只写了 --confirm-access-upgrade、只写了退出 0 的成功路径,读者照文档走会找不到 schema 升级拒绝的出路。
• 风险与回滚:纯文档,不改任何包、不发布;回滚即还原本 PR。
• 先看:content/docs/deployment/cli.mdx 约 3245 行新表格行,和约 3266–3276 行第 3、4 步。
• 两分钟验证:grep -n "confirm-upgrade" content/docs/deployment/cli.mdx,预期在参数表、第 3 步、os package install 节都能看到它。
• 需要你做的:无,席位落地。

What changes

content/docs/deployment/cli.mdx, section os deploy only. Every fact is read from packages/cli/src/commands/deploy.ts on main 4363945:

1. Flag table. A --confirm-upgrade row beside --confirm-access-upgrade: self-hosted target only, confirms the upgrade's schema findings (a suspected rename, a type change that is not safe) with the finding-set token the runtime's refusal printed, refused when the target is ObjectOS Cloud. Source: the flag's description (deploy.ts L149-L154) and the cloud-target refusal loop over both flags (L169-L177).
2. Step 3, Install. Both --confirm-access-upgrade and --confirm-upgrade are passed through (L336-L340), a schema upgrade to confirm joins the listed refusals, and the step names each refusal's retry: os deploy --confirm-access-upgrade TOKEN for access findings, os deploy --confirm-upgrade TOKEN for schema findings. The retry spelling is PackageInstall.retryCommand = 'os deploy' (deploy.ts L321) as printed by packages/cli/src/commands/package/install.ts L468 and L489.
3. Step 4, Live. A package the runtime recorded but its running kernel could not load is not live: the command prints that it loads when the runtime restarts and exits 1 (deploy.ts L346-L353, !outcome.hotLoaded).

Why

Card #31339: the page lagged os deploy on a self-hosted runtime target on these three points. Rulings from the order: docs only, every fact measured from deploy.ts; p3 by triage 6716396816.

Tests

None owed: docs text only, no behaviour changed, so no test and no ablation.

Acceptance notes

• Eval 21 left alone. The order lets skills/objectstack-platform/evals/ eval 21 ride this PR only if PR docs: teach os mcp connect and the use-runtime deploy target in the remaining pages #31335 (Docs and skill still type the MCP connect line by hand and describe os deploy as cloud-only #31235) had merged at start. Read at start: PR docs: teach os mcp connect and the use-runtime deploy target in the remaining pages #31335 is open, merged: false. The eval is untouched.
• Docs census and transcript gates. pnpm check:docs-transcript-drift, pnpm check:cli-examples-parity, pnpm check:doc-anchors and the rest of the derived union read this file and stay green with no move, so no census row changes in this PR.
• Step 3's "a package the running kernel cannot register" refusal is kept as written: install-local refuses an inline manifest whose register throws (422 PLUGIN_REGISTER_FAILED, install.ts comment at L648-L657), which os deploy reads as a non-installed outcome and exits 1 (deploy.ts L341-L345). The new step 4 sentence covers the other answer, hotLoaded: false.
• Governed surface. node scripts/pm/check-governed-merges.mjs --branch HEAD on head ef2c181, exit 0: "0 of 1 path(s) hit the register … NOT governed — ordinary queue landing applies".
• node scripts/pm/dispatch-gates.mjs --tier: no path-derived model mandate for this surface.

Verification

Gate union derived by node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack (44 families for this diff), run on head ef2c1811, each exit code captured before any pipe:

• 44 run, exit 0 each. --ran: "44 derived famil(ies) accounted for — 44 run, 0 NOT-MEASURED".
• pnpm --filter @objectstack/spec run check:skill-examples first answered exit 3 (PREREQUISITE NOT MET: packages/client-react/dist unbuilt). After pnpm --filter "@objectstack/client-react..." build it answered exit 0: "285 prose examples type-check across 3 surface(s)". The recorded code is the second run.
• Builds before the union, through scripts/pm/os-verify-lock.sh: @objectstack/spec... and @objectstack/lint... (VERDICT command-exit 0), then @objectstack/client-react... (VERDICT command-exit 0).
• pnpm lint: the diff touches no package, so there is no scoped package lint.
• CI's own steps the derivation names as NOT MEASURED locally (ci.yml Build Docs, Plan Test Core shards, the type-check lanes) are read from this PR's check-runs, not re-run here.

skip-changeset: content/docs/** is published by no package.

Human Minimum

• 1. Schemas start as Zod; packages/spec holds no runtime logic. (not touched)
• 2. Every name I added uses the casing for its kind. (no names added)
• 3. No formatter ran; pnpm lint passes. (no package touched)
• 4. One issue, one branch off an up-to-date main, one pull request.
• 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset. (publishes nothing: skip-changeset)
• 6. packages/spec touched: its generated artifacts are regenerated and committed. (not touched)
• 7. No hand edits to content/docs/references/, packages/*/CHANGELOG.md or content/docs/releases/.
• 8. Title, body and comments are in English. (the 维护者速读 block is the lane's required Chinese summary)
• The Before Submitting list in CONTRIBUTING.md is done.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FEkQ5kuCuTK9UtGmuBcaPR

---

Generated by Claude Code

[objectstack-fleet]

domain:devx#3 · os-project-manager · session_01FEkQ5njkh3xbcDN6EtSfw7

席位核对

Verdict: ACCEPT · head ef2c1811a43438758e90fe82dda7db1fb3a7f175 · card #31339 · report 6716929831.

• Shape: draft → main, Fixes #31339. One file, content/docs/deployment/cli.mdx, +10/-4, inside the claim's surface. NOT governed.
• Card's ask, checked line by line against packages/cli/src/commands/deploy.ts on main:
  • Flag row: the --confirm-upgrade <token> row matches the flag at L149–153. It is self-hosted only and refused on ObjectOS Cloud, the same loop as --confirm-access-upgrade at L169.
  • Step 3: both flags are passed through to the install (L338–339), and each refusal names its own retry (L105–106, L147).
  • Step 4: a package that is recorded but not loaded is not live. It loads on restart and the command exits 1 (L346–352).
• Eval 21 left alone: PR docs: teach os mcp connect and the use-runtime deploy target in the remaining pages #31335 was still open at start, as the order said. It is named in out_of_scope_findings, with docs: teach os mcp connect and the use-runtime deploy target in the remaining pages #31335 as the carrier.
• Gates: 44 derived, 44 exit 0, 0 NOT MEASURED. Check-runs on this head when read: 16 success, 19 skipped, 8 in progress, 0 failed. Automerge waits for the required contexts.
• Changeset: docs only ⇒ skip-changeset. Clause-②: no. No contract review is owed.
• Landing: under 「按照 pm-dispatch 规则复核过的都授权」 (2026-10-25T11:35Z) and 「你应该使用 pm-dispatch 技能审核和落地pr」 (2026-11-07T16:59Z): pr_ready + automerge_enable now.