feat(runtime-host): schedule managed update reconciliation

[me2seeks]

English

Summary

• install an OS-owned hourly wake-up for each Maka-managed Runtime Host deployment on Linux (systemd --user) and macOS (LaunchAgent)
• keep the user-selected cadence in the installation-scoped update policy: automatic policies accept 1h through 168h and default to 6h; manual performs no registry discovery or mutation
• gate scheduled invocations before registry access, while an explicit service reconcile-update remains an immediate user-requested check
• reuse feat(runtime-host): add managed update reconciliation #3720's stable managed operator, exact candidate discovery, compatibility admission, active-work boundary, and update transaction instead of introducing an updater daemon or a second mutation authority
• compose scheduler install, verification, logs, rollback, repair, and uninstall with the existing service lifecycle; version cutover does not rewrite the stable schedule
• spread hourly wake-ups and due phases deterministically by installation identity, and normalize pre-cadence policy records to the 6h default

Only a Maka-managed deployment receives this schedule. A transient npx invocation does not become background update authority by itself; an explicit managed setup does. Persistent global-CLI services and SSH clients do not acquire replacement or remote deployment authority.

Builds on #3720, now merged. This branch is rebased onto the merge and contains only the scheduler/cadence change.

Refs #3228
Refs #3709

Verification

• npm --workspace maka-agent test — 457 passed after rebasing onto merged feat(runtime-host): add managed update reconciliation #3720
• npm run lint
• npm run format:check
• npm run typecheck (after building the UI declarations required by Desktop)
• npm run check:asf-headers

Review focus

• the OS scheduler is only a wake-up adapter; the update policy remains the cadence authority
• scheduled manual and not-due paths return before registry access
• lifecycle rollback and uninstall remove the scheduler without allowing a remote Client, PID, version, or Host epoch to become deployment authority

AI use

Select exactly one:

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

Tool(s) and scope: OpenAI Codex implemented, tested, documented, and simplified the change under maintainer direction. Human review is required before merge.

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

简体中文

摘要

• 为 Linux（systemd --user）与 macOS（LaunchAgent）上的每个 Maka 托管 Runtime Host deployment 安装由操作系统持有的每小时唤醒任务
• 检查周期仍由 installation-scoped update policy 持有：自动策略可配置 1h 至 168h，默认 6h；manual 不执行 registry discovery 或 mutation
• 定时调用会在访问 registry 前判断是否到期；用户显式执行 service reconcile-update 则始终立即检查
• 复用 feat(runtime-host): add managed update reconciliation #3720 的稳定 managed operator、精确候选发现、兼容性准入、active-work 边界与 update transaction，不新增 updater daemon 或第二个 mutation authority
• 将 scheduler 的安装、校验、日志、回滚、repair 与 uninstall 组合进现有 service lifecycle；版本切换不重写稳定 schedule
• 按 installation identity 确定性分散每小时唤醒时间与到期 phase；旧版无周期字段的 policy 读取为默认 6h

只有 Maka 托管的 deployment 会获得该 schedule。一次临时 npx 调用本身不会成为后台更新 authority；用户显式执行 managed setup 才会创建它。持久全局 CLI service 与 SSH Client 都不会因此获得替换或 remote deployment authority。

基于已经合入的 #3720；当前分支已 rebase 到其 merge 之后，只包含 scheduler/cadence 变更。

关联 #3228
关联 #3709

验证

• npm --workspace maka-agent test — rebase 到已合入的 feat(runtime-host): add managed update reconciliation #3720 后 457 项通过
• npm run lint
• npm run format:check
• npm run typecheck（先构建 Desktop 所需的 UI declaration）
• npm run check:asf-headers

审查重点

• OS scheduler 只是 wake-up adapter，update policy 才是检查周期 authority
• manual 与尚未到期的定时路径都会在访问 registry 前返回
• lifecycle rollback 与 uninstall 会移除 scheduler，且 remote Client、PID、version、Host epoch 都不会因此成为 deployment authority

AI 使用

OpenAI Codex 在维护者指导下实现、测试、撰写文档并简化本次变更；合入前仍需人工审查。

Checklist

• 测试覆盖新增行为，并能在缺少实现时失败
• lint、format、typecheck 与受影响测试均已在本地通过
• 本 PR 会改变行为，具体见上方摘要

[Astro-Han]

I reviewed this head and found blocking issues.

[P2] Repair verifies authored files but not effective schedule

runtime-host-systemd-update-scheduler.ts:104-125 checks service/timer files and is-enabled/active, but an override override.conf changing ExecStart or OnCalendar still passes verification while the effective scheduler is different or inactive. Needs FragmentPath/DropInPaths checks like the Host service verifier.

[P2] Missed wake can defer checks by a full cadence

The scheduler decides due from modulo of current epoch hour with no last-check. For a 4h interval, a missed wake (sleep through phase) causes immediate timer run to be considered not_due, deferring next check by another full interval (up to nearly a week at 168h).

Minor note: combined scheduler+service log truncation can erase scheduler diagnostics when service logs are large.

Checks on c623ed60a are test: success.

简体中文

存在修复验证与调度遗漏两项阻断。

[M4n5ter]

Before reviewing the implementation details, could you clarify the product scope and canonical proposal?

1. [Tracking] Managed remote Runtime Host onboarding and lifecycle #3228 currently points to feat(runtime-host): schedule managed update reconciliation #3747 for this same scheduler slice. feat(runtime-host): schedule managed update reconciliation #3747 and feat(runtime-host): schedule managed update reconciliation #3750 share the same base, title, and user-facing goal, but there is no recorded supersession. Is feat(runtime-host): schedule managed update reconciliation #3750 intended to replace feat(runtime-host): schedule managed update reconciliation #3747? If so, what distinct user outcome justifies the second proposal rather than converging one PR?
2. What concrete workflow requires a managed Host to update while no Desktop or CLI is connected, and why are reconcile-on-connect, a service-start check, or an explicit update insufficient?
3. What current requirement needs a persisted, user-configurable 1h..168h cadence and an hourly scheduler installed even while the policy is manual, rather than one fixed low-frequency schedule installed only for an opted-in automatic policy?
4. Which service-stop contract is intended? feat(runtime-host): schedule managed update reconciliation #3747 stops/starts the scheduler with the Host service, while feat(runtime-host): schedule managed update reconciliation #3750 leaves the scheduler running after service stop; its later reconcile path can replace and start an inactive service.

These choices determine whether the added scheduler/cadence contracts are necessary and which implementation has the correct lifecycle owner, so I think they need to be explicit before line-level review.

[me2seeks]

English

Thanks — these questions expose a duplicate proposal, and the canonical answer is now clear.

#3747 was opened before #3750, and #3228 recorded #3747 as the scheduler slice before this PR was created. I missed that tracker update. #3750 is not intended to replace #3747, and after comparing both implementations there is no distinct scheduler outcome that justifies maintaining two proposals.

The concrete disconnected workflow is an opted-in automatic policy on a managed remote computer that may run without Desktop or a CLI Client attached. #3747 already provides that outcome by invoking #3720's bounded one-shot reconciler from a derived OS resource. Reconcile-on-connect and explicit update remain sufficient for manual policy; service-start-only discovery is insufficient for a long-running remote Host, but that does not distinguish #3750 from #3747.

The configurable 1h..168h cadence was an additional proposal in #3750, not a currently recorded requirement in #3228. It should not be used to justify a second scheduler implementation. The smaller current contract is #3747's fixed low-frequency schedule. Keeping that derived schedule installed in manual mode is reasonable because the one-shot command exits before discovery, while policy changes do not need to acquire platform-scheduler mutation authority.

#3747 also has the cleaner lifecycle contract: an explicit user service stop stops the whole managed deployment, including scheduling; the internal retire operation used during replacement stops only the Host process and preserves scheduling. #3750 incorrectly left scheduling live after an explicit stop. #3747's current head also verifies effective systemd fragments and rejects drop-in overrides.

I am therefore closing #3750 as superseded by #3747. I will not move the untracked configurable-cadence proposal into #3747. If a concrete product requirement for per-installation cadence is established later, it should be a separate follow-up proposal built on the canonical scheduler rather than a competing implementation.

简体中文

感谢指出。这些问题揭示了重复 proposal，现在 canonical 结论已经明确。

#3747 早于 #3750 创建，并且 #3228 在本 PR 创建前已经把 #3747 记录为 scheduler slice；我漏看了该 tracker 更新。#3750 并不应替代 #3747。比较两套实现后，也没有足以维护第二套 proposal 的独立 scheduler 用户结果。

具体的 disconnected workflow 是：用户为受管远端电脑启用自动策略后，即使 Desktop 或 CLI Client 没有连接，电脑仍能执行更新 reconciliation。#3747 已通过 OS 派生资源调用 #3720 的有界 one-shot reconciler 来满足该结果。manual policy 使用 reconnect reconciliation 或显式 update 已足够；仅在 service start 时检查无法覆盖长期运行的远端 Host，但这也不能区分 #3750 与 #3747。

#3750 中的 1h..168h 可配置周期是额外 proposal，并不是 #3228 当前记录的需求，因此不能用它支撑第二套 scheduler 实现。当前更小的契约是 #3747 的固定低频 schedule。manual 模式保留这一派生 schedule 也合理：one-shot command 会在 discovery 前返回，同时 policy 变化不需要取得平台 scheduler mutation authority。

#3747 的 lifecycle contract 也更干净：用户显式执行 service stop 时停止整个 managed deployment（包括 scheduler）；replacement 内部使用的 retire 只停止 Host process 并保留 scheduler。#3750 在显式 stop 后仍保留 scheduler 是错误语义。#3747 当前 head 也已经校验 effective systemd fragment 并拒绝 drop-in override。

因此我会关闭 #3750，由 #3747 取代。我不会把尚未形成正式需求的可配置周期塞入 #3747。如果以后建立了明确的 per-installation cadence 产品需求，应基于 canonical scheduler 单独提出 follow-up，而不是维护竞争实现。

[me2seeks]

Closing as superseded by #3747, per the scope analysis above.