host-cli-source-activation-v0.md

Host CLI source activation v0

This is an explicit Docker operation adapter for an existing benchmark-toolkit controller. It changes the versioned CLI used by future subprocesses while the running Host keeps its imported modules. It is not a new execution provider, Goal operation, application setting or automatic update service. App, Lark, ordinary CLI and existing checkpoint callers do not invoke it by default.

Owners and entrypoints

benchmark.edgebench.cli_source_activation.activate_cli_source provides preview, execute and exact-intent reconcile. The controller supplies its current ordinary Stop, phase and resource observations; none of these methods grants a run slot, work admission, account authority or additional allowance.

The registered TypeScript handler benchmark.cli_source_activation qualifies the boundary and chooses permitted readback/repair effects. Python adapts Docker pause/archive and persists transport acknowledgements. Its journal phases remain local to this adapter, separate from Goal, Todo, quota and native-session state. The existing quota settlement, registry activation, native-history, source archive and physical worker-lock owners retain their semantics.

The operation requires an exact daemon/container/start identity, original Goal/Agent/Todo/Turn/native session and registry route, the owned launcher path and uid/gid, distinct versioned old/new targets, and the qualified new revision/archive digest. Targets have the existing releases/<id>/scripts/loopx layout. The launcher must be a physical Linux-profile symlink with its original ownership and mode. A different launcher, namespace or ownership is a failed compare, never overwrite permission.

1. Produce the canonical archive with benchmark.runtime.source.archive_source from the independently qualified clean revision. StagedCliRelease.stage previews by default. Explicit staging creates a fresh versioned directory, verifies every declared byte/mode/member and never promotes the launcher or runs the full installer. Implicit physical tar parent directories are allowed; escaping links, symbolic parents and unexpected executable/source members are rejected. Preserve a partial upload; do not overwrite it as a retry.
2. Compose a PausedSourceProbe from the original runtime's explicit participants, native checkpoint store inventory, state-backup authority inventory and qualified immutable reader dependencies. Its exact passive-process manifest comes from the owned Host contract, not learning every process of a busy source as idle. A passive app-server is not by itself an outstanding model request.
3. Preview activate_cli_source(..., execute=False). On explicit execution it takes the same daemon/full-container worker lock as the old checkpoint Host, in the same controller user's physical filesystem realm. It does not create a controller-ready request, checkpoint identity or capture attempt.
4. A bounded preflight rejects busy/ready/unknown candidates before pausing. After the pause, the observer reads an isolated, network-disabled copy with existing owners. It verifies the exact original settled identity, no pending Host attempt, stable completed native history, no unfinished native effects, no unknown processes and an unchanged source witness. SQLite WAL/journal files participate. Credential homes/auth are excluded; source work never executes in the observer. Work, research, authority, hooks, native configuration, profile and original phase participants remain in place.
5. Persist the private intent before changing the launcher. Docker archive upload is not a filesystem-atomic rename. The physical pause and shared lock make this change atomic with respect to dispatch. Verify the complete target and current Stop again, write the symlink with its original uid/gid, then read back its exact identity and unchanged protected source before releasing the pause.

The probe declaration is an integration input, not another saved product policy. source_goal_control reads the existing registry codec/activation owner. The caller must combine it with its ordinary current controller/phase/resource Stop path. A cached profile flag or a prepared deadline is not a current guard.

Failure, Stop and recovery

The private, physical, owner-only receipt is the operation's transport readback. Keep it and the exact plan. reconcile=True never replays an already released operation, starts a model, reruns a guard or rewrites work state. A released receipt returns an explicitly historical/replayed projection with current source ownership and model adoption unverified; it is not a fresh activation guard.

• A busy or rejected paused observation can resume only the known original launcher under current ordinary control, without an installation change.
• Stop before pause makes no effect. Stop during the transaction keeps the source held for the ordinary Stop owner; a generic finally must not resume it.
• A lost write acknowledgement is resolved by actual old/new readback. A partial, missing or foreign launcher stays paused. Explicit repair="old" or "new" needs the same qualified unchanged source and current control; it repairs only the launcher transport, never native history, work or a model dispatch.
• A lost release acknowledgement reconciles the running source and exact target without another unpause or dispatch. An uncertain pause acknowledgement remains held for explicit ownership recovery; the adapter cannot release another actor's pause by guessing. A pending request, unknown/partial phase or missing durable pause acknowledgement cannot acquire ownership of an observed pause.
• Process death or an unavailable probe leaves a durable intent. Preserve the original namespace and reconcile it; do not create a second activation identity or use an old checkpoint as rollback.

A clean deferred/released-old result did not install the new CLI. A subsequent candidate requires a fresh current boundary and intent after the prior operation is known released. It cannot reuse historical qualification; an uncertain prior operation remains held and must be reconciled first.

All setup and pause time remains charged to the original finite allowance. The adapter records actual pause wall time and never resets, refunds, extends or regrants the phase. Native counters, cooldown, evaluator and incumbent are not called or changed by installation.

Adoption and compatibility

The released receipt is a source amendment for the controller's existing run lineage: old imported Host plus the exact new CLI/kernel. It is not a whole-Host upgrade, a native restore or proof that a model consumed the new behavior. Keep the original frozen profile/digests and earlier source segment. The controller must retain the amendment with future source/checkpoint provenance.

Qualify the actual old Host's next wake, including checkpoint preflight, hook preparation/SessionStart, child Python source, TypeScript runtime fingerprint and the same-session model-visible input/readback. Preserve the actual publisher's manual/composed settlement contract and prove original identity, one debit and replay behavior. Do not select a new execution arm or invent a validator to make an update appear enabled. A schema label, installed file or running container alone is not semantic adoption or an effectiveness/cost improvement.

中文边界

这是现有 benchmark-toolkit controller 的显式 Docker 操作适配器，不增加产品设置、 执行臂、预算或 Goal/Todo owner。运行中的 Host 保留已导入代码；新 CLI 仅影响后续子进程。 默认不执行；当前 App/Lark/普通 CLI 与旧 checkpoint 行为保持原调用边界。

必须先在同一物理 worker 锁下筛选，再暂停后重新用原生会话、真实 settlement 和状态 owner 验证原身份已结算且无未决工作。不能将常驻 app-server、最近一次成功状态或旧 checkpoint 当作当前静止证明。新源码先独立安装验证，只对 owned launcher 做精确比较 后切换；不复制认证，不改原 profile、工作区、状态、原生机会或有限时钟。

写入中断或回执丢失必须读回原/新目标；未知目标保持暂停。Stop 优先，禁止在通用清理 分支盲目恢复。恢复只处理同一操作的物理传输，不重发模型、guard、准入或结算。实际 暂停成本不返还。交付记录明确混合版本，并由原 controller 保存 source amendment； 下一自然输入和真实读回另证采用，不能把安装成功、v1/v2 标签或测试数当作收益。