fix(runtime-host): keep the preferred location when registering a project path

[jsiu93]

Summary

Project preference is derived from location usage (newest lastUsedAt among available locations), and registration wrote the registration timestamp into the location it touched. So runtime-host project add <second checkout> also selected that checkout, and every later project-targeted Session started there.

This adds an optional prefer field to the project.register request. Omitted or true keeps today's behavior; false adds or refreshes a location without recording usage (a new location is stored with lastUsedAt: 0, an existing one keeps its timestamp). A new project still establishes its sole location as the initial preference.

The CLI runtime-host project add now sends prefer: false by default and gains --prefer for callers who mean to select the path. Desktop is unchanged: its registration call sites omit the field, so the folder-open flow (register, then create a project-targeted Session in that folder) behaves as before.

Fixes #3572

Review focus

Opened as a draft for a design check before review effort goes in. Two decisions here are yours to make, and I would rather adjust than argue:

1. Shape of the API. This puts an optional prefer on the existing project.register request, so project add stops selecting by default and --prefer opts in. The alternative is to keep registration as it is and add a separate "use this location" operation (a project use <path> verb), which matches how docker context use or kubectl config use-context separate creating from selecting. Both need the same epoch bump; I picked the smaller diff.
2. The compatibility epoch bump (41 to 42) for a CLI default. If you would rather not spend an epoch on this, say so and I will reduce the PR to the issue plus the storage test coverage.

Compatibility epoch

Bumped from 41 to 42. The registration request is a closed shape, so an epoch-41 Host rejects the new field and a new CLI always sends it. Precedent: 8346fbb92 bumped 36 to 37 when an optional text field was added to another exact catalog request.

Verification

New regression tests, all red before the change and green after:

• storage project-catalog.test.ts: a second location registered with prefer: false leaves preferredPath unchanged; re-registering the non-preferred location with prefer: false leaves it unchanged; registration with the option omitted still selects the path; a later touch on the new location makes it preferred; a new project still gets its sole location as preference.
• runtime-host project-catalog-protocol.test.ts and project-catalog-coordinator.test.ts: project.register accepts prefer: false and the returned record keeps preferredPath; a non-boolean prefer is rejected; protocol.test.ts pins epoch 42.
• cli runtime-host-operator-command.test.ts: project add sends prefer: false by default and prefer: true with --prefer.

Suites, on Node 24.19.0 (the version main CI uses):

npm --workspace @maka/storage test       # tests 914, pass 900, skipped 14, fail 0
npm --workspace @maka/runtime-host test  # tests 1113, pass 1113, fail 0
npm --workspace maka-agent test          # tests 401, pass 401, fail 0

Typecheck passed in the three workspaces. biome lint and biome format reported no fixes on the 12 changed files; git diff --check clean.

Live, fresh Host roots, worktree named aaa-worktree so it sorts before repository:

CLI from main:     add repository, add aaa-worktree  -> preferredPath: aaa-worktree
CLI from this PR:  add repository, add aaa-worktree  -> preferredPath: repository
CLI from this PR:  add aaa-worktree --prefer         -> preferredPath: aaa-worktree

Not run: full monorepo npm test, root-wide typecheck/lint/format, Desktop suites, Windows or Linux.

AI use

Select exactly one:

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope: pi (gpt-5.6-sol) traced the storage, protocol, Desktop and Session-creation paths, wrote the implementation and the regression tests, ran the live and compatibility checks, and drafted this description. Claude Code chose the design, reviewed the diff, re-ran the three suites, and edited this text. The commit carries the trailer.

Generated-by: pi (gpt-5.6-sol)

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

[Astro-Han]

Reviewed exact head f896059. Coverage: storage registration preference semantics across existing/new linked-worktree locations and later touch; Runtime Host protocol/coordinator defaulting and strict boolean decoding; CLI default and explicit --prefer transport; existing Desktop callers retaining prefer-by-default behavior; catalog ordering, path normalization, and transactional mutation paths. Exclusions: real multi-process CLI/Desktop smoke testing and visual/UI behavior. Local Core→Storage→Runtime Host→CLI builds passed, with 78 focused tests green; hosted exact-head test is green. No P0–P3 findings. The branch currently conflicts with main only in packages/runtime-host/src/protocol/index.ts; resolution should preserve both compatibility additions/comment blocks and advance from current main epoch 43 rather than choosing the PR epoch 42 verbatim.

[Astro-Han]

Incremental re-review at exact head 2b639688040c317eef75b1d96a1e01be07fc3b4c. APPROVE — no P0–P3.

This confirms the earlier approval, which was bound to f896059b. I did not re-review the whole change; I verified that the only difference since that approval is the epoch realignment, and that it is correct.

What changed since f896059b

Comparing each file's patch content against its own merge-base (efddab2f then, 84ed9a31 now), 11 of the 12 touched files have byte-identical patches. The single difference is in packages/runtime-host/src/protocol/index.ts:

• RUNTIME_HOST_COMPATIBILITY_EPOCH moved from 42 to 45
• the ledger comment was re-anchored from "Epoch-41 Hosts" to "Epoch-44 hosts", and the intervening 44 / 43 entries from main were kept

Why 45 is the right value

Current main (04836d3b8) is at 44. 45 is the next value, so the monotonic-progression rule holds and no Host that speaks 44 will silently accept the new optional location field on the closed registration input.

One merge-order caveat for maintainers, not a defect in this PR: #3467, #3316, #3376, #3651 and #2521 are also currently claiming 45. Whichever merges first advances main; the rest will need to re-bump. That is inherent to a single global counter, not something this author did wrong.

Gates at this exact head

• test — terminal success
• mergeable — MERGEABLE / CLEAN
• unresolved review threads — 0
• the check set is the correct triggered set for these paths

中文

在 exact head 2b639688 上做的增量复审，结论 APPROVE，无 P0–P3。原批准绑在 f896059b，本次不重审全量，只核"自那次批准以来变了什么"。

各文件对各自 merge-base 的 patch 逐一比对：12 个文件里 11 个逐字节相同，唯一变化是 protocol/index.ts 的 epoch 42→45 与注释重排。main 现在是 44，45 单调正确。

提醒（非本 PR 缺陷）：#3467、#3316、#3376、#3651、#2521 目前都在争 45，谁先合谁把 main 推上去，其余需要重新递增。这是全局单调计数器本身的性质。

门禁：test 终态绿、CLEAN、零未决线程。