From b35e458cdc738c0a538e7ab7f787ffb6c0647419 Mon Sep 17 00:00:00 2001
From: riddhi2910 <riprajap@adobe.com>
Date: Thu, 4 Jun 2026 12:10:37 -0700
Subject: [PATCH] Add directive to use .detached for commands that time out

---
 src/commands/runtime/sandbox/run.js       |  4 +++-
 test/commands/runtime/sandbox/run.test.js | 10 ++++++++++
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/src/commands/runtime/sandbox/run.js b/src/commands/runtime/sandbox/run.js
index 1e5984d4..445f7110 100644
--- a/src/commands/runtime/sandbox/run.js
+++ b/src/commands/runtime/sandbox/run.js
@@ -179,7 +179,9 @@ class SandboxRun extends RuntimeBaseCommand {
           await this._handleExec(sandbox, trimmed)
         }
       } catch (err) {
-        this.log(`exec error: ${err.message || err}`)
+        const msg = err.message || String(err)
+        const hint = msg.includes('exceeded timeout') ? ' (use .detached for long-running commands)' : ''
+        this.log(`exec error: ${msg}${hint}`)
       }
     }
   }
diff --git a/test/commands/runtime/sandbox/run.test.js b/test/commands/runtime/sandbox/run.test.js
index f606f37d..57f5b6cb 100644
--- a/test/commands/runtime/sandbox/run.test.js
+++ b/test/commands/runtime/sandbox/run.test.js
@@ -504,6 +504,16 @@ describe('run', () => {
     expect(stdout.output).toMatch('exec error: plain string error')
   })
 
+  test('REPL: timeout errors include a hint to use .detached', async () => {
+    readline.createInterface.mockReturnValue(makeRl(['sleep 35', 'exit']))
+    sandbox.exec.mockRejectedValueOnce(new Error("Command 'sleep 35' exceeded timeout of 30000ms"))
+
+    command.argv = []
+    await command.run()
+
+    expect(stdout.output).toMatch('exec error: Command \'sleep 35\' exceeded timeout of 30000ms (use .detached for long-running commands)')
+  })
+
   test('REPL: detached command starts in background and streams output', async () => {
     const rl = makeRl(['.detached npm run dev', 'exit'])
     readline.createInterface.mockReturnValue(rl)