@team-agent/installer 0.5.121 → 0.5.123

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 (31) 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 +78 -42
  5. package/crates/team-agent/src/cli/intent/runtime_tests.rs +137 -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/contract_runtime/backend.rs +490 -2
  9. package/crates/team-agent/src/contract_runtime/commands.rs +38 -24
  10. package/crates/team-agent/src/contract_runtime/forward.rs +59 -0
  11. package/crates/team-agent/src/contract_runtime/framework.rs +23 -17
  12. package/crates/team-agent/src/coordinator/tests/health_sync.rs +27 -8
  13. package/crates/team-agent/src/lifecycle/launch/quick_start.rs +6 -17
  14. package/crates/team-agent/src/lifecycle/launch/quick_start_transport.rs +26 -19
  15. package/crates/team-agent/src/lifecycle/launch/spawn.rs +19 -2
  16. package/crates/team-agent/src/lifecycle/restart/agent.rs +3 -0
  17. package/crates/team-agent/src/lifecycle/restart/common.rs +3 -0
  18. package/crates/team-agent/src/lifecycle/restart/rebuild.rs +100 -31
  19. package/crates/team-agent/src/lifecycle/restart.rs +1 -0
  20. package/crates/team-agent/src/lifecycle/tests/acceptance_b_batch_red.rs +16 -3
  21. package/crates/team-agent/src/lifecycle/tests/cursor_restart_resume_red.rs +132 -1
  22. package/crates/team-agent/src/lifecycle/tests/launch_spawn.rs +7 -5
  23. package/crates/team-agent/src/lifecycle/tests/subprep_codex_trust_roundtrip_red.rs +8 -2
  24. package/crates/team-agent/src/mcp_server/readiness.rs +66 -3
  25. package/crates/team-agent/src/mcp_server/readiness_tests.rs +30 -0
  26. package/crates/team-agent/src/messaging/delivery_consumption_tests.rs +12 -1
  27. package/crates/team-agent/src/messaging/tests/dup_inject.rs +48 -4
  28. package/crates/team-agent/src/messaging/tests/spine.rs +45 -14
  29. package/crates/team-agent/src/provider/wire.rs +2 -1
  30. package/npm/install.mjs +17 -97
  31. 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(),
@@ -385,6 +526,153 @@ pub fn preflight(team: &super::config::TeamConfig) -> Result<(), BackendError> {
385
526
  Ok(())
386
527
  }
387
528
 
529
+ #[derive(Debug)]
530
+ enum ExistingStart {
531
+ Committed(OperationRecord),
532
+ FinishReceipt(OperationRecord),
533
+ Pending(OperationRecord),
534
+ Resume(SeatRecord),
535
+ Blocked(OperationRecord),
536
+ }
537
+
538
+ // Receipt classification is read-only, never native admission or permission
539
+ // to replay an unfinished host effect. Check parent leases before old success.
540
+ fn existing_start(backend: &Backend, seat: &SeatId) -> Result<Option<ExistingStart>, BackendError> {
541
+ let unfinished: Vec<_> = backend.store.unfinished()?.into_iter().filter(|record| {
542
+ &record.target.identity.seat == seat
543
+ || record.parent.as_ref().is_some_and(|parent| &parent.identity.seat == seat)
544
+ }).collect();
545
+ if unfinished.len() > 1 { return Err(Error::Fence.into()); }
546
+ if let Some(record) = unfinished.into_iter().next() {
547
+ if record.target.identity.scope != backend.binding.scope { return Err(Error::Fence.into()); }
548
+ return Ok(Some(if record.phase == Phase::F4Commit && record.pending.is_none()
549
+ && matches!(record.kind, TransactionKind::Startup | TransactionKind::Restart
550
+ | TransactionKind::NewSeatFullSnapshot | TransactionKind::NativeNewSeat)
551
+ { ExistingStart::FinishReceipt(record) }
552
+ else if record.outcome == Outcome::Running { ExistingStart::Pending(record) }
553
+ else { ExistingStart::Blocked(record) }));
554
+ }
555
+ let Some(current) = backend.store.seat(seat)? else {
556
+ return match backend.store.creation_receipt(seat, None)? {
557
+ None => Ok(None),
558
+ Some(record) if record.outcome == Outcome::Compensated => Ok(None),
559
+ Some(_) => Err(Error::Fence.into()),
560
+ };
561
+ };
562
+ if current.identity.scope != backend.binding.scope { return Err(Error::Fence.into()); }
563
+ let record = backend.store.creation_receipt(seat, Some(&current.identity))?.ok_or(Error::Fence)?;
564
+ if record.outcome != Outcome::Committed || record.phase != Phase::F5Receipt || record.pending.is_some() {
565
+ return Ok(Some(ExistingStart::Blocked(record)));
566
+ }
567
+ Ok(Some(if current.status == SeatStatus::Stopped { ExistingStart::Resume(current) }
568
+ else { ExistingStart::Committed(record) }))
569
+ }
570
+
571
+ fn require_candidate(binding: &Binding) -> Result<(), BackendError> {
572
+ let candidate = std::env::current_exe()?.canonicalize()?;
573
+ if candidate != binding.candidate || fingerprint_file(&candidate, 1024 * 1024 * 1024,
574
+ Duration::from_secs(10))? != binding.candidate_sha256 { return Err(Error::Fence.into()); }
575
+ Ok(())
576
+ }
577
+
578
+ fn validate_existing(backend: &Backend, role: &RoleConfig, record: &OperationRecord) -> Result<SeatRecord, BackendError> {
579
+ let current = backend.store.assert_current(&record.target.identity)?;
580
+ if current.evidence_kind != EvidenceKind::Native || current.provider != role.provider
581
+ || current.status == SeatStatus::Unknown
582
+ || serde_json::to_vec(&read_role(&backend.binding, &current.identity)?).map_err(|_| BackendError::Metadata)?
583
+ != serde_json::to_vec(role).map_err(|_| BackendError::Metadata)?
584
+ { return Err(ContractError::Mismatch("existing native launch configuration").into()); }
585
+ let target = current.physical.as_ref().ok_or(BackendError::Metadata)?;
586
+ let clock = RealClock::new();
587
+ let deadline = Duration::from_secs(5);
588
+ let mut host = TmuxHost::restore_owned(target.clone(), backend.binding.tmux.clone(),
589
+ settings(&backend.binding, registry::provider(current.provider.as_str())?).limits,
590
+ RealCommandRunner::default(), &clock, deadline)?;
591
+ host.validate_target(target, &clock, deadline)?;
592
+ Ok(current)
593
+ }
594
+
595
+ fn receipt_error(record: OperationRecord) -> BackendError {
596
+ BackendError::Shutdown { operation: record.id, phase: record.phase,
597
+ outcome: record.outcome, failure: record.failure.or(record.pending) }
598
+ }
599
+
600
+ /// Plan only against this selected store and exact row (or an unbound seed).
601
+ /// A stale parent can be repaired only by its actual creation receipt, never
602
+ /// by selecting the greatest generation or adopting a discovered process.
603
+ pub(crate) fn start_needs_reconciliation(workspace: &Path, team: &str, seat: &SeatId, row: &serde_json::Value) -> Result<bool, BackendError> {
604
+ let backend = Backend::open_readonly(workspace, team)?;
605
+ require_candidate(&backend.binding)?;
606
+ let class = existing_start(&backend, seat)?;
607
+ let current = backend.store.seat(seat)?;
608
+ if current.as_ref().is_some_and(|seat| row.get("provider").and_then(serde_json::Value::as_str) != Some(seat.provider.as_str())) {
609
+ return Err(Error::Fence.into());
610
+ }
611
+ let matches = |identity: &InstanceIdentity| {
612
+ row.get("contract_scope").and_then(serde_json::Value::as_str) == Some(identity.scope.as_str())
613
+ && row.get("contract_instance").and_then(serde_json::Value::as_str) == Some(identity.instance.as_str())
614
+ && row.get("generation").and_then(serde_json::Value::as_u64) == Some(identity.generation.0)
615
+ };
616
+ let seed = ["contract_scope", "contract_instance", "generation", "session_id"].iter()
617
+ .all(|key| row.get(*key).is_none_or(serde_json::Value::is_null));
618
+ let record = match &class {
619
+ Some(ExistingStart::Committed(record) | ExistingStart::FinishReceipt(record)) => Some(record),
620
+ _ => None,
621
+ };
622
+ if !seed && !current.as_ref().is_some_and(|seat| matches(&seat.identity))
623
+ && !record.and_then(|record| record.parent.as_ref()).is_some_and(|parent| matches(&parent.identity)
624
+ && row.get("session_id").and_then(serde_json::Value::as_str)
625
+ == parent.session.as_ref().map(|session| session.native_session.as_str()))
626
+ { return Err(Error::Fence.into()); }
627
+ let needs_projection = seed || current.as_ref().is_some_and(|seat| !matches(&seat.identity)
628
+ || seat.status == SeatStatus::Starting
629
+ || row.get("session_id").and_then(serde_json::Value::as_str) != seat.session.as_ref().map(|session| session.native_session.as_str())
630
+ || (seat.status == SeatStatus::Stopped && row.get("status").and_then(serde_json::Value::as_str) != Some("stopped"))
631
+ || (seat.status != SeatStatus::Stopped && row.get("status").and_then(serde_json::Value::as_str) != Some("running")))
632
+ || matches!(class, Some(ExistingStart::FinishReceipt(_) | ExistingStart::Pending(_) | ExistingStart::Blocked(_)));
633
+ if needs_projection { return Ok(true); }
634
+ if let Some(current) = current.filter(|current| current.status != SeatStatus::Stopped) {
635
+ if let Some(target) = current.physical.as_ref().filter(|target| target.shared_endpoint) {
636
+ // A crash after JSON projection but before the owner marker is not
637
+ // a verified no-op. Reuse only this exact creator receipt, under
638
+ // the existing lifecycle lock; a foreign marker still refuses.
639
+ let (topology, transport, _) = workspace_tmux(&backend.binding, seat, Some(target))?;
640
+ return Ok(transport.session_owner(&crate::transport::SessionName::new(&topology.session_name))
641
+ .map_err(|_| ContractError::Mismatch("workspace session owner observation"))?.is_none());
642
+ }
643
+ }
644
+ Ok(false)
645
+ }
646
+
647
+ /// Read-only preflight, reused by the CLI before any role write or stop.
648
+ pub(crate) fn preflight_start_role(workspace: &Path, team: &str, role: &RoleConfig) -> Result<bool, BackendError> {
649
+ let backend = Backend::open_readonly(workspace, team)?;
650
+ require_candidate(&backend.binding)?;
651
+ match existing_start(&backend, &role.id)? {
652
+ Some(ExistingStart::Committed(record))
653
+ if backend.store.assert_current(&record.target.identity)?.physical.as_ref().is_some_and(|target|
654
+ team_agent_contract::host::process::sample_process(&target.process) == team_agent_contract::host::process::ProcessState::Exited) => {
655
+ prepare_resume(workspace, team, &role.id, Some(role))?;
656
+ },
657
+ Some(ExistingStart::Committed(record) | ExistingStart::FinishReceipt(record)) => { validate_existing(&backend, role, &record)?; },
658
+ Some(ExistingStart::Resume(_)) => { prepare_resume(workspace, team, &role.id, Some(role))?; },
659
+ Some(ExistingStart::Pending(record) | ExistingStart::Blocked(record)) => return Err(receipt_error(record)),
660
+ None => return Ok(true), // Caller must run full-team fresh preflight before writes.
661
+ }
662
+ Ok(false)
663
+ }
664
+
665
+ fn finish_receipt(backend: &mut Backend, record: OperationRecord) -> Result<OperationRecord, BackendError> {
666
+ let selected = registry::provider(record.target.provider.as_str())?;
667
+ let adapter = adapter(&backend.binding, &record.target.identity, &record.target.provider)?;
668
+ let hooks = adapter.hooks();
669
+ let clock = RealClock::new();
670
+ let mut host = PhysicalRuntime::new(Registration { descriptor: selected.descriptor(), hooks: &hooks,
671
+ controls: selected.controls(), startup: selected.startup(), session_panel: selected.session_panel() },
672
+ settings(&backend.binding, selected), record.id.clone(), &clock)?;
673
+ Ok(Lifecycle { store: &mut backend.store, host: &mut host, io: &mut NoNewIo }.recover(&record.id)?)
674
+ }
675
+
388
676
  /// Fresh startup is distinct from resume. An existing generation is never
389
677
  /// silently replaced with a new native session.
390
678
  pub fn start(
@@ -393,6 +681,36 @@ pub fn start(
393
681
  role: &RoleConfig,
394
682
  members: &[MemberRoute],
395
683
  ) -> Result<(Binding, OperationRecord), BackendError> {
684
+ let cwd = resolve_cwd(workspace)?;
685
+ let scope = scope_for(&cwd, team)?;
686
+ if root_for(&cwd.path, &scope).exists() {
687
+ let mut backend = Backend::open(&cwd.path, team)?;
688
+ require_candidate(&backend.binding)?;
689
+ match existing_start(&backend, &role.id)? {
690
+ Some(ExistingStart::Committed(record)) => {
691
+ let current = backend.store.assert_current(&record.target.identity)?;
692
+ if current.physical.as_ref().is_some_and(|target|
693
+ team_agent_contract::host::process::sample_process(&target.process) == team_agent_contract::host::process::ProcessState::Exited) {
694
+ let prepared = prepare_resume(workspace, team, &role.id, Some(role))?;
695
+ return Ok((backend.binding, resume(prepared)?));
696
+ }
697
+ validate_existing(&backend, role, &record)?;
698
+ return Ok((backend.binding, record));
699
+ },
700
+ Some(ExistingStart::FinishReceipt(record)) => {
701
+ validate_existing(&backend, role, &record)?;
702
+ let record = finish_receipt(&mut backend, record)?;
703
+ return Ok((backend.binding, record));
704
+ },
705
+ Some(ExistingStart::Resume(current)) => {
706
+ if current.provider != role.provider { return Err(Error::Fence.into()); }
707
+ let prepared = prepare_resume(workspace, team, &role.id, Some(role))?;
708
+ return Ok((backend.binding, resume(prepared)?));
709
+ },
710
+ Some(ExistingStart::Pending(record) | ExistingStart::Blocked(record)) => return Err(receipt_error(record)),
711
+ None => {},
712
+ }
713
+ }
396
714
  let selected = registry::provider(role.provider.as_str())?;
397
715
  let descriptor = selected.descriptor();
398
716
  let discovered = discovery::discover_runtime(&role.provider, workspace)?;
@@ -440,7 +758,7 @@ pub fn start(
440
758
  {
441
759
  return Err(Error::Fence.into());
442
760
  }
443
- if backend.store.seat(&role.id)?.is_some() {
761
+ if existing_start(&backend, &role.id)?.is_some() {
444
762
  return Err(Error::Conflict.into());
445
763
  }
446
764
  let route = backend.binding.framework().route()?;
@@ -490,6 +808,8 @@ pub fn start(
490
808
  Some(&discovered.catalog),
491
809
  )?;
492
810
  let plan = adapter.plan(&resolved)?;
811
+ validate_launch_plan(descriptor, &resolved, &plan)?;
812
+ let (workspace_topology, _, _) = workspace_tmux(&backend.binding, &role.id, None)?;
493
813
  let operation = OperationId::new(format!("start-{}", request.identity.instance.as_str()))?;
494
814
  let mut io = ScopedMaterializer::new(
495
815
  descriptor,
@@ -512,6 +832,7 @@ pub fn start(
512
832
  &clock,
513
833
  )?;
514
834
  physical.evidence = policy_evidence(&role.provider, &request.native, candidate_sha256)?;
835
+ physical.workspace_tmux = Some(workspace_topology);
515
836
  let record = Lifecycle {
516
837
  store: &mut backend.store,
517
838
  host: &mut physical,
@@ -645,6 +966,24 @@ pub fn resume(prepared: PreparedResume) -> Result<OperationRecord, BackendError>
645
966
  let plan = adapter.plan(&resolved)?;
646
967
  validate_launch_plan(descriptor, &resolved, &plan)?;
647
968
  write_role(&backend.binding, &prepared.request.identity, &prepared.role)?;
969
+ let shared_parent = parent.physical.as_ref().is_some_and(|target| target.shared_endpoint);
970
+ let workspace_topology = if shared_parent {
971
+ // Validate root topology before stopping. Capture again only after the
972
+ // authorized stop, since its last pane may destroy the old session ID.
973
+ let (before, _, _) = workspace_tmux(&backend.binding, &prepared.role.id, None)?;
974
+ if parent.status != SeatStatus::Stopped {
975
+ let target = parent.physical.as_ref().ok_or(BackendError::Metadata)?;
976
+ if before.endpoint != target.endpoint || before.session.as_deref() != Some(target.session.as_str()) {
977
+ return Err(ContractError::Mismatch("resume workspace session").into());
978
+ }
979
+ let stopped = stop(&backend.binding.workspace.path, &backend.binding.team, &prepared.role.id)?;
980
+ if stopped.outcome != Outcome::Committed {
981
+ return Err(BackendError::Shutdown { operation: stopped.id, phase: stopped.phase,
982
+ outcome: stopped.outcome, failure: stopped.failure });
983
+ }
984
+ }
985
+ Some(workspace_tmux(&backend.binding, &prepared.role.id, None)?.0)
986
+ } else { None };
648
987
  let operation = OperationId::new(format!("resume-{}", prepared.request.identity.instance.as_str()))?;
649
988
  let mut io = ScopedMaterializer::new(descriptor, &resolved, &plan, operation.clone(), RealCommandRunner::default())?;
650
989
  let clock = RealClock::new();
@@ -656,6 +995,7 @@ pub fn resume(prepared: PreparedResume) -> Result<OperationRecord, BackendError>
656
995
  settings(&backend.binding, selected), operation.clone(), &clock,
657
996
  )?;
658
997
  physical.evidence = policy_evidence(&prepared.role.provider, &prepared.request.native, backend.binding.candidate_sha256)?;
998
+ physical.workspace_tmux = workspace_topology;
659
999
  let record = Lifecycle { store: &mut backend.store, host: &mut physical, io: &mut io }.startup(
660
1000
  &Adapter { descriptor, hooks: &hooks, catalog: Some(&prepared.discovered.catalog) },
661
1001
  &prepared.request,
@@ -853,9 +1193,157 @@ mod tests {
853
1193
  } };
854
1194
  Self { root, binding, role, identity }
855
1195
  }
1196
+
1197
+ // Receipt-only fixtures never authorize a native action; the runtime
1198
+ // must separately revalidate candidate, role, socket and process birth.
1199
+ fn canonical(&mut self, status: SeatStatus, phase: Phase, outcome: Outcome, pending: Option<&str>) -> Backend {
1200
+ self.binding.transport_root = self.binding.workspace.path.join("native-store");
1201
+ self.binding.endpoint = endpoint(&self.binding.scope);
1202
+ let store = ContractStore::create(&self.binding.transport_root, self.binding.scope.clone(), &self.binding.endpoint).unwrap();
1203
+ let target = SeatRecord { identity: self.identity.clone(), provider: self.role.provider.clone(),
1204
+ native: NativeIdentity { version: "fixture".into(), harness: "fixture".into(), ui: "controlled".into(),
1205
+ platform: Platform::MacOs, executable_sha256: digest(b"fixture") },
1206
+ cwd: self.binding.workspace.clone(), endpoint: self.binding.endpoint.clone(), pane: "%1".into(),
1207
+ binding_key: "controlled".into(), profile: "fixture".into(), server_key: "fixture".into(),
1208
+ evidence_kind: EvidenceKind::Fixture, status, process: None, physical: None, session: None,
1209
+ resources: vec![], workspace_resources: vec![], bootstrap_used: false };
1210
+ let operation = OperationRecord { id: OperationId::new("controlled-start").unwrap(), kind: TransactionKind::Startup,
1211
+ target: target.clone(), parent: None, phase, pending: pending.map(str::to_owned), resources: vec![],
1212
+ effect: team_agent_contract::contract::delivery::DeliveryEffect::NoEffect, outcome, preserved: vec![], failure: None };
1213
+ let db = rusqlite::Connection::open(self.binding.transport_root.join("contract.db")).unwrap();
1214
+ db.execute("INSERT INTO contract_seats VALUES(?1,?2)", rusqlite::params![self.identity.seat.as_str(), serde_json::to_string(&target).unwrap()]).unwrap();
1215
+ db.execute("INSERT INTO contract_generations VALUES(?1,?2)", rusqlite::params![self.identity.seat.as_str(), self.identity.generation.0]).unwrap();
1216
+ 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();
1217
+ db.execute("INSERT INTO contract_operations VALUES(?1,?2)", rusqlite::params![operation.id.as_str(), serde_json::to_string(&operation).unwrap()]).unwrap();
1218
+ if matches!(outcome, Outcome::Running | Outcome::NeedsRecovery) {
1219
+ db.execute("INSERT INTO contract_leases VALUES(?1,?2)", rusqlite::params![self.identity.seat.as_str(), operation.id.as_str()]).unwrap();
1220
+ }
1221
+ std::fs::write(root_for(&self.binding.workspace.path, &self.binding.scope).join("framework-binding.json"),
1222
+ serde_json::to_vec(&self.binding).unwrap()).unwrap();
1223
+ drop(db); drop(store);
1224
+ Backend::open_readonly(&self.binding.workspace.path, "test").unwrap()
1225
+ }
856
1226
  }
857
1227
  impl Drop for RoleFixture { fn drop(&mut self) { let _ = std::fs::remove_dir_all(&self.root); } }
858
1228
 
1229
+ fn assert_receipt_class(status: SeatStatus, phase: Phase, outcome: Outcome, pending: Option<&str>, expected: &str) {
1230
+ let mut fixture = RoleFixture::new();
1231
+ let backend = fixture.canonical(status, phase, outcome, pending);
1232
+ let before = serde_json::to_vec(&backend.store.seat(&fixture.identity.seat).unwrap()).unwrap();
1233
+ let receipt = backend.store.creation_receipt(&fixture.identity.seat, Some(&fixture.identity)).unwrap().unwrap();
1234
+ assert_eq!(receipt.phase, phase);
1235
+ assert_eq!(receipt.outcome, outcome);
1236
+ let result = existing_start(&backend, &fixture.identity.seat);
1237
+ assert_eq!(serde_json::to_vec(&backend.store.seat(&fixture.identity.seat).unwrap()).unwrap(), before);
1238
+ assert_eq!(backend.store.operation(&receipt.id).unwrap(), receipt);
1239
+ let classified = result.unwrap_or_else(|error| panic!("{expected} must not collapse to unconditional Conflict: {error}"));
1240
+ let matches = match classified {
1241
+ Some(ExistingStart::Committed(record)) => expected == "committed" && record.id == receipt.id,
1242
+ Some(ExistingStart::FinishReceipt(record)) => expected == "finish" && record.id == receipt.id,
1243
+ Some(ExistingStart::Pending(record)) => expected == "pending" && record.id == receipt.id,
1244
+ Some(ExistingStart::Resume(record)) => expected == "resume" && record.identity == fixture.identity,
1245
+ Some(ExistingStart::Blocked(record)) => expected == "blocked" && record.id == receipt.id,
1246
+ None => false,
1247
+ };
1248
+ assert!(matches, "wrong receipt class for {expected}");
1249
+ }
1250
+
1251
+ #[test]
1252
+ fn startup_receipt_red_committed_is_reused_not_conflicted() {
1253
+ assert_receipt_class(SeatStatus::Ready, Phase::F5Receipt, Outcome::Committed, None, "committed");
1254
+ }
1255
+ #[test]
1256
+ fn startup_receipt_red_f4_is_receipt_completion_not_fresh() {
1257
+ assert_receipt_class(SeatStatus::Starting, Phase::F4Commit, Outcome::Running, None, "finish");
1258
+ }
1259
+ #[test]
1260
+ fn startup_receipt_red_inflight_is_pending_not_replayed() {
1261
+ assert_receipt_class(SeatStatus::Starting, Phase::F3Spawn, Outcome::Running, Some("spawn"), "pending");
1262
+ }
1263
+ #[test]
1264
+ fn startup_receipt_red_stopped_is_resume_not_fresh() {
1265
+ assert_receipt_class(SeatStatus::Stopped, Phase::F5Receipt, Outcome::Committed, None, "resume");
1266
+ }
1267
+ #[test]
1268
+ fn startup_receipt_red_uncertain_is_blocked_with_original_receipt() {
1269
+ assert_receipt_class(SeatStatus::Starting, Phase::F3Spawn, Outcome::NeedsRecovery, Some("spawn"), "blocked");
1270
+ }
1271
+
1272
+ #[test]
1273
+ fn startup_receipt_projection_repair_refuses_foreign_or_guessed_identity() {
1274
+ let mut fixture = RoleFixture::new();
1275
+ fixture.binding.candidate = std::env::current_exe().unwrap().canonicalize().unwrap();
1276
+ fixture.binding.candidate_sha256 = fingerprint_file(&fixture.binding.candidate, 1024 * 1024 * 1024, Duration::from_secs(10)).unwrap();
1277
+ let backend = fixture.canonical(SeatStatus::Starting, Phase::F4Commit, Outcome::Running, None);
1278
+ let original = backend.store.creation_receipt(&fixture.identity.seat, Some(&fixture.identity)).unwrap().unwrap();
1279
+ let seed = serde_json::json!({"provider":"cursor","status":"unknown"});
1280
+ assert!(start_needs_reconciliation(&fixture.root, "test", &fixture.identity.seat, &seed).unwrap());
1281
+ let exact = serde_json::json!({"provider":"cursor","status":"unknown","contract_scope":fixture.identity.scope,
1282
+ "contract_instance":fixture.identity.instance,"generation":fixture.identity.generation});
1283
+ assert!(start_needs_reconciliation(&fixture.root, "test", &fixture.identity.seat, &exact).unwrap());
1284
+ for (key, value) in [("provider", serde_json::json!("grok_build")), ("contract_scope", serde_json::json!("foreign")),
1285
+ ("contract_instance", serde_json::json!("another")), ("generation", serde_json::json!(2))] {
1286
+ let mut forged = exact.clone(); forged[key] = value;
1287
+ assert!(start_needs_reconciliation(&fixture.root, "test", &fixture.identity.seat, &forged).is_err(), "{key}");
1288
+ }
1289
+ assert_eq!(backend.store.operation(&original.id).unwrap(), original);
1290
+ assert!(preflight_start_role(&fixture.root, "test", &fixture.role).is_err(), "classification is not Native admission");
1291
+ }
1292
+
1293
+ #[test]
1294
+ fn startup_receipt_fixture_cannot_authorize_reuse_or_native_input() {
1295
+ let mut fixture = RoleFixture::new();
1296
+ let backend = fixture.canonical(SeatStatus::Ready, Phase::F5Receipt, Outcome::Committed, None);
1297
+ let record = backend.store.creation_receipt(&fixture.identity.seat, Some(&fixture.identity)).unwrap().unwrap();
1298
+ assert!(validate_existing(&backend, &fixture.role, &record).is_err());
1299
+ assert_eq!(backend.store.operation(&record.id).unwrap(), record);
1300
+ }
1301
+
1302
+ #[test]
1303
+ fn startup_receipt_unfinished_parent_wins_over_old_committed_generation() {
1304
+ let mut fixture = RoleFixture::new();
1305
+ let backend = fixture.canonical(SeatStatus::Ready, Phase::F5Receipt, Outcome::Committed, None);
1306
+ let mut interrupted = backend.store.creation_receipt(&fixture.identity.seat, Some(&fixture.identity)).unwrap().unwrap();
1307
+ interrupted.parent = Some(interrupted.target.clone());
1308
+ interrupted.id = OperationId::new("uncertain-restart").unwrap();
1309
+ interrupted.kind = TransactionKind::Restart;
1310
+ interrupted.target.identity.instance = InstanceId::new("second").unwrap();
1311
+ interrupted.target.identity.generation = Generation(2);
1312
+ interrupted.phase = Phase::F3Spawn;
1313
+ interrupted.pending = Some("spawn".into());
1314
+ interrupted.outcome = Outcome::NeedsRecovery;
1315
+ let db = rusqlite::Connection::open(fixture.binding.transport_root.join("contract.db")).unwrap();
1316
+ db.execute("INSERT INTO contract_operations VALUES(?1,?2)", rusqlite::params![interrupted.id.as_str(), serde_json::to_string(&interrupted).unwrap()]).unwrap();
1317
+ assert!(matches!(existing_start(&backend, &fixture.identity.seat).unwrap(),
1318
+ Some(ExistingStart::Blocked(record)) if record == interrupted));
1319
+ assert_eq!(backend.store.seat(&fixture.identity.seat).unwrap().unwrap().identity, fixture.identity);
1320
+ }
1321
+
1322
+ #[test]
1323
+ fn startup_receipt_missing_committed_seat_refuses_but_compensated_allows_fresh_proposal() {
1324
+ for outcome in [Outcome::Committed, Outcome::Compensated] {
1325
+ let mut fixture = RoleFixture::new();
1326
+ let backend = fixture.canonical(SeatStatus::Stopped, Phase::F5Receipt, outcome, None);
1327
+ let db = rusqlite::Connection::open(fixture.binding.transport_root.join("contract.db")).unwrap();
1328
+ db.execute("DELETE FROM contract_seats", []).unwrap();
1329
+ let result = existing_start(&backend, &fixture.identity.seat);
1330
+ if outcome == Outcome::Committed { assert!(result.is_err()); }
1331
+ else { assert!(result.unwrap().is_none()); }
1332
+ assert_eq!(backend.store.propose_identity(&fixture.identity.seat).unwrap().generation, Generation(2));
1333
+ }
1334
+ }
1335
+
1336
+ #[test]
1337
+ fn startup_receipt_lookup_refuses_cross_scope_and_generation_fallback() {
1338
+ let mut fixture = RoleFixture::new();
1339
+ let backend = fixture.canonical(SeatStatus::Ready, Phase::F5Receipt, Outcome::Committed, None);
1340
+ let mut wrong = fixture.identity.clone(); wrong.generation = Generation(2);
1341
+ assert!(backend.store.creation_receipt(&fixture.identity.seat, Some(&wrong)).is_err());
1342
+ wrong = fixture.identity.clone(); wrong.scope = ScopeId::new("foreign").unwrap();
1343
+ assert!(backend.store.creation_receipt(&fixture.identity.seat, Some(&wrong)).is_err());
1344
+ assert!(backend.store.creation_receipt(&SeatId::new("absent").unwrap(), None).unwrap().is_none());
1345
+ }
1346
+
859
1347
  #[test]
860
1348
  fn restart_skips_stopped_mirror_and_stopped_native_store_before_resume_discovery() {
861
1349
  for provider in ["cursor", "grok_build"] {