fix(cloud-connection,cli): the install-local ledger follows OS_HOME, so os dev --fresh starts without earlier installs - #30351

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/cli, @objectstack/cloud-connection, touching 24 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/cloud-connection/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/automation/flows.mdx (via os doctor (command, read off packages/cli/src/commands/doctor.ts))
• content/docs/automation/jobs.mdx (via os doctor (command, read off packages/cli/src/commands/doctor.ts))
• content/docs/data-modeling/drivers.mdx (via OS_MULTI_ORG_ENABLED (literal, a string literal in DOCTOR_ENV_INPUTS), OS_TENANCY_POSTURE (literal, a string literal in DOCTOR_ENV_INPUTS))
• content/docs/data-modeling/indexing.mdx (via os doctor (command, read off packages/cli/src/commands/doctor.ts))
• content/docs/deployment/backup-restore.mdx (via OS_HOME (literal, a string literal in DOCTOR_ENV_INPUTS))
• content/docs/deployment/cli.mdx (via MarketplaceInstallLocalPlugin (symbol, a top-level class), OS_HOME (literal, a string literal in DOCTOR_ENV_INPUTS), OS_TENANCY_POSTURE (literal, a string literal in DOCTOR_ENV_INPUTS), os doctor (command, read off packages/cli/src/commands/doctor.ts))
• content/docs/deployment/environment-variables.mdx (via OS_HOME (literal, a string literal in DOCTOR_ENV_INPUTS), OS_MULTI_ORG_ENABLED (literal, a string literal in DOCTOR_ENV_INPUTS), OS_TENANCY_POSTURE (literal, a string literal in DOCTOR_ENV_INPUTS), os doctor (command, read off packages/cli/src/commands/doctor.ts))
• content/docs/deployment/production-readiness.mdx (via os doctor (command, read off packages/cli/src/commands/doctor.ts))
• content/docs/deployment/tenancy-modes.mdx (via OS_MULTI_ORG_ENABLED (literal, a string literal in DOCTOR_ENV_INPUTS), OS_TENANCY_POSTURE (literal, a string literal in DOCTOR_ENV_INPUTS))
• content/docs/plugins/packages.mdx (via OS_MULTI_ORG_ENABLED (literal, a string literal in DOCTOR_ENV_INPUTS), OS_TENANCY_POSTURE (literal, a string literal in DOCTOR_ENV_INPUTS))
• content/docs/protocol/backward-compatibility.mdx (via os doctor (command, read off packages/cli/src/commands/doctor.ts))
• content/docs/protocol/kernel/config-resolution.mdx (via os doctor (command, read off packages/cli/src/commands/doctor.ts))
• content/docs/protocol/kernel/http-protocol.mdx (via os doctor (command, read off packages/cli/src/commands/doctor.ts))
• content/docs/protocol/objectql/schema.mdx (via OS_TENANCY_POSTURE (literal, a string literal in DOCTOR_ENV_INPUTS))
• content/docs/upgrading.mdx (via OS_TENANCY_POSTURE (literal, a string literal in DOCTOR_ENV_INPUTS))

⛔ 7 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v16.mdx (via os doctor (command, read off packages/cli/src/commands/doctor.ts))
• content/docs/releases/v17/17-1.mdx (via OS_TENANCY_POSTURE (literal, a string literal in DOCTOR_ENV_INPUTS))
• content/docs/releases/v17/17-3.mdx (via OS_TENANCY_POSTURE (literal, a string literal in DOCTOR_ENV_INPUTS))
• content/docs/releases/v17/17-4.mdx (via OS_TENANCY_POSTURE (literal, a string literal in DOCTOR_ENV_INPUTS))
• content/docs/releases/v17/17-5.mdx (via os doctor (command, read off packages/cli/src/commands/doctor.ts))
• content/docs/releases/v17/17-7.mdx (via OS_TENANCY_POSTURE (literal, a string literal in DOCTOR_ENV_INPUTS))
• content/docs/releases/v18/index.mdx (via OS_MULTI_ORG_ENABLED (literal, a string literal in DOCTOR_ENV_INPUTS), OS_TENANCY_POSTURE (literal, a string literal in DOCTOR_ENV_INPUTS))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 1bba927bfdd4ff03383a1fa58a712eb59afc6900 && git checkout 1bba927bfdd4ff03383a1fa58a712eb59afc6900
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin d1d90b7062af18eda616f875f9efc1ffeaac645a 2e2ebc4089991d0f1c833149f20d6385067fae2e && git checkout -B drift-repro d1d90b7062af18eda616f875f9efc1ffeaac645a && git merge --no-ff 2e2ebc4089991d0f1c833149f20d6385067fae2e

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

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 d1d90b7062af18eda616f875f9efc1ffeaac645a → pass the list as
args.docs, on the commit named under Which tree this was computed on.

domain:server#3 · os-bill · session_01Utp6CbPxYq1wQmUNWvMZkC

Contract review

Served-tier: TIER_DEFAULT
Head-sha: 299ca6ddb2a8748be8191820b22fd21f306b31e2
Local-runs: none
Scope: packages/cloud-connection/src/local-manifest-source.ts, packages/cloud-connection/src/index.ts, packages/cloud-connection/src/marketplace-install-local-plugin.ts, packages/cli/src/commands/doctor.ts, packages/cli/src/commands/dev.ts, .changeset/30217-install-ledger-follows-os-home.md

Face: declaration (Clause-②: yes (widening) line-initial on the PR body and the changeset). No published schema, no governed path, no narrowing in the committed tree, so the lane seat records this review at TIER_DEFAULT. Reads: the full diff, card #30217 (claim 6650344744, amendment 6650402032, os-dev report 6652012535), the PR body.

① Derived judgments

1. Public surface widened. @objectstack/cloud-connection's index newly exports INSTALLED_PACKAGES_HOME_SUBDIR, FRESH_HOME_CHANNEL_ENV, resolveInstalledPackagesDir and the types InstalledPackagesLocation, LegacyLedgerAdoption; LocalManifestSource gains readonly legacyDir and adoptLegacyEntries(). DEFAULT_INSTALLED_PACKAGES_DIR stays exported with the same value. No signature narrows (the constructor still takes an optional storageDir), so yes (widening) is the right declaration.
2. Where the ledger lives. resolveInstalledPackagesDir: OS_HOME unset → CWD/.objectstack/installed-packages (unchanged); set → OS_HOME/installed-packages; os start project mode (OS_HOME = CWD/.objectstack) resolves to the old directory and adopts nothing (dir === legacy). An explicit storageDir is used as given and adopts nothing.
3. Adoption. Copy-only, once (only while the new directory is absent), staged in a sibling mkdtemp and renamed into place, staging removed on failure; old files never deleted. A failed copy is an error log naming both directories, not a boot refusal; a done copy is a warn. Readers (list, read, os doctor) never write.
4. --fresh. os dev sets OS_INTERNAL_FRESH_HOME on the serve child only under --fresh and deletes an inherited copy otherwise; the resolver honours it only when it names the same home, so a stale inherited value cannot suppress adoption elsewhere. The two spellings (cli constant, cloud-connection constant) are held equal by dev-fresh-home-channel.test.ts.
5. os doctor. Reads resolveInstalledPackagesDir (under the .env* overlay, with OS_HOME added to DOCTOR_ENV_INPUTS) instead of joining cwd with the string, so doctor and the runtime read one directory; a resolver that throws is a readerFailure row, a missing function the existing dirAuthorityMissing row.

② Semver level

@objectstack/cloud-connection and @objectstack/cli patch: AGENTS.md step 3, a non-protocol change (widening) ships patch; Metadata-protocol: none. Nothing removed or refused, so no BREAKING banner and no ADR-0087 disposition are owed. The changeset's "Existing installs" bullet states the move and the one-time copy an operator sees.

③ Boundary flags

• Seat 4's p1 Seed.locale: marketplace install, reseed sample data and per-org replay should select datasets by the installing organization's locale #30281 touches runInlineSeed in marketplace-install-local-plugin.ts; this diff does not (constructor-adjacent rehydrate start and a new private method only).
• serve.ts unchanged (the default now resolves correctly without a storageDir).
• A shared OS_HOME used from several projects adopts the first project's cwd ledger once; the changeset tells the operator to remove the old directory. Noted, not a defect of this card.

Implemented-by: claude/project-thread-14pct9
Reviewed-by: session_01Utp6CbPxYq1wQmUNWvMZkC

VERDICT: PASS

domain:server#3 · os-bill · session_01Utp6CbPxYq1wQmUNWvMZkC

Contract review

Served-tier: TIER_DEFAULT
Head-sha: 2e2ebc4089991d0f1c833149f20d6385067fae2e
Local-runs: none
Scope: packages/cli/test/package-install-local-jobs-pull.integration.test.ts, packages/cli/test/package-install-local-hooks.integration.test.ts

Delta review by the lane seat, PR #30351 (card #30217), declaration face. Previous record on 299ca6ddb2a8748be8191820b22fd21f306b31e2 (PR comment 6652045064): PASS. That head then went red on Test Core (4/8) (job 127104154080, package-install-local-jobs-pull.integration.test.ts:464/:476) and Test Core (1/8) (job 127104154082, package-install-local-hooks.integration.test.ts:495/:502). This record judges the one commit 299ca6dd → 2e2ebc40 (test(cli): write the earlier build's ledger entry into the home's ledger); every item of the earlier record the delta does not touch stands as written there.

① Derived judgments

• Cause of the red, owned by this PR. Both fixtures boot twice with --home <runtimeDir>/home and, between boots, planted the "earlier build" entry in join(runtimeDir, '.objectstack', 'installed-packages'). Under this PR the ledger is OS_HOME/installed-packages; boot 1's installs already created it, so the one-time adoption (new directory absent) does not run and boot 2 never read the planted entry: the rehydrated object answered 404, the bindable pull job was not scheduled, and no withheld-item warn printed. That is the behaviour the earlier record describes (judgment 3), so the fixtures, not the source, were stale.
• The fix. Each fixture now plants the entry in join(home, 'installed-packages'), the directory the runtime reads, with a two-line note citing install-local: the cached-manifest directory is resolved from the working directory, not OS_HOME, so os dev --fresh rehydrates a previous install #30217. Test intent (an entry an earlier build wrote is rehydrated; its unbindable item is withheld by name) unchanged; assertions unchanged; no source file touched.
• No third site. The dev's repo-wide grep finds the cwd-ledger join only in the doctor unit tests (posture-independence, dir-authority, read-failure), which pass no --home and set no OS_HOME, so the cwd ledger is the right reading there; read-failure's OS_HOME case already reads the home ledger.

② Semver level

Unchanged: @objectstack/cloud-connection and @objectstack/cli patch; test-only delta.

③ Boundary flags

• Adoption-from-cwd stays covered by the cloud-connection unit tests from the earlier head; these two integration files now cover rehydrate under a home ledger, which is what they always meant to.
• CI on 2e2ebc40 still running at this reading; landing waits for green.

Implemented-by: claude/project-thread-14pct9
Reviewed-by: session_01Utp6CbPxYq1wQmUNWvMZkC

VERDICT: PASS

domain:server#3 · os-bill · session_01Utp6CbPxYq1wQmUNWvMZkC

席位核对

ACCEPT · head 2e2ebc4089991d0f1c833149f20d6385067fae2e · card #30217 (claim 6650344744, amendment 6650402032) · 2026-11-05T07:54Z

• Shape: draft PR to main, author objectstack-fleet[bot] (relay), attribution block then Fixes #30217. 13 files, +651 −72. check-governed-merges.mjs --pr 30351: NOT governed, 723 changed lines ≤ 3000 ⇒ ordinary queue landing.
• Declarations: Clause-②: yes (widening), Metadata-protocol: none; changesets @objectstack/cloud-connection patch and @objectstack/cli patch (AGENTS.md step 3: a non-protocol widening ships patch). No BREAKING banner owed.
• Review of record: seat TIER_DEFAULT record PASS on 299ca6dd (6652045064) and delta record PASS on 2e2ebc40 (6652363537). The delta is the two integration fixtures that planted the "earlier build" entry in the cwd ledger under --home; they now plant it in the home's ledger the runtime reads. Test-only, source unchanged.
• Gates (check-runs on this head): 48 runs, 35 success, 13 skipped, 0 failed; Test Core ×8 + aggregate (red on 299ca6dd, jobs 127104154080 / 127104154082) now green. Skips read by name (path-gated, opt-in harnesses): check-expected-skips.mjs cannot run in this container (yaml not installed).
• Accepted deviation: two commits after the first report (changeset path spelling; the fixture rework), no force-push.
• Landing: ready + auto-merge by the seat.