[roodboi]

The upgrade guide now records the first reported next.16 Compose trials: three existing v4.3.0 projects on macOS started, restarted and stopped with their .hack/ configuration unchanged, after one credential refresh and the startup reruns described in the guide. This follow-up to #746 is separate from security guidance PR #760.

It adds the seven findings reported by the lead on November 13, using generic wording:

• Stable installation stays in place, but candidate Compose uses the stable Hack home. The macOS launchd service needs stable daemon stop, then daemon uninstall; stable daemon install restores it later. The candidate Doctor hint naming stable hack daemon start must not be followed during the shared-home trial.
• Lifecycle hooks still run. A pre-up hook failed until its own cloud credentials were refreshed; its failure blocks up with E_LIFECYCLE_FAILED.
• next.16 can falsely report E_STARTUP_INCOMPLETE for a sub-second one-shot. Check real state before using the observed up -d rerun workaround; fix(compose): settle short one-shot startup observations (HACK-2168) #758 is an open fix intended for the next prerelease.
• Port 80 working does not establish HTTPS: another program listening on all addresses at 443 blocked loopback-resolved project hostnames. Proxy-container-address names were unaffected in the reported trial; Doctor does not yet detect this case.
• next.16 JSON env listings still disclose plain values. The fix(env)!: restrict value exposure and protect plaintext entries (HACK-2166) #767 listing/protect changes are prospective and breaking: has_value is for availability, while env get KEY is a deliberate plaintext read.
• A key-backup warning precedes migration. HACK-2172 affects explicit doctor --migrate-env-config cleanup when a legacy store's keyPath is .hack.secret.key. Implicit cleanup removes only migrated dotenv files, but still writes, so it also needs the existing backup precautions.
• next.16 Doctor already flags env-key-weak-permissions and suggests chmod 600. fix(env): secrets at rest: ignored staging, tightened modes, expiring mux payloads, doctor secrets hygiene (HACK-2165) #764 extends this with the broader hygiene report and fixes in a future prerelease.

The reported trials are observations supplied by the lead, not Mac acceptance tests performed by this docs session. v4.2.1, full application/data checks, migration, Linux/native qualification and rollback remain explicitly unconfirmed. Open fix PRs are not described as features of an installed next.16 bundle. No project names, host identities or private paths are included.

Source checks use the next.16 tag b21c3b189841c1a3cbb8af2b76414fa347dc7057 and branch point cce4b5954a4b1889b095bda796bea561142d6b52:

Behavior	Source
Candidate/shared-home/service boundary and misleading stable daemon hint	candidate-install.md
Lifecycle and incomplete-start errors	project.ts, #758
next.16 env-value disclosure; prospective output migration	env.ts, #767
Explicit versus implicit cleanup and the legacy key candidate	project-env-config.ts (collectLegacyEncryptedBackendCleanupCandidates, removeLegacyProjectEnvArtifacts, finishImplicitLegacyEnvMigration), doctor.ts
Existing weak-key diagnosis; prospective broader hygiene	doctor-env-key.ts, #764

Only the existing versioned guide changes. Navigation, the versions manifest, immutable release snapshots and the decision diagram remain unchanged.

Validation on pinned Bun 1.4.4:

• Docs prepare/check/typecheck and production build passed.
• HTTP smoke: 93 docs, isolated search/export routes, 37 diagram blocks served as 74 SVGs, 176 recipe links/anchors; published guide checked for all seven findings.
• All 50 pinned source-file citations verified; generated canonical routes passed HTTP checks.
• Privacy check and full HEAD-history Gitleaks scan passed (1,267 commits, no leaks).
• Persistent Claude Opus 5.5 review: clean at 4830e3f7ad0dca11b4d8c159aeecf70f92ed7fd0, after two rounds.
• No new runtime tests or live daemon, credentials, Docker or VM runs. The task-owned HTTP server was stopped after verification. Hosted Linux shards 4–8, including typecheck/privacy/quality, docs, models and secret scan are green in run 43392907053. Codex code and automatic security reviews are clean at this head; review-status is CLEAR with zero unresolved threads. macOS shards 1–3 remain queued, and the test aggregate awaits them. Docker/compiler/native-core work was scope-skipped.

---

^{Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.}

[vercel]

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

Project	Deployment	Actions	Updated
hack-docs	Ready	Preview	Nov 13, 2026 8:24am UTC

[linear-code]

HACK-1977

[roodboi]

@codex review

[chatgpt-codex-connector]

Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-11-13T08:25:41.677936Z	4830e3f	Manual request
🔒 Security Review	✅ Completed 2026-11-13T08:27:06.065206Z	4830e3f	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Nice work!

Reviewed commit: 4830e3f7ad

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: 4830e3f7ad

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

[roodboi]

Ready for lead: the next.16 upgrade-trial guide follow-up covers all seven reported findings, with the HACK-2172 key-backup warning before migration and unpublished fixes kept distinct from next.16. This is the separate one-page follow-up to #746; full v4.2.1 migration, application/data recovery and rollback remain unconfirmed.

Persistent Claude Opus 5.5 review is clean after two rounds. Codex code and automatic security reviews are clean at this head. Zero unresolved bot threads; computer pr review-status: CLEAR at 4830e3f.

Linux test shards 4–8 (including typecheck, quality and privacy), docs site, models and secret scan are green in run 43392907053. Hosted jobs still pending: macOS test shards 1–3 are queued; the test aggregate awaits them. Docker/compiler/native-core work was scope-skipped. The earlier cancelled run's aggregate failure is superseded by this active run. Local docs checks, production build, 93-page HTTP smoke and full-history Gitleaks passed.

One push; no freshness-only merge. Ready for your batch integration and merge.

4830e3f

[roodboi]

Blocked: The next.17 “what changed and what to do” draft is prepared locally, but #767 is still open and you asked me to wait for its merge before opening the follow-up PR. Could you signal here when #767 lands?

The draft covers native plain log-follow formatting, env metadata/explicit reads/protection/terminal reveal/stdin migration, and merged HACK-2172 key preservation with the key-backup warning retained for next.16 or earlier. It updates the release notes, both upgrade guides and docs/env.md. Docs generation/check/typecheck and privacy checks pass. No PR or push yet; final wording and review will use the merged #767 behavior. #768 receipt behavior remains explicitly pending unless that PR has also merged.