@team-agent/installer 0.5.122 → 0.5.124

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 (35) hide show
  1. package/Cargo.lock +8 -1
  2. package/Cargo.toml +1 -1
  3. package/crates/team-agent/src/cli/diagnose.rs +176 -10
  4. package/crates/team-agent/src/cli/intent/runtime.rs +103 -43
  5. package/crates/team-agent/src/cli/intent/runtime_tests.rs +198 -0
  6. package/crates/team-agent/src/cli/intent/tests.rs +37 -0
  7. package/crates/team-agent/src/cli/intent.rs +22 -0
  8. package/crates/team-agent/src/cli/models.rs +54 -10
  9. package/crates/team-agent/src/contract_runtime/backend.rs +498 -2
  10. package/crates/team-agent/src/contract_runtime/commands.rs +38 -24
  11. package/crates/team-agent/src/contract_runtime/discovery.rs +46 -56
  12. package/crates/team-agent/src/contract_runtime/forward.rs +59 -0
  13. package/crates/team-agent/src/contract_runtime/framework.rs +23 -17
  14. package/crates/team-agent/src/contract_runtime/registry.rs +41 -3
  15. package/crates/team-agent/src/lifecycle/launch/pi_mcp.rs +19 -101
  16. package/crates/team-agent/src/lifecycle/launch/quick_start.rs +6 -17
  17. package/crates/team-agent/src/lifecycle/launch/quick_start_transport.rs +26 -19
  18. package/crates/team-agent/src/lifecycle/launch/spawn.rs +19 -2
  19. package/crates/team-agent/src/lifecycle/restart/rebuild.rs +95 -31
  20. package/crates/team-agent/src/lifecycle/restart.rs +1 -0
  21. package/crates/team-agent/src/lifecycle/tests/cli_argv_routing_red.rs +5 -6
  22. package/crates/team-agent/src/lifecycle/tests/launch_spawn.rs +7 -5
  23. package/crates/team-agent/src/lifecycle/tests/pi_catalog_red.rs +1 -3
  24. package/crates/team-agent/src/lifecycle/tests/pi_command_red.rs +4 -16
  25. package/crates/team-agent/src/lifecycle/tests/pi_compiler_red.rs +1 -3
  26. package/crates/team-agent/src/lifecycle/tests/pi_executable_mcp_red.rs +84 -53
  27. package/crates/team-agent/src/lifecycle/tests/pi_fork_session_inheritance_red.rs +19 -1
  28. package/crates/team-agent/src/lifecycle/tests/pi_session_delivery_red.rs +21 -0
  29. package/crates/team-agent/src/messaging/delivery.rs +5 -3
  30. package/crates/team-agent/src/provider/adapters/pi.rs +4 -4
  31. package/crates/team-agent/src/provider/session_scan/pi.rs +32 -19
  32. package/crates/team-agent/src/provider/tests/command_helpers.rs +2 -2
  33. package/crates/team-agent/src/provider/wire.rs +2 -1
  34. package/npm/install.mjs +56 -99
  35. package/package.json +4 -4
@@ -19,11 +19,14 @@ use team_agent_contract::host::{
19
19
  digest, digest_hex,
20
20
  materialize::ScopedMaterializer,
21
21
  process::{fingerprint_file, resolve_cwd},
22
- tmux::HostLimits,
22
+ tmux::{HostLimits, SharedTmux, TmuxHost},
23
+ transport::PhysicalTransport,
23
24
  };
24
25
  use team_agent_contract::orchestration::{lifecycle::*, physical::*, store::*, Error};
25
26
  use thiserror::Error as ThisError;
26
27
 
28
+ use crate::transport::Transport;
29
+
27
30
  use super::{
28
31
  config::{MemberRoute, RoleConfig, RuntimeFamily},
29
32
  discovery::{self, Discovery, DiscoveryError},
@@ -205,6 +208,144 @@ impl Backend {
205
208
  }
206
209
  }
207
210
 
211
+ fn workspace_socket(path: &Path) -> Result<Option<(u64, u64)>, BackendError> {
212
+ use std::os::unix::fs::{FileTypeExt, MetadataExt};
213
+ let metadata = match std::fs::symlink_metadata(path) {
214
+ Ok(metadata) => metadata,
215
+ Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
216
+ Err(error) => return Err(error.into()),
217
+ };
218
+ // Root already uses libc for UID checks; this syscall has no pointer input.
219
+ let uid = unsafe { libc::geteuid() };
220
+ if !metadata.file_type().is_socket() || metadata.uid() != uid {
221
+ return Err(ContractError::Mismatch("workspace socket owner/type").into());
222
+ }
223
+ Ok(Some((metadata.dev(), metadata.ino())))
224
+ }
225
+
226
+ /// The selected root transport is authority; ambient TMUX is never a selector.
227
+ /// This runs only in the owning lifecycle action, after native F0 admission.
228
+ fn workspace_tmux(
229
+ binding: &Binding,
230
+ seat: &SeatId,
231
+ claim: Option<&team_agent_contract::host::transport::TargetReceipt>,
232
+ ) -> Result<(SharedTmux, crate::tmux_backend::TmuxBackend, String), BackendError> {
233
+ use std::os::unix::fs::{DirBuilderExt, MetadataExt};
234
+ let selected = crate::state::selector::resolve_active_team_readonly(
235
+ &binding.workspace.path, Some(&binding.team), crate::state::selector::SelectorMode::RuntimeOnly,
236
+ ).map_err(|_| ContractError::Mismatch("workspace topology scope"))?;
237
+ if selected.run_workspace != binding.workspace.path || selected.team_key != binding.team {
238
+ return Err(Error::Fence.into());
239
+ }
240
+ crate::lifecycle::launch::ensure_owner_allowed_for_state(&selected.state,
241
+ Some(&crate::model::ids::AgentId::new(seat.as_str())))
242
+ .map_err(|_| ContractError::Mismatch("workspace topology caller ownership"))?;
243
+ let transport = crate::lifecycle::restart::lifecycle_worker_tmux_backend_selection_for_state(
244
+ &selected.run_workspace, &selected.state,
245
+ ).map_err(|_| ContractError::Mismatch("workspace topology transport"))?.backend;
246
+ let endpoint = transport.tmux_endpoint().filter(|s| !s.is_empty())
247
+ .ok_or(ContractError::Invalid("explicit workspace tmux endpoint required"))?;
248
+ let named = !Path::new(&endpoint).is_absolute();
249
+ let endpoint = if named {
250
+ crate::tmux_backend::socket_path_for_name(&endpoint)
251
+ .ok_or(ContractError::Invalid("workspace tmux socket name"))?
252
+ } else { PathBuf::from(endpoint) };
253
+ let parent = endpoint.parent().ok_or(ContractError::Invalid("workspace socket parent"))?;
254
+ if !parent.exists() && named && claim.is_none() {
255
+ if let Err(error) = std::fs::DirBuilder::new().mode(0o700).create(parent) {
256
+ if error.kind() != std::io::ErrorKind::AlreadyExists { return Err(error.into()); }
257
+ }
258
+ }
259
+ let metadata = std::fs::symlink_metadata(parent)?;
260
+ let physical_parent = parent.canonicalize()?;
261
+ if !metadata.is_dir() || metadata.uid() != unsafe { libc::geteuid() }
262
+ || metadata.mode() & 0o777 != 0o700 || (!named && physical_parent != parent)
263
+ { return Err(ContractError::Mismatch("workspace socket parent ownership").into()); }
264
+ let endpoint = physical_parent.join(endpoint.file_name().ok_or(ContractError::Invalid("workspace socket name"))?);
265
+ let session_name = selected.state.get("session_name").and_then(serde_json::Value::as_str)
266
+ .filter(|s| !s.is_empty() && !s.chars().any(|c| c.is_control() || c == ':'))
267
+ .ok_or(ContractError::Invalid("workspace team session name"))?.to_owned();
268
+ let generation = crate::state::projection::session_generation(&selected.state)
269
+ .unwrap_or(&session_name).to_owned();
270
+ let socket = workspace_socket(&endpoint)?;
271
+ let mut session = None;
272
+ if socket.is_some() {
273
+ let result = RealCommandRunner::default().run(&CommandRequest {
274
+ executable: binding.tmux.clone(), arguments: vec!["-u".into(), "-S".into(), endpoint.as_os_str().to_owned(),
275
+ "-N".into(), "list-sessions".into(), "-F".into(), "#{session_id}:#{session_name}".into()],
276
+ cwd: None, environment: EnvironmentDelta { remove: Default::default(), set: Default::default() },
277
+ stdin: None, budget: Duration::from_secs(5), limits: OutputLimits { stdout: 65536, stderr: 4096, stdin: 1 },
278
+ reject_stdout: None,
279
+ });
280
+ if result.success() {
281
+ let text = std::str::from_utf8(&result.stdout).map_err(|_| ContractError::Invalid("workspace session metadata"))?;
282
+ for line in text.lines() {
283
+ let (id, name) = line.split_once(':').ok_or(ContractError::Invalid("workspace session metadata"))?;
284
+ if !id.strip_prefix('$').is_some_and(|s| !s.is_empty() && s.bytes().all(|b| b.is_ascii_digit())) {
285
+ return Err(ContractError::Invalid("workspace session ID").into());
286
+ }
287
+ if name == session_name {
288
+ if session.replace(id.to_owned()).is_some() { return Err(Error::Fence.into()); }
289
+ }
290
+ }
291
+ } else if !(result.end == CommandEnd::Exited && result.exit_code == Some(1) && result.child_reaped
292
+ && result.stdout.is_empty() && result.stderr == format!("no server running on {}\n", endpoint.display()).as_bytes())
293
+ { return Err(ContractError::Mismatch("workspace server observation unavailable").into()); }
294
+ if workspace_socket(&endpoint)? != socket { return Err(Error::Fence.into()); }
295
+ }
296
+ if let Some(id) = &session {
297
+ let owner = transport.session_owner(&crate::transport::SessionName::new(&session_name))
298
+ .map_err(|_| ContractError::Mismatch("workspace session owner observation"))?;
299
+ let may_claim = claim.is_some_and(|target| target.shared_endpoint && target.created_session
300
+ && target.identity().scope == binding.scope && &target.identity().seat == seat
301
+ && target.endpoint == endpoint && target.session == *id
302
+ && Some((target.socket_device, target.socket_inode)) == socket);
303
+ if !owner.as_ref().is_some_and(|owner| Path::new(&owner.workspace) == binding.workspace.path
304
+ && owner.team == binding.team && owner.generation == generation)
305
+ && !(owner.is_none() && may_claim)
306
+ { return Err(ContractError::Mismatch("workspace session ownership").into()); }
307
+ } else if claim.is_some() { return Err(ContractError::Mismatch("committed workspace session disappeared").into()); }
308
+ if claim.is_some_and(|target| target.endpoint != endpoint
309
+ || session.as_deref() != Some(target.session.as_str()))
310
+ { return Err(ContractError::Mismatch("committed workspace target changed").into()); }
311
+ Ok((SharedTmux { endpoint, socket, session_name, session }, transport, generation))
312
+ }
313
+
314
+ /// Projection is saved first by the caller. Only an exact current target that
315
+ /// actually created this shared session may seed a missing root owner marker.
316
+ pub(super) fn bind_workspace_session(workspace: &Path, team: &str, seat: &SeatId) -> Result<(), BackendError> {
317
+ let backend = Backend::open_readonly(workspace, team)?;
318
+ let current = backend.store.seat(seat)?.ok_or(BackendError::Metadata)?;
319
+ let target = current.physical.as_ref().ok_or(BackendError::Metadata)?;
320
+ if !target.shared_endpoint { return Ok(()); }
321
+ let clock = RealClock::new();
322
+ let deadline = Duration::from_secs(5);
323
+ let mut host = TmuxHost::restore_owned(target.clone(), backend.binding.tmux.clone(),
324
+ settings(&backend.binding, registry::provider(current.provider.as_str())?).limits,
325
+ RealCommandRunner::default(), &clock, deadline)?;
326
+ host.validate_target(target, &clock, deadline)?;
327
+ let (topology, transport, generation) = workspace_tmux(&backend.binding, seat, Some(target))?;
328
+ let session = crate::transport::SessionName::new(&topology.session_name);
329
+ transport.set_session_owner_with_generation(&session, &backend.binding.workspace.path, team, &generation)
330
+ .map_err(|_| ContractError::Mismatch("workspace session owner commit"))?;
331
+ let owner = transport.session_owner(&session).map_err(|_| ContractError::Mismatch("workspace session owner readback"))?;
332
+ if !owner.is_some_and(|owner| Path::new(&owner.workspace) == backend.binding.workspace.path
333
+ && owner.team == team && owner.generation == generation)
334
+ { return Err(Error::Fence.into()); }
335
+ host.validate_target(target, &clock, deadline)?;
336
+ Ok(())
337
+ }
338
+
339
+ /// A session-wide legacy kill must not bypass canonical teardown of any
340
+ /// contract window, including a paused or currently unselected seat.
341
+ pub(crate) fn has_shared_windows(workspace: &Path, team: &str) -> Result<bool, BackendError> {
342
+ let cwd = resolve_cwd(workspace)?;
343
+ if !root_for(&cwd.path, &scope_for(&cwd, team)?).exists() { return Ok(false); }
344
+ let backend = Backend::open_readonly(&cwd.path, team)?;
345
+ Ok(backend.store.seats()?.iter().any(|seat|
346
+ seat.physical.as_ref().is_some_and(|target| target.shared_endpoint)))
347
+ }
348
+
208
349
  pub(super) fn settings(binding: &Binding, provider: registry::NativeProvider) -> PhysicalSettings {
209
350
  PhysicalSettings {
210
351
  tmux: binding.tmux.clone(),
@@ -290,6 +431,10 @@ fn request(
290
431
  return Err(ContractError::AmbiguousProfile.into());
291
432
  }
292
433
  profile.policy.require("native submit policy")?;
434
+ // The worker execs exactly the public command its runtime route was probed on.
435
+ let launcher = discovered.runtime.as_ref()
436
+ .ok_or(ContractError::Invalid("native runtime installation"))?
437
+ .launcher();
293
438
  Ok(LaunchRequest {
294
439
  provider: role.provider.as_str().into(),
295
440
  operation: Operation::Fresh,
@@ -303,6 +448,7 @@ fn request(
303
448
  identity,
304
449
  native: discovered.native.clone(),
305
450
  paths: LaunchPaths {
451
+ launcher,
306
452
  executable: discovered.engine.clone(),
307
453
  candidate: binding.candidate.clone(),
308
454
  cwd: binding.workspace.clone(),
@@ -385,6 +531,153 @@ pub fn preflight(team: &super::config::TeamConfig) -> Result<(), BackendError> {
385
531
  Ok(())
386
532
  }
387
533
 
534
+ #[derive(Debug)]
535
+ enum ExistingStart {
536
+ Committed(OperationRecord),
537
+ FinishReceipt(OperationRecord),
538
+ Pending(OperationRecord),
539
+ Resume(SeatRecord),
540
+ Blocked(OperationRecord),
541
+ }
542
+
543
+ // Receipt classification is read-only, never native admission or permission
544
+ // to replay an unfinished host effect. Check parent leases before old success.
545
+ fn existing_start(backend: &Backend, seat: &SeatId) -> Result<Option<ExistingStart>, BackendError> {
546
+ let unfinished: Vec<_> = backend.store.unfinished()?.into_iter().filter(|record| {
547
+ &record.target.identity.seat == seat
548
+ || record.parent.as_ref().is_some_and(|parent| &parent.identity.seat == seat)
549
+ }).collect();
550
+ if unfinished.len() > 1 { return Err(Error::Fence.into()); }
551
+ if let Some(record) = unfinished.into_iter().next() {
552
+ if record.target.identity.scope != backend.binding.scope { return Err(Error::Fence.into()); }
553
+ return Ok(Some(if record.phase == Phase::F4Commit && record.pending.is_none()
554
+ && matches!(record.kind, TransactionKind::Startup | TransactionKind::Restart
555
+ | TransactionKind::NewSeatFullSnapshot | TransactionKind::NativeNewSeat)
556
+ { ExistingStart::FinishReceipt(record) }
557
+ else if record.outcome == Outcome::Running { ExistingStart::Pending(record) }
558
+ else { ExistingStart::Blocked(record) }));
559
+ }
560
+ let Some(current) = backend.store.seat(seat)? else {
561
+ return match backend.store.creation_receipt(seat, None)? {
562
+ None => Ok(None),
563
+ Some(record) if record.outcome == Outcome::Compensated => Ok(None),
564
+ Some(_) => Err(Error::Fence.into()),
565
+ };
566
+ };
567
+ if current.identity.scope != backend.binding.scope { return Err(Error::Fence.into()); }
568
+ let record = backend.store.creation_receipt(seat, Some(&current.identity))?.ok_or(Error::Fence)?;
569
+ if record.outcome != Outcome::Committed || record.phase != Phase::F5Receipt || record.pending.is_some() {
570
+ return Ok(Some(ExistingStart::Blocked(record)));
571
+ }
572
+ Ok(Some(if current.status == SeatStatus::Stopped { ExistingStart::Resume(current) }
573
+ else { ExistingStart::Committed(record) }))
574
+ }
575
+
576
+ fn require_candidate(binding: &Binding) -> Result<(), BackendError> {
577
+ let candidate = std::env::current_exe()?.canonicalize()?;
578
+ if candidate != binding.candidate || fingerprint_file(&candidate, 1024 * 1024 * 1024,
579
+ Duration::from_secs(10))? != binding.candidate_sha256 { return Err(Error::Fence.into()); }
580
+ Ok(())
581
+ }
582
+
583
+ fn validate_existing(backend: &Backend, role: &RoleConfig, record: &OperationRecord) -> Result<SeatRecord, BackendError> {
584
+ let current = backend.store.assert_current(&record.target.identity)?;
585
+ if current.evidence_kind != EvidenceKind::Native || current.provider != role.provider
586
+ || current.status == SeatStatus::Unknown
587
+ || serde_json::to_vec(&read_role(&backend.binding, &current.identity)?).map_err(|_| BackendError::Metadata)?
588
+ != serde_json::to_vec(role).map_err(|_| BackendError::Metadata)?
589
+ { return Err(ContractError::Mismatch("existing native launch configuration").into()); }
590
+ let target = current.physical.as_ref().ok_or(BackendError::Metadata)?;
591
+ let clock = RealClock::new();
592
+ let deadline = Duration::from_secs(5);
593
+ let mut host = TmuxHost::restore_owned(target.clone(), backend.binding.tmux.clone(),
594
+ settings(&backend.binding, registry::provider(current.provider.as_str())?).limits,
595
+ RealCommandRunner::default(), &clock, deadline)?;
596
+ host.validate_target(target, &clock, deadline)?;
597
+ Ok(current)
598
+ }
599
+
600
+ fn receipt_error(record: OperationRecord) -> BackendError {
601
+ BackendError::Shutdown { operation: record.id, phase: record.phase,
602
+ outcome: record.outcome, failure: record.failure.or(record.pending) }
603
+ }
604
+
605
+ /// Plan only against this selected store and exact row (or an unbound seed).
606
+ /// A stale parent can be repaired only by its actual creation receipt, never
607
+ /// by selecting the greatest generation or adopting a discovered process.
608
+ pub(crate) fn start_needs_reconciliation(workspace: &Path, team: &str, seat: &SeatId, row: &serde_json::Value) -> Result<bool, BackendError> {
609
+ let backend = Backend::open_readonly(workspace, team)?;
610
+ require_candidate(&backend.binding)?;
611
+ let class = existing_start(&backend, seat)?;
612
+ let current = backend.store.seat(seat)?;
613
+ if current.as_ref().is_some_and(|seat| row.get("provider").and_then(serde_json::Value::as_str) != Some(seat.provider.as_str())) {
614
+ return Err(Error::Fence.into());
615
+ }
616
+ let matches = |identity: &InstanceIdentity| {
617
+ row.get("contract_scope").and_then(serde_json::Value::as_str) == Some(identity.scope.as_str())
618
+ && row.get("contract_instance").and_then(serde_json::Value::as_str) == Some(identity.instance.as_str())
619
+ && row.get("generation").and_then(serde_json::Value::as_u64) == Some(identity.generation.0)
620
+ };
621
+ let seed = ["contract_scope", "contract_instance", "generation", "session_id"].iter()
622
+ .all(|key| row.get(*key).is_none_or(serde_json::Value::is_null));
623
+ let record = match &class {
624
+ Some(ExistingStart::Committed(record) | ExistingStart::FinishReceipt(record)) => Some(record),
625
+ _ => None,
626
+ };
627
+ if !seed && !current.as_ref().is_some_and(|seat| matches(&seat.identity))
628
+ && !record.and_then(|record| record.parent.as_ref()).is_some_and(|parent| matches(&parent.identity)
629
+ && row.get("session_id").and_then(serde_json::Value::as_str)
630
+ == parent.session.as_ref().map(|session| session.native_session.as_str()))
631
+ { return Err(Error::Fence.into()); }
632
+ let needs_projection = seed || current.as_ref().is_some_and(|seat| !matches(&seat.identity)
633
+ || seat.status == SeatStatus::Starting
634
+ || row.get("session_id").and_then(serde_json::Value::as_str) != seat.session.as_ref().map(|session| session.native_session.as_str())
635
+ || (seat.status == SeatStatus::Stopped && row.get("status").and_then(serde_json::Value::as_str) != Some("stopped"))
636
+ || (seat.status != SeatStatus::Stopped && row.get("status").and_then(serde_json::Value::as_str) != Some("running")))
637
+ || matches!(class, Some(ExistingStart::FinishReceipt(_) | ExistingStart::Pending(_) | ExistingStart::Blocked(_)));
638
+ if needs_projection { return Ok(true); }
639
+ if let Some(current) = current.filter(|current| current.status != SeatStatus::Stopped) {
640
+ if let Some(target) = current.physical.as_ref().filter(|target| target.shared_endpoint) {
641
+ // A crash after JSON projection but before the owner marker is not
642
+ // a verified no-op. Reuse only this exact creator receipt, under
643
+ // the existing lifecycle lock; a foreign marker still refuses.
644
+ let (topology, transport, _) = workspace_tmux(&backend.binding, seat, Some(target))?;
645
+ return Ok(transport.session_owner(&crate::transport::SessionName::new(&topology.session_name))
646
+ .map_err(|_| ContractError::Mismatch("workspace session owner observation"))?.is_none());
647
+ }
648
+ }
649
+ Ok(false)
650
+ }
651
+
652
+ /// Read-only preflight, reused by the CLI before any role write or stop.
653
+ pub(crate) fn preflight_start_role(workspace: &Path, team: &str, role: &RoleConfig) -> Result<bool, BackendError> {
654
+ let backend = Backend::open_readonly(workspace, team)?;
655
+ require_candidate(&backend.binding)?;
656
+ match existing_start(&backend, &role.id)? {
657
+ Some(ExistingStart::Committed(record))
658
+ if backend.store.assert_current(&record.target.identity)?.physical.as_ref().is_some_and(|target|
659
+ team_agent_contract::host::process::sample_process(&target.process) == team_agent_contract::host::process::ProcessState::Exited) => {
660
+ prepare_resume(workspace, team, &role.id, Some(role))?;
661
+ },
662
+ Some(ExistingStart::Committed(record) | ExistingStart::FinishReceipt(record)) => { validate_existing(&backend, role, &record)?; },
663
+ Some(ExistingStart::Resume(_)) => { prepare_resume(workspace, team, &role.id, Some(role))?; },
664
+ Some(ExistingStart::Pending(record) | ExistingStart::Blocked(record)) => return Err(receipt_error(record)),
665
+ None => return Ok(true), // Caller must run full-team fresh preflight before writes.
666
+ }
667
+ Ok(false)
668
+ }
669
+
670
+ fn finish_receipt(backend: &mut Backend, record: OperationRecord) -> Result<OperationRecord, BackendError> {
671
+ let selected = registry::provider(record.target.provider.as_str())?;
672
+ let adapter = adapter(&backend.binding, &record.target.identity, &record.target.provider)?;
673
+ let hooks = adapter.hooks();
674
+ let clock = RealClock::new();
675
+ let mut host = PhysicalRuntime::new(Registration { descriptor: selected.descriptor(), hooks: &hooks,
676
+ controls: selected.controls(), startup: selected.startup(), session_panel: selected.session_panel() },
677
+ settings(&backend.binding, selected), record.id.clone(), &clock)?;
678
+ Ok(Lifecycle { store: &mut backend.store, host: &mut host, io: &mut NoNewIo }.recover(&record.id)?)
679
+ }
680
+
388
681
  /// Fresh startup is distinct from resume. An existing generation is never
389
682
  /// silently replaced with a new native session.
390
683
  pub fn start(
@@ -393,6 +686,36 @@ pub fn start(
393
686
  role: &RoleConfig,
394
687
  members: &[MemberRoute],
395
688
  ) -> Result<(Binding, OperationRecord), BackendError> {
689
+ let cwd = resolve_cwd(workspace)?;
690
+ let scope = scope_for(&cwd, team)?;
691
+ if root_for(&cwd.path, &scope).exists() {
692
+ let mut backend = Backend::open(&cwd.path, team)?;
693
+ require_candidate(&backend.binding)?;
694
+ match existing_start(&backend, &role.id)? {
695
+ Some(ExistingStart::Committed(record)) => {
696
+ let current = backend.store.assert_current(&record.target.identity)?;
697
+ if current.physical.as_ref().is_some_and(|target|
698
+ team_agent_contract::host::process::sample_process(&target.process) == team_agent_contract::host::process::ProcessState::Exited) {
699
+ let prepared = prepare_resume(workspace, team, &role.id, Some(role))?;
700
+ return Ok((backend.binding, resume(prepared)?));
701
+ }
702
+ validate_existing(&backend, role, &record)?;
703
+ return Ok((backend.binding, record));
704
+ },
705
+ Some(ExistingStart::FinishReceipt(record)) => {
706
+ validate_existing(&backend, role, &record)?;
707
+ let record = finish_receipt(&mut backend, record)?;
708
+ return Ok((backend.binding, record));
709
+ },
710
+ Some(ExistingStart::Resume(current)) => {
711
+ if current.provider != role.provider { return Err(Error::Fence.into()); }
712
+ let prepared = prepare_resume(workspace, team, &role.id, Some(role))?;
713
+ return Ok((backend.binding, resume(prepared)?));
714
+ },
715
+ Some(ExistingStart::Pending(record) | ExistingStart::Blocked(record)) => return Err(receipt_error(record)),
716
+ None => {},
717
+ }
718
+ }
396
719
  let selected = registry::provider(role.provider.as_str())?;
397
720
  let descriptor = selected.descriptor();
398
721
  let discovered = discovery::discover_runtime(&role.provider, workspace)?;
@@ -440,7 +763,7 @@ pub fn start(
440
763
  {
441
764
  return Err(Error::Fence.into());
442
765
  }
443
- if backend.store.seat(&role.id)?.is_some() {
766
+ if existing_start(&backend, &role.id)?.is_some() {
444
767
  return Err(Error::Conflict.into());
445
768
  }
446
769
  let route = backend.binding.framework().route()?;
@@ -490,6 +813,8 @@ pub fn start(
490
813
  Some(&discovered.catalog),
491
814
  )?;
492
815
  let plan = adapter.plan(&resolved)?;
816
+ validate_launch_plan(descriptor, &resolved, &plan)?;
817
+ let (workspace_topology, _, _) = workspace_tmux(&backend.binding, &role.id, None)?;
493
818
  let operation = OperationId::new(format!("start-{}", request.identity.instance.as_str()))?;
494
819
  let mut io = ScopedMaterializer::new(
495
820
  descriptor,
@@ -512,6 +837,7 @@ pub fn start(
512
837
  &clock,
513
838
  )?;
514
839
  physical.evidence = policy_evidence(&role.provider, &request.native, candidate_sha256)?;
840
+ physical.workspace_tmux = Some(workspace_topology);
515
841
  let record = Lifecycle {
516
842
  store: &mut backend.store,
517
843
  host: &mut physical,
@@ -645,6 +971,24 @@ pub fn resume(prepared: PreparedResume) -> Result<OperationRecord, BackendError>
645
971
  let plan = adapter.plan(&resolved)?;
646
972
  validate_launch_plan(descriptor, &resolved, &plan)?;
647
973
  write_role(&backend.binding, &prepared.request.identity, &prepared.role)?;
974
+ let shared_parent = parent.physical.as_ref().is_some_and(|target| target.shared_endpoint);
975
+ let workspace_topology = if shared_parent {
976
+ // Validate root topology before stopping. Capture again only after the
977
+ // authorized stop, since its last pane may destroy the old session ID.
978
+ let (before, _, _) = workspace_tmux(&backend.binding, &prepared.role.id, None)?;
979
+ if parent.status != SeatStatus::Stopped {
980
+ let target = parent.physical.as_ref().ok_or(BackendError::Metadata)?;
981
+ if before.endpoint != target.endpoint || before.session.as_deref() != Some(target.session.as_str()) {
982
+ return Err(ContractError::Mismatch("resume workspace session").into());
983
+ }
984
+ let stopped = stop(&backend.binding.workspace.path, &backend.binding.team, &prepared.role.id)?;
985
+ if stopped.outcome != Outcome::Committed {
986
+ return Err(BackendError::Shutdown { operation: stopped.id, phase: stopped.phase,
987
+ outcome: stopped.outcome, failure: stopped.failure });
988
+ }
989
+ }
990
+ Some(workspace_tmux(&backend.binding, &prepared.role.id, None)?.0)
991
+ } else { None };
648
992
  let operation = OperationId::new(format!("resume-{}", prepared.request.identity.instance.as_str()))?;
649
993
  let mut io = ScopedMaterializer::new(descriptor, &resolved, &plan, operation.clone(), RealCommandRunner::default())?;
650
994
  let clock = RealClock::new();
@@ -656,6 +1000,7 @@ pub fn resume(prepared: PreparedResume) -> Result<OperationRecord, BackendError>
656
1000
  settings(&backend.binding, selected), operation.clone(), &clock,
657
1001
  )?;
658
1002
  physical.evidence = policy_evidence(&prepared.role.provider, &prepared.request.native, backend.binding.candidate_sha256)?;
1003
+ physical.workspace_tmux = workspace_topology;
659
1004
  let record = Lifecycle { store: &mut backend.store, host: &mut physical, io: &mut io }.startup(
660
1005
  &Adapter { descriptor, hooks: &hooks, catalog: Some(&prepared.discovered.catalog) },
661
1006
  &prepared.request,
@@ -853,9 +1198,157 @@ mod tests {
853
1198
  } };
854
1199
  Self { root, binding, role, identity }
855
1200
  }
1201
+
1202
+ // Receipt-only fixtures never authorize a native action; the runtime
1203
+ // must separately revalidate candidate, role, socket and process birth.
1204
+ fn canonical(&mut self, status: SeatStatus, phase: Phase, outcome: Outcome, pending: Option<&str>) -> Backend {
1205
+ self.binding.transport_root = self.binding.workspace.path.join("native-store");
1206
+ self.binding.endpoint = endpoint(&self.binding.scope);
1207
+ let store = ContractStore::create(&self.binding.transport_root, self.binding.scope.clone(), &self.binding.endpoint).unwrap();
1208
+ let target = SeatRecord { identity: self.identity.clone(), provider: self.role.provider.clone(),
1209
+ native: NativeIdentity { version: "fixture".into(), harness: "fixture".into(), ui: "controlled".into(),
1210
+ platform: Platform::MacOs, executable_sha256: digest(b"fixture") },
1211
+ cwd: self.binding.workspace.clone(), endpoint: self.binding.endpoint.clone(), pane: "%1".into(),
1212
+ binding_key: "controlled".into(), profile: "fixture".into(), server_key: "fixture".into(),
1213
+ evidence_kind: EvidenceKind::Fixture, status, process: None, physical: None, session: None,
1214
+ resources: vec![], workspace_resources: vec![], bootstrap_used: false };
1215
+ let operation = OperationRecord { id: OperationId::new("controlled-start").unwrap(), kind: TransactionKind::Startup,
1216
+ target: target.clone(), parent: None, phase, pending: pending.map(str::to_owned), resources: vec![],
1217
+ effect: team_agent_contract::contract::delivery::DeliveryEffect::NoEffect, outcome, preserved: vec![], failure: None };
1218
+ let db = rusqlite::Connection::open(self.binding.transport_root.join("contract.db")).unwrap();
1219
+ db.execute("INSERT INTO contract_seats VALUES(?1,?2)", rusqlite::params![self.identity.seat.as_str(), serde_json::to_string(&target).unwrap()]).unwrap();
1220
+ db.execute("INSERT INTO contract_generations VALUES(?1,?2)", rusqlite::params![self.identity.seat.as_str(), self.identity.generation.0]).unwrap();
1221
+ db.execute("INSERT INTO contract_instances VALUES(?1,?2,?3)", rusqlite::params![self.identity.instance.as_str(), self.identity.seat.as_str(), self.identity.generation.0]).unwrap();
1222
+ db.execute("INSERT INTO contract_operations VALUES(?1,?2)", rusqlite::params![operation.id.as_str(), serde_json::to_string(&operation).unwrap()]).unwrap();
1223
+ if matches!(outcome, Outcome::Running | Outcome::NeedsRecovery) {
1224
+ db.execute("INSERT INTO contract_leases VALUES(?1,?2)", rusqlite::params![self.identity.seat.as_str(), operation.id.as_str()]).unwrap();
1225
+ }
1226
+ std::fs::write(root_for(&self.binding.workspace.path, &self.binding.scope).join("framework-binding.json"),
1227
+ serde_json::to_vec(&self.binding).unwrap()).unwrap();
1228
+ drop(db); drop(store);
1229
+ Backend::open_readonly(&self.binding.workspace.path, "test").unwrap()
1230
+ }
856
1231
  }
857
1232
  impl Drop for RoleFixture { fn drop(&mut self) { let _ = std::fs::remove_dir_all(&self.root); } }
858
1233
 
1234
+ fn assert_receipt_class(status: SeatStatus, phase: Phase, outcome: Outcome, pending: Option<&str>, expected: &str) {
1235
+ let mut fixture = RoleFixture::new();
1236
+ let backend = fixture.canonical(status, phase, outcome, pending);
1237
+ let before = serde_json::to_vec(&backend.store.seat(&fixture.identity.seat).unwrap()).unwrap();
1238
+ let receipt = backend.store.creation_receipt(&fixture.identity.seat, Some(&fixture.identity)).unwrap().unwrap();
1239
+ assert_eq!(receipt.phase, phase);
1240
+ assert_eq!(receipt.outcome, outcome);
1241
+ let result = existing_start(&backend, &fixture.identity.seat);
1242
+ assert_eq!(serde_json::to_vec(&backend.store.seat(&fixture.identity.seat).unwrap()).unwrap(), before);
1243
+ assert_eq!(backend.store.operation(&receipt.id).unwrap(), receipt);
1244
+ let classified = result.unwrap_or_else(|error| panic!("{expected} must not collapse to unconditional Conflict: {error}"));
1245
+ let matches = match classified {
1246
+ Some(ExistingStart::Committed(record)) => expected == "committed" && record.id == receipt.id,
1247
+ Some(ExistingStart::FinishReceipt(record)) => expected == "finish" && record.id == receipt.id,
1248
+ Some(ExistingStart::Pending(record)) => expected == "pending" && record.id == receipt.id,
1249
+ Some(ExistingStart::Resume(record)) => expected == "resume" && record.identity == fixture.identity,
1250
+ Some(ExistingStart::Blocked(record)) => expected == "blocked" && record.id == receipt.id,
1251
+ None => false,
1252
+ };
1253
+ assert!(matches, "wrong receipt class for {expected}");
1254
+ }
1255
+
1256
+ #[test]
1257
+ fn startup_receipt_red_committed_is_reused_not_conflicted() {
1258
+ assert_receipt_class(SeatStatus::Ready, Phase::F5Receipt, Outcome::Committed, None, "committed");
1259
+ }
1260
+ #[test]
1261
+ fn startup_receipt_red_f4_is_receipt_completion_not_fresh() {
1262
+ assert_receipt_class(SeatStatus::Starting, Phase::F4Commit, Outcome::Running, None, "finish");
1263
+ }
1264
+ #[test]
1265
+ fn startup_receipt_red_inflight_is_pending_not_replayed() {
1266
+ assert_receipt_class(SeatStatus::Starting, Phase::F3Spawn, Outcome::Running, Some("spawn"), "pending");
1267
+ }
1268
+ #[test]
1269
+ fn startup_receipt_red_stopped_is_resume_not_fresh() {
1270
+ assert_receipt_class(SeatStatus::Stopped, Phase::F5Receipt, Outcome::Committed, None, "resume");
1271
+ }
1272
+ #[test]
1273
+ fn startup_receipt_red_uncertain_is_blocked_with_original_receipt() {
1274
+ assert_receipt_class(SeatStatus::Starting, Phase::F3Spawn, Outcome::NeedsRecovery, Some("spawn"), "blocked");
1275
+ }
1276
+
1277
+ #[test]
1278
+ fn startup_receipt_projection_repair_refuses_foreign_or_guessed_identity() {
1279
+ let mut fixture = RoleFixture::new();
1280
+ fixture.binding.candidate = std::env::current_exe().unwrap().canonicalize().unwrap();
1281
+ fixture.binding.candidate_sha256 = fingerprint_file(&fixture.binding.candidate, 1024 * 1024 * 1024, Duration::from_secs(10)).unwrap();
1282
+ let backend = fixture.canonical(SeatStatus::Starting, Phase::F4Commit, Outcome::Running, None);
1283
+ let original = backend.store.creation_receipt(&fixture.identity.seat, Some(&fixture.identity)).unwrap().unwrap();
1284
+ let seed = serde_json::json!({"provider":"cursor","status":"unknown"});
1285
+ assert!(start_needs_reconciliation(&fixture.root, "test", &fixture.identity.seat, &seed).unwrap());
1286
+ let exact = serde_json::json!({"provider":"cursor","status":"unknown","contract_scope":fixture.identity.scope,
1287
+ "contract_instance":fixture.identity.instance,"generation":fixture.identity.generation});
1288
+ assert!(start_needs_reconciliation(&fixture.root, "test", &fixture.identity.seat, &exact).unwrap());
1289
+ for (key, value) in [("provider", serde_json::json!("grok_build")), ("contract_scope", serde_json::json!("foreign")),
1290
+ ("contract_instance", serde_json::json!("another")), ("generation", serde_json::json!(2))] {
1291
+ let mut forged = exact.clone(); forged[key] = value;
1292
+ assert!(start_needs_reconciliation(&fixture.root, "test", &fixture.identity.seat, &forged).is_err(), "{key}");
1293
+ }
1294
+ assert_eq!(backend.store.operation(&original.id).unwrap(), original);
1295
+ assert!(preflight_start_role(&fixture.root, "test", &fixture.role).is_err(), "classification is not Native admission");
1296
+ }
1297
+
1298
+ #[test]
1299
+ fn startup_receipt_fixture_cannot_authorize_reuse_or_native_input() {
1300
+ let mut fixture = RoleFixture::new();
1301
+ let backend = fixture.canonical(SeatStatus::Ready, Phase::F5Receipt, Outcome::Committed, None);
1302
+ let record = backend.store.creation_receipt(&fixture.identity.seat, Some(&fixture.identity)).unwrap().unwrap();
1303
+ assert!(validate_existing(&backend, &fixture.role, &record).is_err());
1304
+ assert_eq!(backend.store.operation(&record.id).unwrap(), record);
1305
+ }
1306
+
1307
+ #[test]
1308
+ fn startup_receipt_unfinished_parent_wins_over_old_committed_generation() {
1309
+ let mut fixture = RoleFixture::new();
1310
+ let backend = fixture.canonical(SeatStatus::Ready, Phase::F5Receipt, Outcome::Committed, None);
1311
+ let mut interrupted = backend.store.creation_receipt(&fixture.identity.seat, Some(&fixture.identity)).unwrap().unwrap();
1312
+ interrupted.parent = Some(interrupted.target.clone());
1313
+ interrupted.id = OperationId::new("uncertain-restart").unwrap();
1314
+ interrupted.kind = TransactionKind::Restart;
1315
+ interrupted.target.identity.instance = InstanceId::new("second").unwrap();
1316
+ interrupted.target.identity.generation = Generation(2);
1317
+ interrupted.phase = Phase::F3Spawn;
1318
+ interrupted.pending = Some("spawn".into());
1319
+ interrupted.outcome = Outcome::NeedsRecovery;
1320
+ let db = rusqlite::Connection::open(fixture.binding.transport_root.join("contract.db")).unwrap();
1321
+ db.execute("INSERT INTO contract_operations VALUES(?1,?2)", rusqlite::params![interrupted.id.as_str(), serde_json::to_string(&interrupted).unwrap()]).unwrap();
1322
+ assert!(matches!(existing_start(&backend, &fixture.identity.seat).unwrap(),
1323
+ Some(ExistingStart::Blocked(record)) if record == interrupted));
1324
+ assert_eq!(backend.store.seat(&fixture.identity.seat).unwrap().unwrap().identity, fixture.identity);
1325
+ }
1326
+
1327
+ #[test]
1328
+ fn startup_receipt_missing_committed_seat_refuses_but_compensated_allows_fresh_proposal() {
1329
+ for outcome in [Outcome::Committed, Outcome::Compensated] {
1330
+ let mut fixture = RoleFixture::new();
1331
+ let backend = fixture.canonical(SeatStatus::Stopped, Phase::F5Receipt, outcome, None);
1332
+ let db = rusqlite::Connection::open(fixture.binding.transport_root.join("contract.db")).unwrap();
1333
+ db.execute("DELETE FROM contract_seats", []).unwrap();
1334
+ let result = existing_start(&backend, &fixture.identity.seat);
1335
+ if outcome == Outcome::Committed { assert!(result.is_err()); }
1336
+ else { assert!(result.unwrap().is_none()); }
1337
+ assert_eq!(backend.store.propose_identity(&fixture.identity.seat).unwrap().generation, Generation(2));
1338
+ }
1339
+ }
1340
+
1341
+ #[test]
1342
+ fn startup_receipt_lookup_refuses_cross_scope_and_generation_fallback() {
1343
+ let mut fixture = RoleFixture::new();
1344
+ let backend = fixture.canonical(SeatStatus::Ready, Phase::F5Receipt, Outcome::Committed, None);
1345
+ let mut wrong = fixture.identity.clone(); wrong.generation = Generation(2);
1346
+ assert!(backend.store.creation_receipt(&fixture.identity.seat, Some(&wrong)).is_err());
1347
+ wrong = fixture.identity.clone(); wrong.scope = ScopeId::new("foreign").unwrap();
1348
+ assert!(backend.store.creation_receipt(&fixture.identity.seat, Some(&wrong)).is_err());
1349
+ assert!(backend.store.creation_receipt(&SeatId::new("absent").unwrap(), None).unwrap().is_none());
1350
+ }
1351
+
859
1352
  #[test]
860
1353
  fn restart_skips_stopped_mirror_and_stopped_native_store_before_resume_discovery() {
861
1354
  for provider in ["cursor", "grok_build"] {
@@ -998,6 +1491,9 @@ mod tests {
998
1491
  ui: "metadata".into(), platform: Platform::MacOs, executable_sha256: digest(b"launcher"),
999
1492
  };
1000
1493
  let mut discovery = Discovery {
1494
+ command: team_agent_contract::host::command::PublicCommand {
1495
+ name: "cursor-agent".into(), search_path: "/controlled".into(), entry: "/controlled/cursor-agent".into(),
1496
+ },
1001
1497
  runtime: None,
1002
1498
  engine: "/controlled/cursor-agent".into(), native: native.clone(),
1003
1499
  catalog: CatalogObservation { provider, native,