Repository navigation
rollout(agent-mode): apply the shared control envelope across commands #323
Description
Depends on #333. This issue applies the approved envelope; it does not redesign it.
Summary
The first-adoption workflow still exposes command-specific machine interfaces. After #333 settles the compact permission/control shape, roll that single vocabulary across detect, init, doctor, scan, verify, and check.
Semantic boundary
scan,verify, andcheckmust project the existing authoritative release decision; no renderer may compute a second verdict.detect,init, anddoctorrun before a release decision exists. Their control state derives from setup facts such as detection confidence, manifest validity, and unresolved human-owned placeholders. The payload must identify that source explicitly.- Command-specific result fields remain available through the documented compatibility window.
Acceptance criteria
- All six commands expose the Define a compact, operationally unambiguous agent-control envelope #333 control-state and permission vocabulary in agent mode.
- Every non-complete state has one typed rank-1 action and optional ranked alternatives.
- Setup-derived and release-decision-derived control states identify their source and cannot be confused.
- JSON uses documented streams and is not split into incompatible stdout/stderr shapes.
- Existing command-specific schemas remain backward compatible through a stated migration window.
- An end-to-end Epic: make the adoption walk compose — preview → init --local-review → verify #327 adoption fixture routes every step using only the shared envelope.
- The rollout introduces no second verdict and no duplicate envelope schema.
Activity
pengfei-threemoonslab commentedon Aug 7, 2026
Triage note, and the important call on this one is that it is not new surface.
derive_agent_controlalready exists (core/agent_control.py:34) and already produces exactly the envelope this issue describes —state,completion_allowed,next_action,allowed_next_commands,human_review.verifyandcheckuse it.initdoes not:cli/_register_init.pyemitsnext_actionas a free-text string in most branches (:303,:340,:412,:517), with one branch that does produce a structurednext_actions=[action.model_dump(mode="json")]at:328.So the domain states are not merely "already shared" as the issue puts it — the implementation is already shared, and four commands simply bypass it. That reframes the work as applying an existing surface consistently, which lands on the right side of the
CONTRIBUTING.mdgate: "Deleting or consolidating surface never needs this new-surface justification." No headline metric is owed here. Reducing four transport shapes to one is consolidation.Two constraints worth writing into the design before implementation:
The envelope must project the decision, never restate it. The roadmap non-goal is "no second verdict — nothing gates independently of
release_decision.decision." Acontrol.stateonscanhas to be a projection of the existing decision, not a parallel judgement computed in the renderer. #318 is a live example of what happens when a projection starts deciding for itself.initanddoctorhave norelease_decisionto project. They run before or outside a scan, so theircontrol.statederives from a different source — placeholder state, manifest validity, detection confidence. That is legitimate but needs stating explicitly, or the same field will mean "the gate says" in one command and "setup says" in another, which is the ambiguity this issue exists to remove. #325 is effectively the first instance of that question and should be settled here rather than separately.Sequencing suggestion: settle the
initcontrol semantics as part of #325 (which needs a decision anyway), then generalize. Doing #323 first risks fixing the transport while leaving the state vocabulary underspecified.Labeled P1 / v0.17.0.
pengfei-threemoonslab commentedon Aug 7, 2026
Milestone and scope update: this issue is merging into #333, which stays in v0.17.0 as part of the control-plane foundation.
The two are the same surface approached from opposite ends — this one horizontal (make
init,doctor,scan,detect,verify,checkall speak one vocabulary), #333 vertical (make that object compact and unambiguous about what is permitted). Both land incore/agent_control.pyandschemas/agent_control.py. Building them separately produces two envelope definitions and a migration between them.#333 absorbs the scope because the compact/permission model is the harder constraint; the horizontal rollout is mechanical once the shape is fixed. The two constraints raised here carry over verbatim and are restated on #333:
release_decision, never restate it (roadmap non-goal: no second verdict);initanddoctorhave norelease_decisionto project from, so their control state derives from setup facts — which must be stated explicitly orcontrol_statemeans two different things depending on the producing command.Keeping this issue open as the horizontal-coverage checklist against #333's shape; it moves to v0.18.0 as the rollout step, with the design decided in v0.17.0. Close it in favour of #333 if you would rather track that as one item.
[-]ux(agent-mode): expose a common control envelope across init, doctor, scan, and verify[/-][+]rollout(agent-mode): apply the shared control envelope across commands[/+]feat(control): add the compact shipgate.agent_control/v1 control enve…
feat(control): add the compact shipgate.agent_control/v1 control enve…
fix(agent-mode): close the setup control review findings (#323)
fix(agent-mode): close the second-round setup control findings (#323)
merge: resolve #370 manifest-scope conflicts with the setup control e…
fix(agent-mode): drop the edit variant and close the remaining setup …
fix(agent-mode): type the setup edit on the envelope and close the fi…
fix(agent-mode): make the envelope's exactness claims true (#323)
feat(agent-mode): roll the shared control envelope across the setup c…
fix(agent-mode): close the first review round on the setup failure ro…
fix(agent-mode): close the first review round on the setup failure ro…
fix(agent-mode): a refused run must not lose what it was asked for (#323
feat(agent-mode): finish the control-envelope rollout and prove the w…
fix(agent-mode): close the first review round on the setup failure ro…
fix(agent-mode): a refused run must not lose what it was asked for (#323
fix(agent-mode): the direction owns the pack change, not the caller (#…
feat(agent-mode): finish the control-envelope rollout and prove the a…