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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
fix: prevent dynamic imports in live inspector cleanup
Adam Eivyf8dec1d16ce7
diff --git a/AGENTS.md b/AGENTS.mdindex 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.mdindex 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