Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

fix: prevent dynamic imports in live inspector cleanup

Adam Eivyf8dec1d16ce7
diff --git a/AGENTS.md b/AGENTS.md
index 23c1cd9574..c43c5e44e6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -234,6 +234,7 @@ This policy governs code comments, not user-facing guides or product copy.
## Code Conventions
+- **Live Node inspector cleanup** — do not schedule dynamic `import()` from an inspector-evaluated callback; it can reject with `ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING` outside the evaluation's promise. Use `process.getBuiltinModule('node:inspector')` for builtin access, inspect the protocol response before disconnecting, and verify the listener closed. See [safe inspector cleanup](docs/TROUBLESHOOTING.md#dynamic-import-callback-missing-after-profiling).
- **Error handling** — in Express request handlers, let errors bubble to centralized middleware instead of wrapping each handler in try/catch. Client code uses the shared error/save boundaries in `client/src/AGENTS.md`. **Process-boundary exception:** PTY/child-process/`setTimeout`/`setInterval` callbacks and any code running *outside* the Express request lifecycle, where an uncaught throw crashes the Node process. At those boundaries, wrap hook invocation in try/catch and log via the emoji-prefixed `console.error` style. Async event handlers that mutate shared module-level state (e.g. the TUI spawner's `handleData`) must also be serialized — chain them onto a per-session/per-actor `Promise.resolve()` queue rather than firing concurrently.
- **Functional programming** — no classes; use hooks in React.
- **Zod validation** — all route inputs validated via `lib/validation.js`.
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 25c06650a0..bf2f9fd47c 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -92,6 +92,44 @@ npm run pm2:restart
**Never copy `data.reference/` over `data/` by hand** (`cp -r data.reference/* data/`). The seed tree includes `settings.json`, `apps.json`, `providers.json`, `cos/state.json`, `TASKS.md`, Brain settings (`brain/meta.json`), the digital-twin documents and every prompt template. Copying it overwrites your copies of all of them with shipped defaults, and nothing reports what was lost.
+### Dynamic import callback missing after profiling
+
+**Symptom**: `ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING`, followed by an unhandled
+rejection whose original stack names `Timeout._onTimeout (<anonymous>:…)`, near
+`Debugger attached` / `Debugger ending` messages.
+
+Inspect the original stderr stack, not only the normalized `ServerError` stack.
+A profiler cleanup expression injected through Node's inspector can cause this:
+
+```js
+setTimeout(() => import('node:inspector').then(m => m.close()), 500);
+```
+
+The timer's dynamic import can run without an import callback in that evaluation
+context. Its rejected promise escapes the timer, and the inspector stays open.
+An acknowledged `Runtime.evaluate` request only proves the timer was scheduled;
+even `awaitPromise: true` cannot await a promise that the timer callback later
+creates. This pattern alone does not indicate a broken application import.
+See Node's [VM import callback documentation](https://nodejs.org/api/vm.html#when-the-importmoduledynamically-option-is-not-specified-or-undefined).
+
+**Solution**: after stopping your profiling session, use synchronous builtin
+access in the inspector's `Runtime.evaluate` expression:
+
+```js
+setTimeout(() => process.getBuiltinModule('node:inspector').close(), 500);
+'cleanup scheduled';
+```
+
+`process.getBuiltinModule` is available on PortOS's supported Node versions and
+does not depend on the evaluation context's ESM loader. Check the response with
+the matching protocol request ID for both a protocol `error` and
+`result.exceptionDetails` before disconnecting your debugger socket. After the
+delay, verify that the same loopback inspector listener is closed and the server
+remains healthy with no new rejection. Closing the debugger socket alone leaves
+the inspector listener running. Close only the inspector session you own; do not
+restart the live server or change application VM sandbox loaders to repair a
+profiling expression.
+
## Connection Issues
### Cannot Access from Other Devices