Repository navigation
Home is not optional — one home-resolution contract for the repo's tools #5762
Description
Home is not optional — one home-resolution contract for the repo's tools
Design doc: files/designs/code-home-resolution-contract.md in the
keep-the-four-repos-healthy goal workspace. Filed by the design
architect (pass 53, 2026-11-04). No user/review: the contract
generalises the repo's own two precedents (id world.rs hard error;
fleet-config #5473's empty-counts-as-unset ruling), and the one
judgment call the origins left open is recorded in the doc.
The defect
Three filings in two days are one defect with three addresses: a
tool that cannot find the user's home directory invents one, and
the invention differs per copy of the helper —
- Filesystem root — fleet-queue's client
home()
(unwrap_or_default()) anchors the broker socket, broker token
and worker-wake signal at/...when HOME is unset or empty
(fleet-queue(client): HOME unset/empty makes home() empty — broker socket, token, and worker signal paths all anchor at the filesystem root #5673); its brokers are loud on unset, silent on empty. - Current working directory — fleet-config's
home_dir()
falls back to".", so config/state/socket resolve CWD-relative
and a planted./.config/fleet/fleet.tomlis loaded, probe-
verified (fleet-config: HOME unset/empty falls back to "." — config, state dir, and broker socket resolve CWD-relative, and a planted ./fleet.toml loads #5737) — the HOME spelling of the hazard fleet-config: empty XDG env vars resolve to CWD-relative paths (a planted ./fleet/fleet.toml is loaded), and a relative FLEET_BROKER_SOCKET bypasses under-HOME resolution #5473 closed
for XDG in the same crate. - A literal
~directory — atlas-search / atlas-core /
fleet-search copy a helper mapping missing HOME to"~", so
atlas-search initexits 0 creating./~/.local/state/...
(atlas-search(fleet-search): HOME unset/empty resolves state/config/token paths relative to the CWD (literal ~ dir) #5640, probe-verified).
HOME is most often absent exactly where these tools run (cron,
minimal systemd units, env -i, containers), and in every
spelling the tool succeeds silently at the wrong place.
The contract (recorded decision)
A tool that needs the home directory resolves it exactly one
way: a non-empty HOME. Empty is unset. Unset is a named error
at the first surface that needs a path — never a substitute
directory.
- Empty = unset, for HOME itself as fleet-config: empty XDG env vars resolve to CWD-relative paths (a planted ./fleet/fleet.toml is loaded), and a relative FLEET_BROKER_SOCKET bypasses under-HOME resolution #5473 ruled for XDG/FLEET_*.
- Unset = fail loudly naming HOME (the world.rs precedent),
before any home-derived read/write/spawn/connect. No root
anchoring, no CWD fallback, no literal~, no hardcoded user. - One helper per deploy unit, shaped like fleet-config's
non_empty_path; one shared probe matrix (unset and empty
both error; set = exactly today's paths). - Absolute XDG/FLEET_* overrides keep working as fleet-config: empty XDG env vars resolve to CWD-relative paths (a planted ./fleet/fleet.toml is loaded), and a relative FLEET_BROKER_SOCKET bypasses under-HOME resolution #5473 left
them; relative/empty ones are not a home substitute.
Passwd resolution is declined as the default (the origins'
"or resolves the real home another way" either/or): it is
another silent substitution, it contradicts the in-tree
precedent, and fail-loud is recoverable in one line in the unit
while a wrong-home write is not recoverable at all. A surface
that can demonstrate a legitimate passwd-authoritative context
may record an exception on its own phase issue.
Phases (each independently landable)
- Phase 1 — fleet-config: fleet-config: HOME unset/empty falls back to "." — config, state dir, and broker socket resolve CWD-relative, and a planted ./fleet.toml loads #5737 (adopted; holds the
non_empty_pathprecedent the others mirror) - Phase 2 — fleet-queue: fleet-queue(client): HOME unset/empty makes home() empty — broker socket, token, and worker signal paths all anchor at the filesystem root #5673 (adopted)
- Phase 3 — atlas-search + fleet-search: atlas-search(fleet-search): HOME unset/empty resolves state/config/token paths relative to the CWD (literal ~ dir) #5640 (adopted)
- Phase 4 — closing inventory audit (filed with this design):
disposition every remaining home-resolution site on main —
pkgs/id/src/world_compile.rs:704(unwrap_or_default), the
JSbin/*hardcoded/home/userfallbacks, mcpx's discarded
os.UserHomeDir()errors, and any further copies the inventory
turns up. Same-shape sites fixed in-phase; genuinely different
contexts filed separately with the reason.
Acceptance
- All four phases closed or dispositioned with evidence.
- No production home-resolution site in the repo maps an
unset/empty HOME to a substitute directory. - Register (
files/potential-projects.md) and the mcpx/fleet
docs that describe these paths agree with the as-built rule.
Activity
developing-today commentedon Nov 5, 2026
CODE-1449
dezren39 commentedon Nov 5, 2026
🤖 Agent note · design filed
files/designs/code-home-resolution-contract.md(keep-the-four-repos-healthy goal workspace); register entry added infiles/potential-projects.md.dezren39 commentedon Nov 5, 2026
🤖 Agent note · handed off
opencodebyfleet queue lanefor task 10170; the laptop opencode claimant launches the bound session, which drives task 10170 to its terminal state. This lane does not work it directly.10 remaining items
dezren39 commentedon Nov 5, 2026
🤖 Agent note · handed off
dezren39 commentedon Nov 5, 2026
🤖 Agent note · handed off
developing-today commentedon Nov 5, 2026
🤖 Agent note · handed off
opencode(repeat handoff, attempt 3/6)dezren39 commentedon Nov 5, 2026
Agent note · picked up
repo-worker-code), OpenChamber scheduled laneheld,user/owned,do-not-merge,do-not-auto-edit). No matching open PR found.dezren39 commentedon Nov 5, 2026
Agent note - handed off
ses_e5e5345cfd6ffeyVUzL25fW7Jfdezren39 commentedon Nov 5, 2026
Triage — 2026-11-05
Disposition: #5762 remains open and actionable; it has no linked PR and is not superseded. The recorded contract is clear: require a non-empty HOME; treat empty as unset; raise a named error before using any home-derived path; preserve absolute overrides; do not substitute filesystem root, CWD, literal tilde, a hardcoded user path, or passwd lookup.
Current-main check: default branch main is c0b4ac6. Compared with the inspected checkout 5ca5cc8, main has three newer commits; the only changed production source path in that delta is unrelated pkgs/id/src/artifact.rs (the rest are docs). The cited HOME-resolution sites therefore remain in scope: fleet-config's home_dir() CWD fallback (#5737), fleet-queue client's empty home() (#5673), the atlas-search/atlas-core/fleet-search fallback copies (#5640), and remaining inventory sites in pkgs/id/src/world_compile.rs, bin/*, and mcpx (#5763). No tests/builds were run; this was triage only.
Ordering / blockers: phases 1–3 are already split into #5737, #5673, and #5640 and are independently landable; use #5737's non_empty_path behavior as the pattern. All three are open and currently labeled status/parked; the latest #5737/#5673 comments record fresh handoffs. Phase 4 (#5763) is open and status/blocked, with its latest triage explicitly gating the inventory audit until phases 1–3 land. Keep that gate; then disposition the remaining sites and complete #5762's acceptance. No additional dependency or design decision is needed to start the first three phases.