@phpsandbox/sdk 0.1.1 → 0.1.2

package/dist/terminal.js

@@ -2,30 +2,34 @@ import { nanoid } from 'nanoid';
 import { once } from './utils/promise.js';
 const TERMINAL_INPUT_FLUSH_DELAY_MS = 8;
 const terminalInputFlushPattern = /[\x00-\x1f\x7f]/;
-export default class Terminal {
+export default class Terminals {
     constructor(okra) {
         this.okra = okra;
     }
     list() {
         return this.okra.invoke('terminal.list');
     }
-    create(input) {
-        return this.okra.invoke('terminal.create', input);
-    }
-    onStarted(handler) {
-        return this.okra.listen('terminal.started', handler);
-    }
-    resize(id, size) {
-        return this.okra.invoke('terminal.resize', { id, width: size[0], height: size[1] });
-    }
-    onOutput(id, handler) {
-        return this.okra.listen(`terminal.output.${id}`, handler);
-    }
-    input(id, input) {
-        return Promise.resolve(this.okra.send('terminal.input', { id, input }));
-    }
-    listen(event, handler) {
-        return this.okra.listen(event, handler);
+    async create(options = {}) {
+        const id = options.id ?? nanoid();
+        const handle = this.processHandle(id, options.abortSignal);
+        const command = typeof options.command === 'string' && options.args?.length
+            ? [options.command, ...options.args]
+            : options.command;
+        const { abortSignal, args: _args, ...input } = options;
+        try {
+            const task = await this.okra.invoke('terminal.create', {
+                ...input,
+                id,
+                kind: options.kind ?? 'bash',
+                size: options.size ?? [80, 24],
+                command,
+            }, { abortSignal });
+            return { ...handle.process, ...task };
+        }
+        catch (error) {
+            handle.dispose();
+            throw error;
+        }
     }
     async attach(id, opts) {
         const handle = this.processHandle(id, opts?.abortSignal);
@@ -48,28 +52,6 @@ export default class Terminal {
             throw error;
         }
     }
-    async spawn(command, args, opts) {
-        const id = opts?.id || nanoid();
-        const handle = this.processHandle(id, opts?.abortSignal);
-        const { abortSignal, ...otherOpts } = opts ?? {};
-        try {
-            const result = await this.okra.invoke('terminal.spawn', {
-                command: [command, ...args],
-                opts: {
-                    id,
-                    ...otherOpts,
-                },
-            }, { abortSignal });
-            return {
-                ...handle.process,
-                ...result,
-            };
-        }
-        catch (error) {
-            handle.dispose();
-            throw error;
-        }
-    }
     processHandle(id, abortSignal) {
         const disposables = new Set();
         let abortHandler;
@@ -95,7 +77,7 @@ export default class Terminal {
             }
             const input = pendingInput;
             pendingInput = '';
-            void this.input(id, input);
+            void this.okra.send('terminal.input', { id, input });
         };
         const scheduleInputFlush = () => {
             if (inputFlushTimer) {
@@ -103,7 +85,8 @@ export default class Terminal {
             }
             inputFlushTimer = setTimeout(flushInput, TERMINAL_INPUT_FLUSH_DELAY_MS);
         };
-        const queueInput = (chunk) => {
+        const queueInput = (value) => {
+            const chunk = typeof value === 'string' ? value : new TextDecoder().decode(value);
             pendingInput += chunk;
             if (terminalInputFlushPattern.test(chunk)) {
                 flushInput();
@@ -124,7 +107,7 @@ export default class Terminal {
         const output = new ReadableStream({
             start: (_controller) => {
                 controller = _controller;
-                disposables.add(this.listen(`terminal.output.${id}`, (data) => {
+                disposables.add(this.okra.listen(`terminal.output.${id}`, (data) => {
                     controller?.enqueue(data.output);
                 }));
             },
@@ -134,7 +117,7 @@ export default class Terminal {
             },
         });
         const completion = new Promise((resolve) => {
-            disposables.add(this.listen(`terminal.close.${id}`, (data) => {
+            disposables.add(this.okra.listen(`terminal.close.${id}`, (data) => {
                 if (controller) {
                     try {
                         controller.close();

package/docs/api-summary.md

@@ -32,36 +32,46 @@ Connection lifecycle methods, streaming actions, and event subscriptions require
 
 - Lifecycle: `ready()`, `connected()`, `whenConnected()`, `reconnect()`, `dispose()`
 - Notebook actions: `fork(input?)`, `destroy()`, `stop()`, `restart()`, `ping()`, `update()`
-- Processes: `run(command, args?, options?)` returning native `stdin`, `stdout`, `stderr`, ordered `output`, `exit`, and `kill()`
+- Processes: `exec(command, args?, options?)`, or `run(command, args?, options?)` returning native `stdin`, `stdout`, `stderr`, ordered `output`, `wait()`, and `kill()`
 - Events: `listen(event, handler)`, `onDidConnect(handler)`, `onDidDisconnect(handler)`, `onDidInitialize(handler)`
 - Raw call: `invoke(action, data?, options?)`
 
 ## Services
 
-### Filesystem (`notebook.file`)
+### Filesystem (`notebook.files`)
 
-- File data: `info()`, `readFile()`, `write()`, `writeFile()`, `tail()`, `stat()`, `exists()`
-- File management: `move()`, `rename()`, `copy()`, `remove()`, `delete()`
-- Directory: `mkdir()`, `createDirectory()`, `readDirectory()`, `tree()`
+- File data: `read()`, `readText()`, `readStream()`, `write()`, `tail()`, `stat()`, `exists()`
+- File management: `move()`, `copy()`, `remove()`
+- Directory: `createDirectory()`, `list()`, `tree()`
 - Search: `find()`, `search()`
-- Streaming/monitoring: `watch()`, `download()`
+- Streaming/monitoring: `readStream()`, `watch()`, `download()`
+- `tail()` is an eager last-lines snapshot; it does not follow future appends.
 
-### Terminal (`notebook.terminal`)
+### Terminal (`notebook.terminals`)
 
-- Terminal control: `list()`, `create()`, `attach()`, `resize()`, `input()`
-- Process API: `spawn(command, args, opts?)`, `attach(id, opts?)`
-- Events: `listen()`, `onStarted()`, `onOutput(id, handler)`
+- `list()` returns terminal metadata
+- `create(options?)` returns a terminal handle
+- `attach(id, options?)` returns a terminal handle
+- Handles expose `input`, `output`, `wait()`, `resize()`, and `kill()`
 
 ### Container (`notebook.container`)
 
 - Lifecycle: `start()`, `stop()`, `state()`
-- Ports: `openedPorts()`, `onPort(handler)`
 - Runtime config: `setPhp(version)`
-- Telemetry: `enableTelemetry(features)`, `stopTelemetry()`, `listen(event, handler)`
 
-### Shell (`notebook.shell`)
+### Runtime observability
 
-- `run(command, args?, options?)` returning the same process handle as `notebook.run()`
+- `notebook.logs.follow({ signal? })` returns `ReadableStream<RuntimeLogEntry>`
+- `notebook.ports.list()` returns the current preview ports
+- `notebook.ports.watch({ signal? })` returns `ReadableStream<PortInfo[]>`
+- `notebook.metrics.current()` returns the current CPU, memory, and disk sample
+- `notebook.metrics.watch({ signal? })` returns `ReadableStream<ContainerStats>`
+
+### Processes
+
+- `notebook.run(command, args?, options?)` returns a streaming process handle
+- `notebook.exec(command, args?, options?)` returns a buffered `ProcessResult` for one-shot commands
+- Process handles expose `output`, `stdout`, `stderr`, `stdin`, `wait()`, and `kill()`
 
 ### Services (`notebook.services`)
 
@@ -70,13 +80,13 @@ Connection lifecycle methods, streaming actions, and event subscriptions require
 - `run(name, command?)`
 - `stop(name)`
 - `logs(name, { tail? })`
-- `logs(name, { follow: true, tail?, id? })` returning `{ id, output, stop() }`
-- Events: `listen()`, `onLog(id, handler)`
+- `logs(name, { follow: true, tail?, id? })` returning `ReadableStream<string>`; cancel the stream to stop following
 
 ### Composer (`notebook.composer`)
 
-- Core: `invoke(command, args?, options?)`
-- Helpers: `install()`, `update()`, `require()`, `remove()`, `dumpAutoload()`, `packages()`, `stream(handler)`
+- Core: `run(command, args?, options?)`
+- Helpers: `install()`, `update()`, `require()`, `remove()`, `dumpAutoload()`, `packages()`
+- Command handles expose `output`, `stdout`, `stderr`, `wait()`, and `kill()`
 
 ### Git (`notebook.git`)
 
@@ -126,11 +136,6 @@ Connection lifecycle methods, streaming actions, and event subscriptions require
 - A publish run exposes `events()` as an `AsyncIterable`, `result()`, and `publication()`.
 - Built-in provider names are `cloudflare-containers`, `ssh-server`, and `laravel-cloud`. Provider maps support TypeScript declaration merging.
 
-### Log (`notebook.log`)
-
-- `stream(handler)`
-- `listen(event, handler)`
-
 ## Common Errors
 
 - `ApiError` for HTTP API failures

package/docs/cdn-usage.md

@@ -18,7 +18,7 @@ Do not hardcode long-lived private API tokens in public frontend code. Use short
   const notebook = await client.notebook.get('your-notebook-id');
   await notebook.ready();
 
-  const result = await notebook.run('php -v', { tty: false }).exit;
+  const result = await notebook.exec('php -v', { tty: false });
   result.throw();
   console.log(result.output);
 </script>
@@ -45,7 +45,7 @@ Do not hardcode long-lived private API tokens in public frontend code. Use short
 
   client.notebook.get('your-notebook-id').then(async (notebook) => {
     await notebook.ready();
-    const result = await notebook.run('php -v', { tty: false }).exit;
+    const result = await notebook.exec('php -v', { tty: false });
     console.log(result.output);
     notebook.dispose();
   });

package/docs/getting-started.md

@@ -48,18 +48,18 @@ API notebook creates and forks are ephemeral by default. Use `persistent: true`
 ## 3. Write and Read Files
 
 ```ts
-await notebook.file.write('hello.php', '<?php echo "Hello";');
+await notebook.files.write('hello.php', '<?php echo "Hello";');
 
-const data = await notebook.file.readFile('hello.php');
+const data = await notebook.files.read('hello.php');
 const text = new TextDecoder().decode(data);
 
 console.log(text);
 ```
 
-If you need binary-safe writes, use `writeFile`:
+The same `write()` method accepts text, bytes, readable streams, and async iterables:
 
 ```ts
-await notebook.file.writeFile('binary.dat', new Uint8Array([1, 2, 3]), {
+await notebook.files.write('binary.dat', new Uint8Array([1, 2, 3]), {
   create: true,
   overwrite: true,
   unlock: false,
@@ -72,7 +72,7 @@ await notebook.file.writeFile('binary.dat', new Uint8Array([1, 2, 3]), {
 ### Terminal (stream output)
 
 ```ts
-const task = await notebook.terminal.spawn('php', ['hello.php']);
+const task = await notebook.terminals.create({ command: 'php', args: ['hello.php'] });
 const reader = task.output.getReader();
 
 try {
@@ -85,14 +85,14 @@ try {
   reader.releaseLock();
 }
 
-const exitCode = await task.exit;
+const exitCode = await task.wait();
 console.log(`\nExit code: ${exitCode}`);
 ```
 
 ### Shell (single command result)
 
 ```ts
-const result = await notebook.run('php -v', { tty: false }).exit;
+const result = await notebook.exec('php -v', { tty: false });
 result.throw();
 console.log(result.stdout);
 ```
@@ -100,14 +100,14 @@ console.log(result.stdout);
 ## 5. Search and Watch Files
 
 ```ts
-const matches = await notebook.file.find('*.php', {
+const matches = await notebook.files.find('*.php', {
   includes: ['app/**'],
   excludes: ['vendor/**'],
 });
 
 console.log(matches.map((m) => m.path));
 
-const watcher = notebook.file.watch(
+const watcher = notebook.files.watch(
   '/app',
   {
     recursive: true,
@@ -125,8 +125,8 @@ watcher.dispose();
 ## 6. Use Composer and Git
 
 ```ts
-await notebook.composer.install({ noInteraction: true });
-await notebook.composer.require({ packages: ['monolog/monolog'] });
+(await notebook.composer.install().wait()).throw();
+(await notebook.composer.require({ packages: ['monolog/monolog'] }).wait()).throw();
 
 await notebook.git.checkpoint('Jane Doe <jane@example.com>', 'Initial checkpoint');
 ```
@@ -142,8 +142,8 @@ notebook.dispose();
 ## Common Pitfalls
 
 - `get()` notebooks must call `await notebook.ready()` before tool calls.
-- `file.watch()` requires an `excludes` array.
-- Await `process.exit`, then call `result.throw()` to fail on non-zero exit codes.
+- `files.watch()` requires an `excludes` array.
+- Use `notebook.exec()` for one-shot commands; for streaming shell handles, await `process.wait()` and call `result.throw()` to fail on non-zero exit codes.
 
 ## Next Reading
 

package/examples/basic.ts

@@ -16,7 +16,7 @@ console.log('\n');
 
 console.log('====== Read routes/web.php in the notebook ======');
 const decoder = new TextDecoder();
-const content = await notebook.file.readFile('routes/web.php');
+const content = await notebook.files.read('routes/web.php');
 console.log(decoder.decode(content));
 
 // Always close the notebook when done to clean up the connection.

package/examples/git-merge-smoke.ts

@@ -54,10 +54,7 @@ async function main(): Promise<void> {
 
     await fork.ready();
     const editContent = buildEditContent(base.data.id, forkNotebookId, options);
-    const written = await fork.file.write(options.editPath, editContent);
-    if (!written) {
-      throw new Error(`fs.write returned false for ${options.editPath}.`);
-    }
+    await fork.files.write(options.editPath, editContent);
     console.log(`Edited fork file: ${options.editPath}`);
 
     const forkCheckpoint = await fork.git.checkpoint(options.author, `Smoke edit in fork ${forkNotebookId}`, options.ref, false);

package/examples/laravel-load-test.ts

@@ -389,11 +389,10 @@ async function runScenario(
   let notebook: NotebookInstance | null = null;
   let previewUrl: string | undefined;
   let logsCaptured = 0;
-  let logListener: Disposable | null = null;
+  let logReader: ReadableStreamDefaultReader<import('../src/log.js').RuntimeLogEntry> | null = null;
   let initTrace: InitTrace | undefined;
   let readyResult: NotebookInitSuccessResult | undefined;
   let initTraceDisposables: Disposable[] = [];
-  let telemetryEnabled = false;
   let redisRunning = false;
 
   const routeSlug = id.toLowerCase();
@@ -560,12 +559,19 @@ async function runScenario(
     }
 
     if (options.mode !== 'init') {
-      logListener = notebook.log.stream((line) => {
-        if (line.trim().length > 0) {
-          logsCaptured += 1;
-          ui.updateScenarioLogs(id, logsCaptured);
+      logReader = notebook.logs.follow().getReader();
+      void (async () => {
+        while (logReader) {
+          const entry = await logReader.read();
+          if (entry.done) {
+            return;
+          }
+          if (entry.value.message.trim().length > 0) {
+            logsCaptured += 1;
+            ui.updateScenarioLogs(id, logsCaptured);
+          }
         }
-      });
+      })().catch(() => {});
 
       await runCheckedStep('notebook.ping', () => notebook!.ping(), { continueOnError: false });
 
@@ -599,8 +605,8 @@ async function runScenario(
       });
 
       await runCheckedStep('container.state', async () => {
-        const [state, ports] = await Promise.all([notebook!.container.state(), notebook!.container.openedPorts()]);
-        const portInfo = assertPortInfoList(ports, 'container.openedPorts');
+        const [state, ports] = await Promise.all([notebook!.container.state(), notebook!.ports.list()]);
+        const portInfo = assertPortInfoList(ports, 'ports.list');
         return `${state.state} (${describePorts(portInfo)})`;
       });
 
@@ -609,11 +615,11 @@ async function runScenario(
           'container.restart',
           async () => {
             await notebook!.container.start();
-            const [state, ports] = await Promise.all([notebook!.container.state(), notebook!.container.openedPorts()]);
+            const [state, ports] = await Promise.all([notebook!.container.state(), notebook!.ports.list()]);
             if (state.state !== 'running') {
               throw new Error(`Expected running container after restart, got ${state.state}`);
             }
-            return `${state.state} (${describePorts(assertPortInfoList(ports, 'container.openedPorts after restart'))})`;
+            return `${state.state} (${describePorts(assertPortInfoList(ports, 'ports.list after restart'))})`;
           },
           { timeoutMs: options.stepTimeoutMs * 3, continueOnError: false }
         );
@@ -626,29 +632,20 @@ async function runScenario(
         async () =>
           retryWithBackoff(
             async () => {
-              const statsPromise = waitForNextEvent<ContainerStats>(
-                (handler) => notebook!.container.listen('container.stats', handler),
-                options.telemetryTimeoutMs,
-                'container.stats'
-              );
-              void statsPromise.catch(() => undefined);
-              const portsPromise = waitForNextEvent<PortInfo[]>(
-                (handler) => notebook!.container.listen('container.ports', handler),
-                options.telemetryTimeoutMs,
-                'container.ports'
-              );
-              void portsPromise.catch(() => undefined);
-
-              await notebook!.container.enableTelemetry(new Set(['stats', 'ports']));
-              telemetryEnabled = true;
-
-              return await firstFulfilled([
-                statsPromise.then(
-                  (stats) =>
-                    `cpu=${stats.cpu.usage}/${stats.cpu.limit} memory=${stats.memory.usage}/${stats.memory.limit}`
-                ),
-                portsPromise.then((ports) => describePorts(assertPortInfoList(ports, 'container.ports'))),
-              ]);
+              const statsReader = notebook!.metrics.watch().getReader();
+              const portsReader = notebook!.ports.watch().getReader();
+              try {
+                const statsPromise = withTimeout(statsReader.read(), options.telemetryTimeoutMs, 'metrics.watch')
+                  .then(({ value }) => {
+                    if (!value) throw new Error('metrics.watch ended before a sample was received.');
+                    return `cpu=${value.cpu.usage}/${value.cpu.limit} memory=${value.memory.usage}/${value.memory.limit}`;
+                  });
+                const portsPromise = withTimeout(portsReader.read(), options.telemetryTimeoutMs, 'ports.watch')
+                  .then(({ value }) => describePorts(assertPortInfoList(value ?? [], 'ports.watch')));
+                return await firstFulfilled([statsPromise, portsPromise]);
+              } finally {
+                await Promise.all([statsReader.cancel(), portsReader.cancel()]);
+              }
             },
             TELEMETRY_RETRY_DELAYS_MS,
             shouldRetryTelemetryError
@@ -660,7 +657,7 @@ async function runScenario(
         'filesystem.watch-and-write',
         async () => {
           const changeSeen = createDeferred<FileChange>();
-          const watch = await notebook!.file.watch(
+          const watch = await notebook!.files.watch(
             'routes',
             { recursive: true, excludes: ['vendor/**', 'node_modules/**'] },
             (change) => {
@@ -671,12 +668,9 @@ async function runScenario(
           );
 
           try {
-            const current = textDecoder.decode(await notebook!.file.readFile(routePath));
+            const current = textDecoder.decode(await notebook!.files.read(routePath));
             const next = appendRouteDefinition(current, id, routeUrlPath);
-            const written = await notebook!.file.write(routePath, next);
-            if (!written) {
-              throw new Error(`fs.write returned false for ${routePath}.`);
-            }
+            await notebook!.files.write(routePath, next);
 
             const change = await withTimeout(
               changeSeen.promise,
@@ -692,14 +686,13 @@ async function runScenario(
       );
 
       await runCheckedStep('filesystem.inspect', async () => {
-        const [raw, info, stat, directory, tree, found, tail] = await Promise.all([
-          notebook!.file.readFile(routePath),
-          notebook!.file.info(routePath),
-          notebook!.file.stat(routePath),
-          notebook!.file.readDirectory('routes'),
-          notebook!.file.tree('routes'),
-          notebook!.file.find(routeFileName, { includes: ['routes/**'], maxResults: 10 }),
-          notebook!.file.tail(routePath, 20),
+        const [raw, stat, directory, tree, found, tail] = await Promise.all([
+          notebook!.files.read(routePath),
+          notebook!.files.stat(routePath),
+          notebook!.files.list('routes'),
+          notebook!.files.tree('routes'),
+          notebook!.files.find(routeFileName, { includes: ['routes/**'], maxResults: 10 }),
+          notebook!.files.tail(routePath, { lines: 20 }),
         ]);
 
         const text = textDecoder.decode(raw);
@@ -707,7 +700,7 @@ async function runScenario(
           throw new Error(`Expected ${routeUrlPath} in ${routePath}.`);
         }
 
-        const [, matches] = await notebook!.file.search(
+        const [, matches] = await notebook!.files.search(
           { pattern: routeUrlPath },
           { includes: [routePath], excludes: [], maxResults: 10 }
         );
@@ -716,12 +709,12 @@ async function runScenario(
           throw new Error(`file.search() did not find ${routeUrlPath}.`);
         }
 
-        const exists = await notebook!.file.exists(routePath);
+        const exists = await notebook!.files.exists(routePath);
         if (!exists) {
           throw new Error(`${routePath} does not exist after write.`);
         }
 
-        return `size=${stat.size} info=${info.language} dir=${directory.length} tree-lines=${tree.split('\n').length} find=${found.length} tail=${tail.length}`;
+        return `size=${stat.size} dir=${directory.length} tree-lines=${tree.split('\n').length} find=${found.length} tail=${tail.length}`;
       });
 
       if (options.includePreview) {
@@ -732,7 +725,10 @@ async function runScenario(
 
       if (options.includeDownload) {
         await runCheckedStep('filesystem.download', async () => {
-          const archive = await notebook!.file.download(undefined, ['vendor/**', 'node_modules/**'], [routePath, 'composer.json']);
+          const archive = await notebook!.files.download({
+            exclude: ['vendor/**', 'node_modules/**'],
+            include: [routePath, 'composer.json'],
+          });
           if (archive.size === 0) {
             throw new Error('file.download() returned an empty blob.');
           }
@@ -784,12 +780,12 @@ async function runScenario(
       );
 
       await runCheckedStep(
-        'terminal.spawn',
+        'terminals.create',
         async () => {
-          const process = await notebook!.terminal.spawn(
-            'php',
-            ['artisan', 'route:list', `--path=${routeUrlPath}`]
-          );
+          const process = await notebook!.terminals.create({
+            command: 'php',
+            args: ['artisan', 'route:list', `--path=${routeUrlPath}`],
+          });
 
           try {
             const outputPromise = readStreamToString(process.output, options.streamTimeoutMs, options.maxStreamChars);
@@ -797,7 +793,7 @@ async function runScenario(
             const [output, exitCode] = await Promise.all([outputPromise, exitPromise]);
 
             if (exitCode !== 0) {
-              throw new Error(`terminal.spawn() exited with ${exitCode}: ${trimDetail(output)}`);
+              throw new Error(`terminals.create() exited with ${exitCode}: ${trimDetail(output)}`);
             }
 
             if (!output.includes(routeUrlPath)) {
@@ -820,7 +816,7 @@ async function runScenario(
           redisRunning = started.running || started.state === 'running' || started.state === 'starting';
 
           const stream = notebook!.services.logs('redis', { follow: true, tail: 25 });
-          const reader = stream.output.getReader();
+          const reader = stream.getReader();
 
           try {
             const [snapshot, chunk] = await Promise.all([
@@ -837,7 +833,6 @@ async function runScenario(
           } finally {
             await reader.cancel().catch(() => undefined);
             reader.releaseLock();
-            await stream.stop().catch(() => false);
             await notebook!.services.stop('redis').catch(() => started);
             redisRunning = false;
           }
@@ -847,25 +842,20 @@ async function runScenario(
 
       await runCheckedStep('composer.metadata', async () => {
         let composerLogChunks = 0;
-        const composerLogs = notebook!.composer.stream((line) => {
-          if (line.trim().length > 0) {
+        const dump = notebook!.composer.dumpAutoload();
+        for await (const chunk of dump.output) {
+          if (chunk.data.byteLength > 0) {
             composerLogChunks += 1;
           }
-        });
-
-        try {
-          const [packages, dump] = await Promise.all([notebook!.composer.packages(), notebook!.composer.dumpAutoload()]);
-          if (!dump.success) {
-            throw new Error(dump.message || 'composer.dumpAutoload() failed.');
-          }
-          if (packages.length === 0) {
-            throw new Error('composer.packages() returned no packages.');
-          }
+        }
 
-          return `packages=${packages.length} composer-log-events=${composerLogChunks}`;
-        } finally {
-          composerLogs.dispose();
+        (await dump.wait()).throw();
+        const packages = await notebook!.composer.packages();
+        if (packages.length === 0) {
+          throw new Error('composer.packages() returned no packages.');
         }
+
+        return `packages=${packages.length} composer-log-events=${composerLogChunks}`;
       }, { timeoutMs: Math.max(options.stepTimeoutMs * 2, 120_000) });
 
       await runCheckedStep('git.checkpoint', async () => {
@@ -960,11 +950,8 @@ async function runScenario(
         await notebook.services.stop('redis').catch(() => undefined);
       }
 
-      if (telemetryEnabled) {
-        await notebook.container.stopTelemetry().catch(() => undefined);
-      }
-
-      logListener?.dispose();
+      await logReader?.cancel().catch(() => undefined);
+      logReader = null;
       for (const disposable of initTraceDisposables) {
         disposable.dispose();
       }