@team-agent/installer 0.5.124 → 0.5.126

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (151) hide show
  1. package/Cargo.lock +1 -8
  2. package/Cargo.toml +1 -1
  3. package/README.md +2 -2
  4. package/README.zh.md +2 -2
  5. package/crates/team-agent/Cargo.toml +0 -1
  6. package/crates/team-agent/src/cli/diagnose.rs +39 -69
  7. package/crates/team-agent/src/cli/emit.rs +45 -15
  8. package/crates/team-agent/src/cli/intent/runtime.rs +5 -53
  9. package/crates/team-agent/src/cli/intent/runtime_tests.rs +10 -130
  10. package/crates/team-agent/src/cli/leader.rs +2 -3
  11. package/crates/team-agent/src/cli/leader_prompt.rs +1 -1
  12. package/crates/team-agent/src/cli/mod.rs +28 -33
  13. package/crates/team-agent/src/cli/models.rs +44 -880
  14. package/crates/team-agent/src/cli/route.rs +1 -1
  15. package/crates/team-agent/src/cli/send/persist.rs +36 -0
  16. package/crates/team-agent/src/cli/send/presentation.rs +7 -1
  17. package/crates/team-agent/src/cli/send.rs +3 -1
  18. package/crates/team-agent/src/cli/spec.rs +1 -2
  19. package/crates/team-agent/src/cli/status_port/brief.rs +66 -0
  20. package/crates/team-agent/src/cli/tests/base.rs +4 -11
  21. package/crates/team-agent/src/cli/tests/mod.rs +1 -1
  22. package/crates/team-agent/src/cli/tests/run_delegation.rs +5 -4
  23. package/crates/team-agent/src/cli/tests/status_send.rs +17 -0
  24. package/crates/team-agent/src/compiler/tests.rs +39 -8
  25. package/crates/team-agent/src/compiler.rs +28 -204
  26. package/crates/team-agent/src/contract_runtime/backend.rs +79 -40
  27. package/crates/team-agent/src/contract_runtime/config.rs +37 -24
  28. package/crates/team-agent/src/contract_runtime/discovery.rs +33 -0
  29. package/crates/team-agent/src/contract_runtime/fork.rs +368 -0
  30. package/crates/team-agent/src/contract_runtime/framework.rs +87 -34
  31. package/crates/team-agent/src/contract_runtime/mod.rs +1 -0
  32. package/crates/team-agent/src/contract_runtime/registry.rs +299 -21
  33. package/crates/team-agent/src/coordinator/runtime_detectors.rs +0 -1
  34. package/crates/team-agent/src/coordinator/tests/api_error_recovery.rs +29 -8
  35. package/crates/team-agent/src/coordinator/tests/health_sync.rs +0 -42
  36. package/crates/team-agent/src/coordinator/tick.rs +89 -1
  37. package/crates/team-agent/src/db/message_store.rs +78 -3
  38. package/crates/team-agent/src/layout/worker_window_helpers.rs +0 -1
  39. package/crates/team-agent/src/leader/prompt.rs +1 -2
  40. package/crates/team-agent/src/leader/provider_attribution.rs +0 -52
  41. package/crates/team-agent/src/leader/start.rs +1 -2
  42. package/crates/team-agent/src/leader/tests/prompt_contract.rs +2 -3
  43. package/crates/team-agent/src/lifecycle/launch/add_agent.rs +91 -0
  44. package/crates/team-agent/src/lifecycle/launch/add_agent_state.rs +15 -195
  45. package/crates/team-agent/src/lifecycle/launch/agent_state.rs +0 -9
  46. package/crates/team-agent/src/lifecycle/launch/clone_agent.rs +11 -27
  47. package/crates/team-agent/src/lifecycle/launch/fork_agent.rs +18 -29
  48. package/crates/team-agent/src/lifecycle/launch/fork_entry.rs +6 -87
  49. package/crates/team-agent/src/lifecycle/launch/mcp_config.rs +3 -11
  50. package/crates/team-agent/src/lifecycle/launch/pi_mcp.rs +74 -244
  51. package/crates/team-agent/src/lifecycle/launch/quick_start.rs +0 -24
  52. package/crates/team-agent/src/lifecycle/launch/role_source.rs +5 -0
  53. package/crates/team-agent/src/lifecycle/launch/spawn.rs +21 -61
  54. package/crates/team-agent/src/lifecycle/launch/spec_state.rs +0 -1
  55. package/crates/team-agent/src/lifecycle/launch/worker_env.rs +0 -108
  56. package/crates/team-agent/src/lifecycle/launch.rs +2 -43
  57. package/crates/team-agent/src/lifecycle/profile_launch.rs +21 -348
  58. package/crates/team-agent/src/lifecycle/profile_smoke.rs +1 -2
  59. package/crates/team-agent/src/lifecycle/restart/common.rs +43 -378
  60. package/crates/team-agent/src/lifecycle/restart/selection.rs +5 -5
  61. package/crates/team-agent/src/lifecycle/restart.rs +0 -2
  62. package/crates/team-agent/src/lifecycle/role_config.rs +42 -3
  63. package/crates/team-agent/src/lifecycle/tests/behavioral_diff_264_red.rs +11 -6
  64. package/crates/team-agent/src/lifecycle/tests/claude_profile_launch_red.rs +8 -320
  65. package/crates/team-agent/src/lifecycle/tests/cli_argv_routing_red.rs +60 -145
  66. package/crates/team-agent/src/lifecycle/tests/clone_fork_copilot_perms_red.rs +8 -334
  67. package/crates/team-agent/src/lifecycle/tests/communication_mode_runtime_contract_red.rs +30 -11
  68. package/crates/team-agent/src/lifecycle/tests/copilot_provider_red.rs +2 -2
  69. package/crates/team-agent/src/lifecycle/tests/core.rs +17 -16
  70. package/crates/team-agent/src/lifecycle/tests/grok_require_explicit_model_red.rs +12 -12
  71. package/crates/team-agent/src/lifecycle/tests/harvest2_a_batch_red.rs +3 -51
  72. package/crates/team-agent/src/lifecycle/tests/launch_spawn.rs +26 -28
  73. package/crates/team-agent/src/lifecycle/tests/pi_catalog_red.rs +6 -18
  74. package/crates/team-agent/src/lifecycle/tests/pi_command_red.rs +52 -70
  75. package/crates/team-agent/src/lifecycle/tests/pi_dual_entry_red.rs +4 -157
  76. package/crates/team-agent/src/lifecycle/tests/pi_executable_mcp_red.rs +10 -302
  77. package/crates/team-agent/src/lifecycle/tests/pi_lifecycle_doctor_red.rs +1 -68
  78. package/crates/team-agent/src/lifecycle/tests/pi_native_mcp_capability_red.rs +1 -19
  79. package/crates/team-agent/src/lifecycle/tests/pi_session_delivery_red.rs +2 -100
  80. package/crates/team-agent/src/lifecycle/tests/quick_start_worker_readiness_red.rs +11 -10
  81. package/crates/team-agent/src/lifecycle/tests/restart_rebind_hotfix_252_red.rs +0 -1
  82. package/crates/team-agent/src/lifecycle/tests/restart_session_capture_red.rs +2 -106
  83. package/crates/team-agent/src/lifecycle/tests/status_credential_redaction_contract.rs +2 -2
  84. package/crates/team-agent/src/lifecycle/tests/swallow_batch4_semantics_red.rs +2 -254
  85. package/crates/team-agent/src/lifecycle/tests/upgrade_compat_0211_red.rs +4 -4
  86. package/crates/team-agent/src/lifecycle/tests/verify_rs031_window_consistency_red.rs +6 -5
  87. package/crates/team-agent/src/lifecycle/tests/worker_spawn_env_red.rs +7 -153
  88. package/crates/team-agent/src/lifecycle/tests.rs +0 -6
  89. package/crates/team-agent/src/lifecycle/types.rs +2 -18
  90. package/crates/team-agent/src/lifecycle/worker_command_context.rs +2 -4
  91. package/crates/team-agent/src/mcp_server/readiness.rs +148 -97
  92. package/crates/team-agent/src/mcp_server/readiness_tests.rs +115 -16
  93. package/crates/team-agent/src/messaging/delivery.rs +185 -168
  94. package/crates/team-agent/src/messaging/delivery_consumption_tests.rs +5 -5
  95. package/crates/team-agent/src/messaging/enter_rescue_tests.rs +1 -1
  96. package/crates/team-agent/src/messaging/helpers.rs +19 -0
  97. package/crates/team-agent/src/messaging/tests/dup_inject.rs +67 -5
  98. package/crates/team-agent/src/messaging/tests/runtime.rs +110 -4
  99. package/crates/team-agent/src/messaging/tests/spine.rs +46 -36
  100. package/crates/team-agent/src/model/enums.rs +1 -8
  101. package/crates/team-agent/src/provider/adapter.rs +33 -302
  102. package/crates/team-agent/src/provider/adapters/mod.rs +4 -5
  103. package/crates/team-agent/src/provider/argv_route.rs +1 -5
  104. package/crates/team-agent/src/provider/bypass_flags.rs +3 -11
  105. package/crates/team-agent/src/provider/classify.rs +68 -3
  106. package/crates/team-agent/src/provider/faults.rs +1 -1
  107. package/crates/team-agent/src/provider/model_catalog.rs +14 -273
  108. package/crates/team-agent/src/provider/session/capture.rs +7 -107
  109. package/crates/team-agent/src/provider/session/context_fork/outcome.rs +0 -4
  110. package/crates/team-agent/src/provider/session/context_fork.rs +17 -109
  111. package/crates/team-agent/src/provider/session_scan/common.rs +11 -36
  112. package/crates/team-agent/src/provider/session_scan/pi.rs +1 -34
  113. package/crates/team-agent/src/provider/session_scan.rs +4 -14
  114. package/crates/team-agent/src/provider/submit_now.rs +5 -28
  115. package/crates/team-agent/src/provider/tests/adapter.rs +39 -275
  116. package/crates/team-agent/src/provider/tests/classify.rs +53 -0
  117. package/crates/team-agent/src/provider/tests/command_helpers.rs +3 -15
  118. package/crates/team-agent/src/provider/tests/idle.rs +0 -25
  119. package/crates/team-agent/src/provider/types.rs +1 -1
  120. package/crates/team-agent/src/provider/wire.rs +79 -11
  121. package/crates/team-agent/src/state/abnormal_watch/tests/mod.rs +1 -1
  122. package/crates/team-agent/src/state/persist.rs +6 -6
  123. package/crates/team-agent/src/state/repository/tests.rs +2 -2
  124. package/crates/team-agent/src/tmux_backend/native_input_tests.rs +2 -178
  125. package/crates/team-agent/src/tmux_backend/tests.rs +151 -0
  126. package/crates/team-agent/src/tmux_backend.rs +43 -8
  127. package/crates/team-agent/src/transport/native_input.rs +2 -231
  128. package/package.json +4 -4
  129. package/skills/team-agent/SKILL.md +7 -5
  130. package/skills/team-agent/command-coverage.json +15 -1
  131. package/skills/team-agent/docs/reference/team-agent-operator.md +5 -3
  132. package/skills/team-agent/references/team-agent-operator.md +5 -3
  133. package/crates/team-agent/src/lifecycle/launch/cursor_create_chat.rs +0 -229
  134. package/crates/team-agent/src/lifecycle/launch/cursor_mcp.rs +0 -522
  135. package/crates/team-agent/src/lifecycle/launch/cursor_mcp_iso.rs +0 -282
  136. package/crates/team-agent/src/lifecycle/restart/avatar.rs +0 -1805
  137. package/crates/team-agent/src/lifecycle/tests/claude_compatible_config_red.rs +0 -325
  138. package/crates/team-agent/src/lifecycle/tests/cursor_mcp_overlay.rs +0 -576
  139. package/crates/team-agent/src/lifecycle/tests/cursor_require_explicit_model_red.rs +0 -222
  140. package/crates/team-agent/src/lifecycle/tests/cursor_restart_resume_red.rs +0 -511
  141. package/crates/team-agent/src/lifecycle/tests/pi_compiler_red.rs +0 -210
  142. package/crates/team-agent/src/lifecycle/tests/pi_fork_session_inheritance_red.rs +0 -1409
  143. package/crates/team-agent/src/provider/adapters/claude.rs +0 -78
  144. package/crates/team-agent/src/provider/adapters/claude_fork.rs +0 -131
  145. package/crates/team-agent/src/provider/adapters/cursor_agent.rs +0 -44
  146. package/crates/team-agent/src/provider/adapters/pi.rs +0 -100
  147. package/crates/team-agent/src/provider/session/context_fork/claude.rs +0 -123
  148. package/crates/team-agent/src/provider/session_scan/claude.rs +0 -523
  149. package/crates/team-agent/src/provider/session_scan/cursor.rs +0 -538
  150. package/crates/team-agent/src/provider/testdata/cursor-list-models-native.stdout +0 -250
  151. package/crates/team-agent/src/test_support/models_timeout_fixture.rs +0 -144
@@ -0,0 +1,368 @@
1
+ //! Generic contract-native seat fork (avatar): one pipeline for every leaf.
2
+ //! The descriptor's fork facet selects the admitted mode, the leaf's H2/H7
3
+ //! supply native argv and stage intent, and the shared `Lifecycle::fork` runs
4
+ //! F0-F5 with its own compensation. Only the registry dispatches per leaf; a
5
+ //! refused provider leaves no role, spec, state, pane or native file behind.
6
+ use std::path::{Path, PathBuf};
7
+
8
+ use serde_json::{json, Value};
9
+ use team_agent_contract::contract::{
10
+ fork::{resolve_fork, select_new_seat_mode, ForkMode, ForkRequest},
11
+ plan::{resolve_launch, validate_launch_plan},
12
+ types::{ContractError, Operation, OperationId, SeatId},
13
+ };
14
+ use team_agent_contract::host::{clock::RealClock, command::RealCommandRunner, materialize::ScopedMaterializer};
15
+ use team_agent_contract::orchestration::{
16
+ lifecycle::{Adapter, Lifecycle, Routing},
17
+ physical::{PhysicalRuntime, Registration},
18
+ store::{OperationRecord, Outcome, SeatStatus},
19
+ Error,
20
+ };
21
+
22
+ use crate::cli::CliError;
23
+ use crate::lifecycle::launch::add_agent_state::{inject_agent_into_spec, rollback_add_agent_atomic, upsert_agent_entry};
24
+ use crate::model::ids::AgentId;
25
+ use crate::model::yaml::Value as Yaml;
26
+ use crate::state::selector::SelectedTeam;
27
+
28
+ use super::{
29
+ backend::{self, Backend, BackendError},
30
+ commands,
31
+ config::{MemberRoute, RoleConfig},
32
+ discovery, framework, registry,
33
+ };
34
+
35
+ fn error(error: impl std::fmt::Display) -> CliError {
36
+ CliError::Runtime(error.to_string())
37
+ }
38
+
39
+ fn refused(provider: &str, refusal: ContractError) -> CliError {
40
+ CliError::Runtime(format!(
41
+ "{provider} does not support session forking: {refusal}; no seat, pane or file was created"
42
+ ))
43
+ }
44
+
45
+ /// `fork-agent <source> --as <target>` for a contract seat. None: the source
46
+ /// is not a contract seat and keeps its own runtime's fork path.
47
+ pub fn fork_agent(
48
+ workspace: &Path,
49
+ team: Option<&str>,
50
+ source: &str,
51
+ target: &str,
52
+ label: Option<&str>,
53
+ ) -> Result<Option<Value>, CliError> {
54
+ commands::with_agent(workspace, team, source, "fork-agent", |selected, source_id| {
55
+ fork_locked(selected, source_id, target, label)
56
+ })
57
+ }
58
+
59
+ /// Called under the source's lifecycle lock (`with_agent`).
60
+ fn fork_locked(
61
+ selected: &SelectedTeam,
62
+ source_id: &SeatId,
63
+ target: &str,
64
+ label: Option<&str>,
65
+ ) -> Result<Value, CliError> {
66
+ let workspace = selected.run_workspace.as_path();
67
+ let team = selected.team_key.as_str();
68
+ // F0 is read-only: nothing below writes until the role file.
69
+ let parent = Backend::open_readonly(workspace, team).map_err(error)?
70
+ .store.seat(source_id).map_err(error)?
71
+ .ok_or_else(|| error("contract source seat is not in its native store"))?;
72
+ let provider = parent.provider.as_str().to_owned();
73
+ let descriptor = registry::provider(&provider).map_err(error)?.descriptor();
74
+ if target == source_id.as_str() {
75
+ // The same seat can only branch in place, and only when admitted.
76
+ descriptor.fork.in_window.require("in-window branch").map_err(|refusal| refused(&provider, refusal))?;
77
+ return Err(error("contract_capability_unverified: in-window branch dispatch is not wired; no key was sent"));
78
+ }
79
+ if select_new_seat_mode(descriptor).map_err(|refusal| refused(&provider, refusal))? != ForkMode::NativeNewSeat {
80
+ return Err(error(format!(
81
+ "contract_capability_unverified: {provider} full-snapshot staging is not wired; no seat was created"
82
+ )));
83
+ }
84
+ let target_id = SeatId::new(target).map_err(|_| error(format!("invalid fork target id: {target}")))?;
85
+ if target == "leader" {
86
+ return Err(error("fork target id `leader` is reserved"));
87
+ }
88
+ let source_session = parent.session.as_ref()
89
+ .filter(|_| parent.status != SeatStatus::Unknown)
90
+ .map(|session| session.native_session.as_str().to_owned())
91
+ .ok_or_else(|| error("contract source seat has no captured native session to fork"))?;
92
+ if selected.state.get("agents").and_then(|agents| agents.get(target)).is_some() {
93
+ return Err(error(format!("agent id already exists: {target}")));
94
+ }
95
+ let role_path = selected.team_dir.join("agents").join(format!("{target}.md"));
96
+ if std::fs::symlink_metadata(&role_path).is_ok() {
97
+ return Err(error(format!("role file already exists: {}", role_path.display())));
98
+ }
99
+ let config = framework::team_config(workspace, &selected.team_dir, team).map_err(error)?
100
+ .ok_or_else(|| error("contract team configuration is unavailable"))?;
101
+ let source_role = config.roles.iter().find(|role| &role.id == source_id)
102
+ .ok_or_else(|| error("contract source role is no longer configured"))?;
103
+ if source_role.provider != parent.provider {
104
+ return Err(error("contract source role now declares another provider; a fork keeps the parent's"));
105
+ }
106
+ let role_text = fork_role_text(&std::fs::read_to_string(&source_role.source).map_err(error)?, target, label);
107
+ let spec_path = crate::model::paths::runtime_spec_path(workspace, team);
108
+ let pre_spec = match std::fs::read_to_string(&spec_path) {
109
+ Ok(text) => Some(text),
110
+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => None,
111
+ Err(e) => return Err(error(e)),
112
+ };
113
+ write_new(&role_path, role_text.as_bytes()).map_err(error)?;
114
+ let undo = Undo {
115
+ workspace: workspace.to_path_buf(), team: team.to_owned(), target: target_id.clone(),
116
+ role_path: role_path.clone(), role_bytes: role_text.into_bytes(), spec_path: spec_path.clone(), pre_spec,
117
+ };
118
+ let result = (|| -> Result<Value, CliError> {
119
+ let config = framework::team_config(workspace, &selected.team_dir, team).map_err(error)?
120
+ .ok_or_else(|| error("contract team configuration is unavailable"))?;
121
+ let role = config.roles.iter().find(|role| role.id == target_id)
122
+ .ok_or_else(|| error("forked contract role was not configured"))?;
123
+ if role.paused || role.provider != parent.provider {
124
+ return Err(error("forked contract role is paused or changed provider; nothing was started"));
125
+ }
126
+ register_spec(selected, &role_path, target, &spec_path, undo.pre_spec.as_deref())?;
127
+ let record = native_fork(workspace, team, source_id, role, &config.members).map_err(error)?;
128
+ if record.outcome != Outcome::Committed {
129
+ return Err(error(BackendError::Shutdown {
130
+ operation: record.id, phase: record.phase, outcome: record.outcome, failure: record.failure,
131
+ }));
132
+ }
133
+ // The roster row appears only once the native seat has committed: a
134
+ // half-built target never enters the coordinator tick's projection.
135
+ upsert_agent_entry(workspace, team, &AgentId::new(target), json!({
136
+ "agent_id": target, "provider": role.provider.as_str(), "runtime_family": "contract",
137
+ "status": "starting", "contract_instance": null, "pane_id": null, "forked_from": source_id.as_str(),
138
+ })).map_err(error)?;
139
+ let projection = commands::publish_at(workspace, team, &target_id, true)?;
140
+ let coordinator = crate::coordinator::start_coordinator_with_team(
141
+ &crate::coordinator::WorkspacePath::new(workspace.to_path_buf()), Some(team),
142
+ ).map_err(error)?;
143
+ Ok(json!({"ok":coordinator.ok,"status":"forked","runtime":"contract","mode":"native_new_seat",
144
+ "provider":provider,"source_agent_id":source_id.as_str(),"new_agent_id":target,"target":target,
145
+ "agent_id":target,"operation":record.id,"source_session_id":source_session,
146
+ "session_id":projection.get("session_id"),"new_session_id":projection.get("session_id"),
147
+ "generation":projection.get("generation"),"backing_state":"verified",
148
+ "coordinator":crate::lifecycle::coordinator_start_summary_value(
149
+ &crate::lifecycle::CoordinatorStartSummary::from_start_report(&coordinator))}))
150
+ })();
151
+ result.map_err(|failure| undo.run(failure))
152
+ }
153
+
154
+ /// The provider-neutral F1-F5: H2 plans the native fork argv for the target,
155
+ /// H7 states the intent, and `Lifecycle::fork` registers, spawns, captures the
156
+ /// child binding and commits, compensating its own effects on failure.
157
+ fn native_fork(
158
+ workspace: &Path,
159
+ team: &str,
160
+ source: &SeatId,
161
+ role: &RoleConfig,
162
+ members: &[MemberRoute],
163
+ ) -> Result<OperationRecord, BackendError> {
164
+ let mut backend = Backend::open(workspace, team)?;
165
+ backend::require_candidate(&backend.binding)?;
166
+ if !backend::seat_unclaimed(&backend, &role.id)? {
167
+ return Err(Error::Conflict.into());
168
+ }
169
+ let parent = backend.store.seat(source)?.ok_or(Error::Invalid("unknown native seat"))?;
170
+ let session = parent.session.clone().ok_or(ContractError::Invalid("native fork source session"))?;
171
+ if parent.status == SeatStatus::Unknown || parent.provider != role.provider {
172
+ return Err(Error::Fence.into());
173
+ }
174
+ let selected = registry::provider(role.provider.as_str())?;
175
+ let descriptor = selected.descriptor();
176
+ let discovered = discovery::discover_runtime(&role.provider, workspace)?;
177
+ if let Some(path) = selected.native_fork_source(discovered.runtime.as_ref(), &session)? {
178
+ // The exact parent backing the native CLI reads must exist before any effect.
179
+ let metadata = std::fs::symlink_metadata(&path)?;
180
+ if !metadata.is_file() || metadata.len() == 0 {
181
+ return Err(ContractError::Invalid("native fork parent backing").into());
182
+ }
183
+ }
184
+ backend::publish_framework_routes(&mut backend, members)?;
185
+ let identity = backend.store.propose_identity(&role.id)?;
186
+ let server_key = selected.server_key_for(&identity)?;
187
+ backend::write_role(&backend.binding, &identity, role)?;
188
+ let adapter = backend::launch_adapter(&backend.binding, &identity, &role.provider, &discovered)?;
189
+ let hooks = adapter.hooks();
190
+ let mut launch = backend::request(&backend.binding, role, identity, &discovered)?;
191
+ launch.operation = Operation::NativeNewSeat;
192
+ if !descriptor.workspace.shared_cwd {
193
+ launch.paths.cwd = super::workspace::prepare(&backend.binding, &role.id)?;
194
+ }
195
+ backend::require_private_primary(selected, &launch.paths.cwd)?;
196
+ backend::preassign_session(selected, &mut launch, &discovered)?;
197
+ let operation = OperationId::new(format!("fork-{}", launch.identity.instance.as_str()))?;
198
+ let request = ForkRequest {
199
+ mode: ForkMode::NativeNewSeat,
200
+ auth: launch.auth,
201
+ source: session,
202
+ expected_source: parent.identity.clone(),
203
+ target: launch.identity.clone(),
204
+ target_native_session: None,
205
+ target_backing: None,
206
+ channel: launch.channel,
207
+ input_profile: launch.input_profile.clone(),
208
+ cwd: launch.paths.cwd.clone(),
209
+ native: launch.native.clone(),
210
+ evidence_kind: launch.evidence_kind,
211
+ selected_turn: None,
212
+ operation_id: operation.clone(),
213
+ };
214
+ launch.fork = Some(Box::new(resolve_fork(descriptor, &hooks, &request)?));
215
+ let resolved = resolve_launch(descriptor, &hooks, &launch, Some(&discovered.catalog))?;
216
+ let plan = adapter.plan(&resolved)?;
217
+ validate_launch_plan(descriptor, &resolved, &plan)?;
218
+ let (workspace_topology, _, _) = backend::workspace_tmux(&backend.binding, &role.id, None)?;
219
+ let mut io = ScopedMaterializer::new(descriptor, &resolved, &plan, operation.clone(), RealCommandRunner::default())?;
220
+ let clock = RealClock::new();
221
+ let mut physical = PhysicalRuntime::new(
222
+ Registration {
223
+ descriptor,
224
+ hooks: &hooks,
225
+ controls: selected.controls(),
226
+ startup: selected.startup(),
227
+ session_panel: selected.session_panel(),
228
+ },
229
+ backend::settings(&backend.binding, selected),
230
+ operation.clone(),
231
+ &clock,
232
+ )?;
233
+ physical.evidence = backend::policy_evidence(&role.provider, &launch.native, backend.binding.candidate_sha256)?;
234
+ physical.workspace_tmux = Some(workspace_topology);
235
+ let routing = Routing {
236
+ pane: "unpublished".into(),
237
+ binding_key: format!("binding-{}", launch.identity.instance.as_str()),
238
+ server_key,
239
+ };
240
+ let record = Lifecycle { store: &mut backend.store, host: &mut physical, io: &mut io }.fork(
241
+ &Adapter { descriptor, hooks: &hooks, catalog: Some(&discovered.catalog) },
242
+ &request,
243
+ Some((&launch, routing)),
244
+ )?;
245
+ Ok(record)
246
+ }
247
+
248
+ /// The target's runtime spec entry and route, compiled exactly as add-agent does.
249
+ fn register_spec(
250
+ selected: &SelectedTeam,
251
+ role_path: &Path,
252
+ target: &str,
253
+ spec_path: &Path,
254
+ pre_spec: Option<&str>,
255
+ ) -> Result<(), CliError> {
256
+ let mut spec = crate::compiler::compile_team(&selected.team_dir).map_err(error)?;
257
+ crate::lifecycle::launch::spec_state::override_spec_workspace(&mut spec, &selected.run_workspace);
258
+ let workspace_text = spec.get("team").and_then(|team| team.get("workspace")).and_then(Yaml::as_str)
259
+ .map(str::to_owned)
260
+ .unwrap_or_else(|| selected.run_workspace.to_string_lossy().into_owned());
261
+ let team_meta = crate::compiler::read_front_matter(&selected.team_dir.join("TEAM.md"))
262
+ .map(|(meta, _)| meta)
263
+ .unwrap_or(Yaml::Null);
264
+ let compiled = crate::compiler::compile_role_agent(role_path, &team_meta, &workspace_text).map_err(error)?;
265
+ if compiled.id != target {
266
+ return Err(error(format!("forked role compiles to '{}', not '{target}'", compiled.id)));
267
+ }
268
+ let mut latest = pre_spec.and_then(|text| crate::model::yaml::loads(text).ok()).unwrap_or(spec);
269
+ inject_agent_into_spec(&mut latest, compiled.agent, &compiled.id).map_err(error)?;
270
+ crate::lifecycle::launch::spec_state::write_spec_atomic(spec_path, &latest).map_err(error)
271
+ }
272
+
273
+ /// The parent's role document under the target's identity: its own name, the
274
+ /// optional label as role, every other field and the body unchanged.
275
+ fn fork_role_text(source: &str, target: &str, label: Option<&str>) -> String {
276
+ let (mut meta, body) = crate::compiler::split_front_matter(source);
277
+ if let Yaml::Map(pairs) = &mut meta {
278
+ pairs.retain(|(key, _)| key != "agent_id");
279
+ set_field(pairs, "name", target);
280
+ if let Some(label) = label.map(str::trim).filter(|label| !label.is_empty()) {
281
+ set_field(pairs, "role", label);
282
+ }
283
+ }
284
+ format!("---\n{}---\n\n{}", crate::lifecycle::launch::role_source::dump_role_frontmatter(&meta), body)
285
+ }
286
+
287
+ fn set_field(pairs: &mut Vec<(String, Yaml)>, key: &str, value: &str) {
288
+ match pairs.iter_mut().find(|(name, _)| name == key) {
289
+ Some((_, old)) => *old = Yaml::Str(value.to_owned()),
290
+ None => pairs.push((key.to_owned(), Yaml::Str(value.to_owned()))),
291
+ }
292
+ }
293
+
294
+ fn write_new(path: &Path, bytes: &[u8]) -> std::io::Result<()> {
295
+ use std::io::Write;
296
+ let mut file = std::fs::OpenOptions::new().write(true).create_new(true).open(path)?;
297
+ file.write_all(bytes)?;
298
+ file.sync_all()
299
+ }
300
+
301
+ /// Compensation for this fork's own registration. A started but unpublished
302
+ /// native seat is stopped first; if that fails, the role/spec/state stay so
303
+ /// status and stop can still reach the live seat.
304
+ struct Undo {
305
+ workspace: PathBuf,
306
+ team: String,
307
+ target: SeatId,
308
+ role_path: PathBuf,
309
+ role_bytes: Vec<u8>,
310
+ spec_path: PathBuf,
311
+ pre_spec: Option<String>,
312
+ }
313
+
314
+ impl Undo {
315
+ fn run(&self, failure: CliError) -> CliError {
316
+ let started = Backend::open_readonly(&self.workspace, &self.team)
317
+ .ok()
318
+ .and_then(|backend| backend.store.seat(&self.target).ok().flatten())
319
+ .is_some_and(|seat| seat.status != SeatStatus::Stopped && seat.physical.is_some());
320
+ if started {
321
+ if let Err(stop) = backend::stop(&self.workspace, &self.team, &self.target) {
322
+ return error(format!(
323
+ "{failure}; stopping the forked native seat failed: {stop}; its role, spec and state were kept"
324
+ ));
325
+ }
326
+ }
327
+ rollback_add_agent_atomic(
328
+ &self.workspace, &self.spec_path, self.pre_spec.as_deref(), None,
329
+ Some(self.team.as_str()), &AgentId::new(self.target.as_str()), "fork_agent_failed",
330
+ );
331
+ let residual = match std::fs::read(&self.role_path) {
332
+ Ok(bytes) if bytes == self.role_bytes => std::fs::remove_file(&self.role_path)
333
+ .err()
334
+ .map(|e| format!("role file {}: {e}", self.role_path.display())),
335
+ Ok(_) => Some(format!("role file {} changed; preserved", self.role_path.display())),
336
+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => None,
337
+ Err(e) => Some(format!("role file {}: {e}", self.role_path.display())),
338
+ };
339
+ match residual {
340
+ None => failure,
341
+ Some(residual) => error(format!("{failure}; compensation incomplete: {residual}")),
342
+ }
343
+ }
344
+ }
345
+
346
+ #[cfg(test)]
347
+ mod tests {
348
+ use super::fork_role_text;
349
+ use crate::model::yaml::Value;
350
+
351
+ #[test]
352
+ fn forked_role_keeps_its_body_and_takes_the_target_identity() {
353
+ let source = "---\nname: opus-architect\nagent_id: opus-architect\nprovider: claude\nmodel: claude-opus-5-5\n---\n\nYou design the system.\n";
354
+ let forked = fork_role_text(source, "opus-fork", Some(" avatar "));
355
+ let (meta, body) = crate::compiler::split_front_matter(&forked);
356
+ assert_eq!(meta.get("name").and_then(Value::as_str), Some("opus-fork"));
357
+ assert!(meta.get("agent_id").is_none());
358
+ assert_eq!(meta.get("role").and_then(Value::as_str), Some("avatar"));
359
+ assert_eq!(meta.get("provider").and_then(Value::as_str), Some("claude"));
360
+ assert_eq!(meta.get("model").and_then(Value::as_str), Some("claude-opus-5-5"));
361
+ assert_eq!(body.trim(), "You design the system.");
362
+ let unlabeled = fork_role_text("plain body\n", "opus-fork", None);
363
+ let (meta, body) = crate::compiler::split_front_matter(&unlabeled);
364
+ assert_eq!(meta.get("name").and_then(Value::as_str), Some("opus-fork"));
365
+ assert!(meta.get("role").is_none());
366
+ assert_eq!(body.trim(), "plain body");
367
+ }
368
+ }
@@ -54,15 +54,26 @@ pub fn require_legacy_lifecycle(
54
54
  ) else {
55
55
  return Ok(());
56
56
  };
57
+ let row = agent.and_then(|id| selected.state.get("agents").and_then(|agents| agents.get(id)));
58
+ // A pre-upgrade legacy Cursor, Claude or Pi seat has no engine left; only teardown is admitted.
59
+ let teardown = matches!(operation, "stop-agent" | "remove-agent");
60
+ if let Some(retired) = row
61
+ .and_then(|row| row.get("provider"))
62
+ .and_then(Value::as_str)
63
+ .filter(|provider| !teardown && crate::provider::wire::is_retired_provider(provider))
64
+ {
65
+ return Err(crate::cli::CliError::Runtime(
66
+ crate::provider::wire::retired_provider_error(retired).into(),
67
+ ));
68
+ }
57
69
  let selected_native = match agent {
58
- Some(id) => selected
59
- .state
60
- .get("agents")
61
- .and_then(|agents| agents.get(id))
62
- .is_some_and(is_contract),
70
+ Some(_) => row.is_some_and(is_contract),
63
71
  None => has_contract(&selected.state),
64
72
  };
65
- let configured_native = selected
73
+ // A recorded legacy seat is torn down on its own runtime even when its role
74
+ // document now declares a contract leaf (`cursor_agent` before the upgrade).
75
+ let configured_native = !(teardown && row.is_some())
76
+ && selected
66
77
  .state
67
78
  .get("team_dir")
68
79
  .and_then(Value::as_str)
@@ -88,23 +99,27 @@ pub fn require_legacy_role(
88
99
  path: Option<&Path>,
89
100
  provider: Option<&str>,
90
101
  ) -> Result<(), crate::cli::CliError> {
91
- let declared = path
92
- .and_then(|path| std::fs::read_to_string(path).ok())
93
- .and_then(|raw| {
94
- crate::compiler::split_front_matter(&raw)
95
- .0
96
- .get("provider")
97
- .and_then(crate::model::yaml::Value::as_str)
98
- .map(str::to_owned)
99
- });
100
- if provider
101
- .or(declared.as_deref())
102
- .is_some_and(super::registry::recognizes)
103
- {
102
+ if declares_contract(path, provider) {
104
103
  return Err(crate::cli::CliError::Runtime("contract_capability_unverified: mutable contract-native role lifecycle is not admitted; use initial quick-start; no role file was changed".into()));
105
104
  }
106
105
  Ok(())
107
106
  }
107
+ /// Whether a role document or CLI provider value selects a contract leaf.
108
+ pub fn declares_contract(path: Option<&Path>, provider: Option<&str>) -> bool {
109
+ let meta = path
110
+ .and_then(|path| std::fs::read_to_string(path).ok())
111
+ .map(|raw| crate::compiler::split_front_matter(&raw).0);
112
+ let declared = meta.as_ref().and_then(|meta| {
113
+ meta.get("provider")
114
+ .and_then(crate::model::yaml::Value::as_str)
115
+ .map(str::to_owned)
116
+ });
117
+ let opted_in = meta.as_ref().is_some_and(|meta| {
118
+ matches!(meta.get("contract_runtime"), Some(crate::model::yaml::Value::Bool(true)))
119
+ });
120
+ // An omitted provider is the default `pi`, which declares the Pi leaf.
121
+ super::registry::recognizes(provider.or(declared.as_deref()).unwrap_or("pi"), opted_in)
122
+ }
108
123
  pub fn team_config(
109
124
  workspace: &Path,
110
125
  directory: &Path,
@@ -132,21 +147,7 @@ pub fn start_role(
132
147
  if directory.canonicalize()? != selected.team_dir.canonicalize()? {
133
148
  return Err(error("native role source changed while acquiring lifecycle ownership".into()));
134
149
  }
135
- let config = team_config(&selected.run_workspace, &selected.team_dir, &selected.team_key)
136
- .map_err(|e| error(e.to_string()))?
137
- .ok_or_else(|| error("contract role no longer configured".into()))?;
138
- let role = config.roles.iter().find(|role| &role.id == seat)
139
- .ok_or_else(|| error("contract role not found".into()))?;
140
- let (_, record) = backend::start(&selected.run_workspace, &selected.team_key, role, &config.members)
141
- .map_err(|e| error(e.to_string()))?;
142
- if record.outcome != Outcome::Committed {
143
- return Err(error(format!("native startup seat={id} operation={:?} phase={:?} outcome={:?}: {}",
144
- record.id, record.phase, record.outcome, record.failure.unwrap_or_default())));
145
- }
146
- // Preserve each committed seat before a later discovery/spawn can fail.
147
- // A whole-batch error must never hide this generation's physical effects.
148
- let projected = super::commands::publish_at(&selected.run_workspace, &selected.team_key, seat, true)?;
149
- Ok(projected)
150
+ start_configured(&selected.run_workspace, &selected.team_dir, &selected.team_key, seat)
150
151
  }).map_err(|e| crate::lifecycle::LifecycleError::Provider(e.to_string()))?;
151
152
  if result.is_none() {
152
153
  return Err(crate::lifecycle::LifecycleError::Provider("native startup scope/seat is not addressable; no legacy fallback".into()));
@@ -154,6 +155,58 @@ pub fn start_role(
154
155
  Ok(())
155
156
  }
156
157
 
158
+ /// Start one configured contract role and publish its seat. The caller holds
159
+ /// the lifecycle lock (or owns the whole launch) and has seeded the state row.
160
+ pub(crate) fn start_configured(
161
+ workspace: &Path,
162
+ directory: &Path,
163
+ team: &str,
164
+ seat: &SeatId,
165
+ ) -> Result<Value, crate::cli::CliError> {
166
+ let error = |error: String| crate::cli::CliError::Runtime(error);
167
+ let config = team_config(workspace, directory, team)
168
+ .map_err(|e| error(e.to_string()))?
169
+ .ok_or_else(|| error("contract role no longer configured".into()))?;
170
+ let role = config.roles.iter().find(|role| &role.id == seat)
171
+ .ok_or_else(|| error(format!("contract role not found in {}", directory.join("agents").display())))?;
172
+ let (_, record) = backend::start(workspace, team, role, &config.members)
173
+ .map_err(|e| error(e.to_string()))?;
174
+ if record.outcome != Outcome::Committed {
175
+ return Err(error(format!("native startup seat={} operation={:?} phase={:?} outcome={:?}: {}",
176
+ seat.as_str(), record.id, record.phase, record.outcome, record.failure.unwrap_or_default())));
177
+ }
178
+ // Preserve each committed seat before a later discovery/spawn can fail.
179
+ // A whole-batch error must never hide this generation's physical effects.
180
+ super::commands::publish_at(workspace, team, seat, true)
181
+ }
182
+
183
+ /// add-agent owns a brand-new seat. If its start committed but publication
184
+ /// failed, stop that seat before the caller rolls its row back: a refused add
185
+ /// never leaves a running native process outside status/stop. An unpublished
186
+ /// spawn stays with its fenced receipt for explicit recovery.
187
+ pub(crate) fn start_new_seat(
188
+ workspace: &Path,
189
+ directory: &Path,
190
+ team: &str,
191
+ seat: &SeatId,
192
+ ) -> Result<(), crate::cli::CliError> {
193
+ let Err(error) = start_configured(workspace, directory, team, seat) else {
194
+ return Ok(());
195
+ };
196
+ let started = Backend::open_readonly(workspace, team)
197
+ .ok()
198
+ .and_then(|backend| backend.store.seat(seat).ok().flatten())
199
+ .is_some_and(|current| current.status != SeatStatus::Stopped && current.physical.is_some());
200
+ if started {
201
+ if let Err(stop) = backend::stop(workspace, team, seat) {
202
+ return Err(crate::cli::CliError::Runtime(format!(
203
+ "{error}; stopping the started native seat failed: {stop}"
204
+ )));
205
+ }
206
+ }
207
+ Err(error)
208
+ }
209
+
157
210
  pub fn project_seat(workspace: &Path, team: &str, id: &str) -> Result<Value, BackendError> {
158
211
  let mut backend = Backend::open_readonly(workspace, team)?;
159
212
  let seat = backend
@@ -7,6 +7,7 @@ pub mod backend;
7
7
  pub mod commands;
8
8
  pub mod config;
9
9
  pub mod discovery;
10
+ pub mod fork;
10
11
  pub mod forward;
11
12
  pub mod framework;
12
13
  pub mod mcp;