@yemi33/minions 0.1.1958 → 0.1.1959

package/engine/keep-process-sweep.js

@@ -380,6 +380,54 @@ function buildKeepProcessesHint(opts) {
     '',
     'If you do NOT write the file, the engine will kill ALL of your descendant processes when you exit (today\'s default). Do not write the file unless you are intentionally leaving a process behind for the human or follow-up work.',
     '',
+    '### How to spawn long-running processes (CRITICAL on Windows)',
+    '',
+    'On Windows, child processes spawned with stdio inherited or piped from your agent process die SECONDS after you exit, because the next time they write to stdout the pipe is closed and they get EPIPE. Vite, bun run dev, file watchers, and HMR all log on every event, so they crash within seconds.',
+    '',
+    'Use this PowerShell pattern -- it gives the child its own log file descriptor (not a pipe) so it survives your exit:',
+    '',
+    '```powershell',
+    '# Adjust $log, $cmd, $args, $cwd for your target.',
+    '$log = "D:\\logs\\<service-name>.log"',
+    'New-Item -Path (Split-Path $log) -ItemType Directory -Force | Out-Null',
+    '$proc = Start-Process -FilePath "bun" -ArgumentList "run","dev" `',
+    '  -WorkingDirectory "<absolute-cwd>" `',
+    '  -RedirectStandardOutput $log -RedirectStandardError $log `',
+    '  -WindowStyle Hidden -PassThru',
+    'Write-Host "spawned PID $($proc.Id) -> $log"',
+    '```',
+    '',
+    'For Node.js / bun spawn() callers, use:',
+    '',
+    '```js',
+    'const fs = require(\'fs\');',
+    'const { spawn } = require(\'child_process\');',
+    'const logFd = fs.openSync(\'D:/logs/<service-name>.log\', \'a\');',
+    'const proc = spawn(\'bun\', [\'run\', \'dev\'], {',
+    '  cwd: \'<absolute-cwd>\',',
+    '  detached: true,',
+    '  stdio: [\'ignore\', logFd, logFd],   // file fds, NOT pipes',
+    '  windowsHide: true,',
+    '});',
+    'proc.unref();',
+    'console.log(\'spawned PID\', proc.pid);',
+    '```',
+    '',
+    'Key requirements (DO NOT skip any):',
+    '1. **stdio MUST be a file descriptor** (`-RedirectStandardOutput` in PowerShell, or `fs.openSync` + numeric fd in Node). NEVER `inherit`, `pipe`, or omit.',
+    '2. **`-WindowStyle Hidden`** in PowerShell, **`windowsHide: true`** in Node -- keeps the child off your desktop.',
+    '3. **`detached: true` + `proc.unref()`** in Node so the parent can exit without taking the child down.',
+    '4. **Capture the spawned PID immediately** -- that\'s what goes into `keep-pids.json`.',
+    '5. **Verify it actually bound the port before you exit.** Run `Get-NetTCPConnection -LocalPort <port> -State Listen` (PowerShell) or `netstat -an | findstr :<port>` and confirm the port is listening. If not, read the log file (`Get-Content $log -Tail 100`) to diagnose. Don\'t exit claiming success if the port isn\'t listening.',
+    '',
+    'What NOT to do:',
+    '- `Start-Process bun run dev` (no `-RedirectStandardOutput` -> child inherits your console handle -> dies on exit).',
+    '- `bun run dev &` (PowerShell `&` is the call operator, not background -- runs synchronously).',
+    '- `Start-Job { bun run dev }` (PS jobs die when the host exits, which is you).',
+    '- `child_process.spawn(...)` with default stdio (`pipe`) -- same EPIPE problem.',
+    '',
+    'If you hit a problem the recipe doesn\'t cover (e.g. Vite needs `VITE_HOST=127.0.0.1` because it\'s defaulting to `::1` and not binding), fix the env in the spawn call (`-Environment` in PowerShell or `env:` in Node spawn opts), don\'t hack around the spawn pattern itself.',
+    '',
     'After you write the file, the engine\'s sweep removes it automatically when its TTL fires (it kills the kept PIDs at that point) or when all declared PIDs are already dead. Humans can also kill any kept PID early from the dashboard.',
     '',
     '## Verify before exit (REQUIRED)',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1958",
+  "version": "0.1.1959",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"