Skip to content

Commit f4e2628

Browse files
committed
fix(sandbox): remove terminal drain timeouts
Signed-off-by: Drew Newberry <[email protected]>
1 parent 595c432 commit f4e2628

11 files changed

Lines changed: 255 additions & 200 deletions

File tree

‎.agents/skills/openshell-cli/SKILL.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -259,6 +259,10 @@ Key flags:
259259
- `--forward [BIND_ADDRESS:]PORT`: Forward a local port and keep the sandbox alive
260260
- `--editor vscode|cursor`: Open a remote editor after creation and keep the sandbox alive
261261

262+
`--detach` adds no attachment grace period. When the canonical process exits,
263+
its terminal phase is reported immediately. A foreground create instead keeps
264+
ephemeral cleanup deferred until its active SSH connection closes naturally.
265+
262266
Do not combine `--upload` with a trailing main command. Uploads currently finish
263267
after the canonical process starts; create a scratch sandbox and use
264268
`sandbox exec`, or build the files into the image.

‎.agents/skills/openshell-cli/cli-reference.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -224,6 +224,10 @@ previous runtime generation.
224224
| `--gpu [COUNT]` | Request the driver's default GPU selection or a specific count |
225225
| `--cpu <QUANTITY>` | CPU limit (for example: `500m`, `1`, `2.5`) |
226226
| `--memory <QUANTITY>` | Memory limit (for example: `512Mi`, `4Gi`, `8G`) |
227+
228+
`--detach` adds no attachment grace period: the sandbox reports the canonical
229+
process result immediately when it exits. Foreground creation defers ephemeral
230+
cleanup only while its active SSH connection drains and closes naturally.
227231
| `--driver-config-json <JSON>` | Experimental driver-keyed configuration object |
228232
| `--provider <NAME>` | Provider to attach (repeatable) |
229233
| `--policy <PATH>` | Custom policy YAML; overrides the built-in default and `OPENSHELL_SANDBOX_POLICY` |

‎architecture/gateway.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,11 @@ The live supervisor session is the readiness authority for its main-process
2929
instance. The supervisor reports its normalized result through the
3030
sandbox-authenticated `ReportMainProcessExit` RPC, and the gateway rejects
3131
results from stale instance IDs. The process supervisor keeps the main SSH
32-
session alive until an attached foreground client drains output to the terminal
33-
event or a bounded detached timeout expires. It durably reports the result,
34-
sends the SSH exit status, and only then releases deferred ephemeral cleanup.
32+
session alive only when a foreground attachment is active at process exit. It
33+
durably reports the result immediately, sends the SSH exit status, and waits for
34+
the peer's SSH channel close before releasing deferred ephemeral cleanup.
35+
Detached commands have no attachment to drain, so they report their result and
36+
exit immediately without a grace period.
3537

3638
## Protocol and Auth
3739

‎architecture/sandbox.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -481,9 +481,11 @@ engine with a gateway policy revision.
481481
re-evaluate.
482482
- If the supervisor relay drops, the sandbox can keep running, but connect and
483483
exec operations fail until the supervisor registers again.
484-
- If the canonical main process exits, the supervisor drains its retained main
485-
output, durably reports the normalized result, sends the SSH exit status, and
486-
releases deferred ephemeral cleanup before shutdown. Exit code 0 records
484+
- If the canonical main process exits, the supervisor durably reports the
485+
normalized result immediately. When a foreground main attachment is active,
486+
it sends the retained output and SSH exit status, waits for the peer's channel
487+
close, and then releases deferred ephemeral cleanup. With no active
488+
attachment, it exits without a grace period. Exit code 0 records
487489
`Completed/MainProcessCompleted`; nonzero and signal-normalized exits record
488490
`Error/MainProcessFailed`. Infrastructure failures also use `Error`, with a
489491
distinct condition reason and no fabricated canonical-process result. Runtime

‎crates/openshell-supervisor-process/src/main_session.rs‎

Lines changed: 94 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -54,12 +54,8 @@ struct OutputLogState {
5454
struct OutputLog {
5555
state: Mutex<OutputLogState>,
5656
version: watch::Sender<u64>,
57-
terminal_delivery_ready: std::sync::atomic::AtomicBool,
58-
terminal_delivery_ready_notify: Notify,
5957
terminal_reported: std::sync::atomic::AtomicBool,
6058
terminal_reported_notify: Notify,
61-
terminal_delivery_complete: std::sync::atomic::AtomicBool,
62-
terminal_delivery_complete_notify: Notify,
6359
}
6460

6561
impl OutputLog {
@@ -72,12 +68,8 @@ impl OutputLog {
7268
next_sequence: 0,
7369
}),
7470
version,
75-
terminal_delivery_ready: std::sync::atomic::AtomicBool::new(false),
76-
terminal_delivery_ready_notify: Notify::new(),
7771
terminal_reported: std::sync::atomic::AtomicBool::new(false),
7872
terminal_reported_notify: Notify::new(),
79-
terminal_delivery_complete: std::sync::atomic::AtomicBool::new(false),
80-
terminal_delivery_complete_notify: Notify::new(),
8173
})
8274
}
8375

@@ -118,6 +110,12 @@ impl OutputLog {
118110
}
119111
}
120112

113+
#[derive(Debug)]
114+
struct TerminalAttachmentState {
115+
accepting: bool,
116+
active: usize,
117+
}
118+
121119
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
122120
pub struct MainOutputLagged {
123121
pub skipped: u64,
@@ -183,6 +181,8 @@ pub struct MainSession {
183181
readers_remaining: AtomicUsize,
184182
readers_done: Notify,
185183
finished: std::sync::atomic::AtomicBool,
184+
terminal_attachments: Mutex<TerminalAttachmentState>,
185+
terminal_attachments_done: Notify,
186186
}
187187

188188
impl MainSession {
@@ -200,6 +200,11 @@ impl MainSession {
200200
readers_remaining: AtomicUsize::new(0),
201201
readers_done: Notify::new(),
202202
finished: std::sync::atomic::AtomicBool::new(false),
203+
terminal_attachments: Mutex::new(TerminalAttachmentState {
204+
accepting: true,
205+
active: 0,
206+
}),
207+
terminal_attachments_done: Notify::new(),
203208
})
204209
}
205210

@@ -245,6 +250,11 @@ impl MainSession {
245250
readers_remaining: AtomicUsize::new(if terminal { 1 } else { 2 }),
246251
readers_done: Notify::new(),
247252
finished: std::sync::atomic::AtomicBool::new(false),
253+
terminal_attachments: Mutex::new(TerminalAttachmentState {
254+
accepting: true,
255+
active: 0,
256+
}),
257+
terminal_attachments_done: Notify::new(),
248258
});
249259
Self::start_io(&session, io, input_rx);
250260
session
@@ -355,36 +365,31 @@ impl MainSession {
355365
}
356366
}
357367

358-
pub async fn finish(&self, exit_code: i32) {
368+
/// Publish the terminal event and stop accepting new main attachments.
369+
///
370+
/// Returns whether a foreground attachment was active at process exit.
371+
pub async fn finish(&self, exit_code: i32) -> bool {
359372
let notified = self.readers_done.notified();
360373
if self.readers_remaining.load(Ordering::Acquire) != 0 {
361-
let _ = tokio::time::timeout(std::time::Duration::from_secs(2), notified).await;
374+
notified.await;
362375
}
376+
let attached = {
377+
let mut state = self
378+
.terminal_attachments
379+
.lock()
380+
.expect("terminal attachment lock poisoned");
381+
state.accepting = false;
382+
state.active != 0
383+
};
363384
self.finished.store(true, Ordering::Release);
364385
self.publish(MainOutput::Exit(exit_code));
386+
attached
365387
}
366388

367389
pub fn subscribe(&self) -> MainOutputCursor {
368390
self.output.subscribe()
369391
}
370392

371-
/// Wait until an attached main-session consumer drains output through the
372-
/// terminal event and is ready for the durable lifecycle report.
373-
pub async fn wait_for_terminal_delivery_ready(&self) {
374-
let notified = self.output.terminal_delivery_ready_notify.notified();
375-
if self.output.terminal_delivery_ready.load(Ordering::Acquire) {
376-
return;
377-
}
378-
notified.await;
379-
}
380-
381-
pub fn mark_terminal_delivery_ready(&self) {
382-
self.output
383-
.terminal_delivery_ready
384-
.store(true, Ordering::Release);
385-
self.output.terminal_delivery_ready_notify.notify_waiters();
386-
}
387-
388393
/// Wait until the gateway durably acknowledges the main-process result.
389394
pub async fn wait_for_terminal_reported(&self) {
390395
let notified = self.output.terminal_reported_notify.notified();
@@ -401,27 +406,56 @@ impl MainSession {
401406
self.output.terminal_reported_notify.notify_waiters();
402407
}
403408

404-
/// Wait until the SSH attachment has finished attempting to send its exit
405-
/// status after the durable lifecycle report.
406-
pub async fn wait_for_terminal_delivery_complete(&self) {
407-
let notified = self.output.terminal_delivery_complete_notify.notified();
408-
if self
409-
.output
410-
.terminal_delivery_complete
411-
.load(Ordering::Acquire)
412-
{
413-
return;
409+
/// Register a foreground main attachment while the process is live.
410+
pub fn begin_terminal_attachment(&self) -> Result<(), &'static str> {
411+
let mut state = self
412+
.terminal_attachments
413+
.lock()
414+
.expect("terminal attachment lock poisoned");
415+
if !state.accepting {
416+
return Err("canonical main process already finished");
417+
}
418+
state.active = state
419+
.active
420+
.checked_add(1)
421+
.expect("terminal attachment count exhausted");
422+
Ok(())
423+
}
424+
425+
/// Release a foreground main attachment after its SSH channel closes.
426+
pub fn end_terminal_attachment(&self) {
427+
let completed = {
428+
let mut state = self
429+
.terminal_attachments
430+
.lock()
431+
.expect("terminal attachment lock poisoned");
432+
debug_assert!(state.active != 0, "terminal attachment count underflow");
433+
if state.active == 0 {
434+
return;
435+
}
436+
state.active -= 1;
437+
state.active == 0
438+
};
439+
if completed {
440+
self.terminal_attachments_done.notify_waiters();
414441
}
415-
notified.await;
416442
}
417443

418-
pub fn mark_terminal_delivery_complete(&self) {
419-
self.output
420-
.terminal_delivery_complete
421-
.store(true, Ordering::Release);
422-
self.output
423-
.terminal_delivery_complete_notify
424-
.notify_waiters();
444+
/// Wait for all attachments that existed at process exit to close.
445+
pub async fn wait_for_terminal_attachments(&self) {
446+
loop {
447+
let notified = self.terminal_attachments_done.notified();
448+
if self
449+
.terminal_attachments
450+
.lock()
451+
.expect("terminal attachment lock poisoned")
452+
.active
453+
== 0
454+
{
455+
return;
456+
}
457+
notified.await;
458+
}
425459
}
426460

427461
pub fn acquire_input(&self) -> Result<(u64, tokio::sync::mpsc::Sender<Vec<u8>>), &'static str> {
@@ -517,34 +551,16 @@ mod tests {
517551
}
518552

519553
#[tokio::test]
520-
async fn terminal_delivery_readiness_requires_an_attachment() {
554+
async fn finish_without_attachment_does_not_defer_shutdown() {
521555
let session = MainSession::inert();
522-
session.finish(0).await;
556+
assert!(!session.finish(0).await);
523557
assert!(session.finished());
524-
525-
assert!(
526-
tokio::time::timeout(
527-
std::time::Duration::from_millis(10),
528-
session.wait_for_terminal_delivery_ready(),
529-
)
530-
.await
531-
.is_err(),
532-
"publishing Exit alone must not count as delivery"
533-
);
534-
535-
session.mark_terminal_delivery_ready();
536-
tokio::time::timeout(
537-
std::time::Duration::from_secs(1),
538-
session.wait_for_terminal_delivery_ready(),
539-
)
540-
.await
541-
.expect("delivery readiness should wake waiter");
558+
assert!(session.begin_terminal_attachment().is_err());
542559
}
543560

544561
#[tokio::test]
545562
async fn terminal_report_acknowledgement_is_independent_from_delivery() {
546563
let session = MainSession::inert();
547-
session.mark_terminal_delivery_ready();
548564

549565
assert!(
550566
tokio::time::timeout(
@@ -566,34 +582,36 @@ mod tests {
566582
}
567583

568584
#[tokio::test]
569-
async fn terminal_delivery_completion_is_distinct_from_readiness_and_reporting() {
585+
async fn finish_waits_for_an_active_attachment_to_close_naturally() {
570586
let session = MainSession::inert();
571-
session.mark_terminal_delivery_ready();
572-
session.mark_terminal_reported();
587+
session
588+
.begin_terminal_attachment()
589+
.expect("begin terminal attachment");
590+
assert!(session.finish(0).await);
573591

574592
assert!(
575593
tokio::time::timeout(
576594
std::time::Duration::from_millis(10),
577-
session.wait_for_terminal_delivery_complete(),
595+
session.wait_for_terminal_attachments(),
578596
)
579597
.await
580598
.is_err(),
581-
"gateway persistence must not imply SSH exit delivery"
599+
"an active attachment must keep terminal delivery open"
582600
);
583601

584-
session.mark_terminal_delivery_complete();
602+
session.end_terminal_attachment();
585603
tokio::time::timeout(
586604
std::time::Duration::from_secs(1),
587-
session.wait_for_terminal_delivery_complete(),
605+
session.wait_for_terminal_attachments(),
588606
)
589607
.await
590-
.expect("completed SSH delivery should wake waiter");
608+
.expect("closing the attachment should wake the waiter");
591609
}
592610

593611
#[tokio::test]
594-
async fn exit_is_replayed_once_to_late_subscribers() {
612+
async fn exit_is_retained_in_the_output_log() {
595613
let session = MainSession::inert();
596-
session.finish(0).await;
614+
let _ = session.finish(0).await;
597615

598616
let mut output = session.subscribe();
599617
assert!(matches!(

0 commit comments

Comments
 (0)