--- name: aide-release-engineering description: >- Finish AIDE IDE release blockers with verification-first engineering, grounded in official research. Use whenever working on the aide-sovereign-workbench repository: desktop daemon lifecycle and real installer smoke tests, DAP fixture completeness (breakpoint stepping, stack, scopes, variables), editor parity (search, undo history, split groups, recovery), real-repository benchmark batteries, live external provider tests, plugin network capability hardening, accessibility/usability audits, or the final synchronized release build. Research first, encode the decision, act surgically, test live, and refuse unsupported completion claims. --- # AIDE Release Engineering ## Creed (applies to every change) **Research, decide, implement surgically, test live, record the result, refuse unsupported completion claims.** AIDE is a pre-production release candidate, not a finished VS Code replacement. Every claim in README/release artifacts must be evidence-backed and no gate is skipped to reach green. - Success criteria first: write the explicit criteria before editing. - Cheapest discriminating check immediately after every edit. - Fix the work, never weaken the check (no skipped/deleted/loosened tests). - Automated proof must FAIL if the behavior regresses. - Log every meaningful change in `docs/RESEARCH_LOG.md` and the master `AGENT_NOTES.md` (via skill: project-governance). - Baseline before changing anything: `npm run check && npm test` must pass. - Never interrupt GPU model training (R2); do CPU-only work while it runs. ## Verified Platform Facts ### Node.js permission model (source: nodejs.org/api/permissions.html, Node 24/25 release notes) - Flag is `--permission` since Node 24.0.0 (`--experimental-permission` was a semver-major removal). Using the old flag = `bad option` crash on modern Node. - Deny-by-default when enabled: fs, network, child processes, worker threads, native addons, WASI, FFI, runtime inspector. - Grants: `--allow-fs-read=` (path-scoped), `--allow-fs-write=`, `--allow-net` (Node 25+, NOT in 24), `--allow-child-process`, `--allow-worker`, `--allow-addons`, `--allow-wasi`, `--allow-ffi`. - `--permission-audit` mode reports violations without denying — use it to discover required grants before enforce mode. - Runtime assertion: `process.permission.has('net')` etc. — fail loudly on bad config. - **Seat belt, not a sandbox**: official docs say it does NOT provide security guarantees against malicious code. Deny network/child-process by default is blast-radius reduction, not a complete boundary. OS-level isolation (separate OS user / container / seccomp) is still required for untrusted code. - CVE-2026-21636: v25 UDS connections bypassed `--allow-net` restrictions. Verify the running Node line's status before claiming network denial is airtight. Keep egress control at the network layer regardless. ### Debug Adapter Protocol (source: microsoft.github.io/debug-adapter-protocol, debugpy wiki, overview.md) - Mandatory sequence: `initialize` first (server returns capabilities) → server sends `initialized` → client sends `launch`/`attach` → client sends `setBreakpoints` (REPLACES all breakpoints for that source, not incremental; unsettable breakpoints are returned `verified: false` and later corrected via `breakpoint` event) → `setExceptionBreakpoints` (if supported) → `configurationDone` → debuggee runs. - On any stop, the adapter sends `stopped` (reason: breakpoint/step/exception/ pause/entry; includes threadId). The client then runs the inspection waterfall: `threads` → `stackTrace` → `scopes` (per frame) → `variables` (per scope) → nested `variables`. - Object references (`frameId`, `variablesReference`) are ONLY valid during the current stopped state and become invalid when execution resumes; reset numbering on each stop. `threadId` persists for the session. - Control: `continue`, `next`, `stepIn`, `stepOut`, `pause` (all reference threadId). Debuggee launched: `terminate` (graceful) then `disconnect` (forceful) if it does not exit; always end with a `terminated` event. - debugpy: adapter speaks DAP over stdin/stdout; launch scenarios require breakpoints set before `configurationDone`. Real breakpoint stepping requires a live debuggee fixture — session-event recording alone is not readiness. DEBUGPY CLIENT QUIRKS (verified 1.8.21 from source + wire probes): the `initialized` event is sent DURING launch/attach handling (not after initialize); the `launch` RESPONSE is deferred and only sent when the client issues `configurationDone` (`clients.py` line 282 `return messaging.NO_RESPONSE # will respond on "configurationDone"`) — awaiting the launch response before configurationDone hangs forever; the adapter process is long-lived and exits only after the client closes the channel (stdin EOF) — close it after `terminated` for a clean exit; pydevd reports reason `breakpoint` (not `step`) when a `next` lands in a comprehension frame on the same physical line as a breakpoint (keep breakpoint lines single frame-free statements); pydevd quotes dict keys and string values in `variables` responses (`'items'`, `'Fizz'`) and zero-pads list indices (`02`). ### Editor parity (source: code.visualstudio.com/docs/editing/codebasics, userinterface, custom-layout, microsoft/vscode Working Copies wiki) - Find in file: highlights in editor + overview ruler; `closeOnResult`; query history restored across restarts. - Search across files: results grouped by file with hit counts, click-through preview, replace with pending-diff preview, replace-all scoped per file. - Undo/redo: editor model owns an undo stack; dirty state is derived from it; save clears the stack baseline; backups (hot exit) are deleted after save. - Editor groups: split (Ctrl+\\), open-to-side, close group, move tabs, per-group MRU (Ctrl+Tab), group navigation (Ctrl+1..3), empty groups close by default. One TextDocument model can back multiple editor views. - Recovery: persist session state (open files, active file, layout) without persisting secrets/prompts/source; restore on boot; unsaved edits restored from backups and marked dirty. ### Tauri desktop + NSIS installer (source: v2.tauri.app/distribute/windows-installer, tauri-apps issues #9950/#15134, PR #14479, real CI smokes) - Sidecars: `bundle.externalBin` resolves to `src-tauri/{name}-{target-triple}.exe`. Rebuilds can serve a stale cached copy from `target/release/` — re-copy and checksum before bundling; log sidecar path/size. - NSIS does NOT replace unversioned sidecar binaries on same-version reinstall, and a RUNNING sidecar holds a file lock that hangs the installer. Fix: `NSIS_HOOK_PREINSTALL` with `nsis_tauri_utils::KillProcessCurrentUser ".exe"` before file replacement. Tauri v2 uses the Windows Restart Manager for graceful main-app close on upgrade. - Install modes: per-user default (%LOCALAPPDATA%, no admin); perMachine or both need admin. WebView2: downloadBootstrapper (default) / embedBootstrapper / offlineInstaller (~127MB) / fixedVersion / skip. - Installer smoke tests (CI): silent install `/S /D=`, bounded timeouts (per-install cap ~480s + job timeout so hangs fail fast), stop app + sidecar process tree BEFORE the upgrade install, verify the registry Uninstall key, expected version metadata, then launch and smoke the sidecar/daemon health. - Cleanup: no orphaned runtimes — the shell owns the daemon lifecycle (start on boot, terminate on app exit, crash cleanup). Windows child processes should be tied to a Job Object so the whole tree dies together. ### Real-repository benchmark battery (source: swebench.com harness/evaluation docs) - Metric core: FAIL_TO_PASS (resolution) + PASS_TO_PASS (maintenance). Resolution: FULL = f2p==1 && p2p==1; PARTIAL = 0`; add `--allow-fs-write= `, `--allow-net`, `--allow-child-process` only if declared and trust-gated. Never grant network/child-process by default. 2. Keep: path-escape check (entry resolves inside pluginDir), `--no-addons`, stdin JSON payload, stdout JSON-only contract, 10s timeout, bounded output, trust-before-execute, no UI-process load. 3. Tests: untrusted plugin refused; entry escaping pluginDir refused; manifest WITHOUT network capability is denied network (probe with a fetch that must fail with ERR_ACCESS_DENIED); manifest WITH network capability gets `--allow-net`; invalid JSON output rejected; timeout kills the child. ### DAP fixture completeness (breakpoint stepping, stack, scopes, variables) 1. Launch a REAL debuggee fixture (debugpy on a small Python program) through the DAP manager and record the wire sequence. 2. Assert the full lifecycle: initialize → initialized → launch → setBreakpoints (before configurationDone) → configurationDone → stopped (reason breakpoint) → threads → stackTrace → scopes → variables → nested variables. 3. Assert stepping: continue/next/stepIn/stepOut produce new stopped events with changed state; object references reset per stop; threadId stable. 4. Assert teardown: terminate → disconnect → terminated event; no orphaned debuggee process remains. 5. Expose to UI only what the fixture proves; keep honest status. ### Editor parity (search, undo history, split groups, recovery) 1. Search: in-file find with highlight + query history; cross-file search grouped by file; replace with preview; replace-all per file; results click-to-navigate. 2. Undo: per-file undo stack with dirty-state sync; undo/redo round-trips byte-exact; save resets baseline; new edits after undo branch the stack. 3. Split groups: split active editor (Ctrl+\\), open-to-side, per-group tabs, group close/move, MRU navigation; same document model backed by multiple views stays consistent. 4. Recovery: persist only non-secret UI state atomically; restore on boot; unsaved edits restored as dirty; no prompts/credentials/source persisted. 5. Each feature: unit test + UI audit entry + daemon endpoint test. Tests fail on revert. ### Desktop daemon lifecycle + installer smoke tests 1. Local (no Rust): verify desktop prepare bundles daemon source + runtime, start/health/terminate the daemon process, assert clean exit and no orphans. 2. CI (Windows GitHub Actions): tauri build; installer smoke — silent install `/S /D=`, verify registry Uninstall key + version, launch app, daemon health HTTP 200, sidecar process alive; kill process tree; silent upgrade; verify version bump; uninstall; assert no leftover processes. Bound every install with a timeout and add job-level timeouts. 3. Rust compilation remains BLOCKED locally until cargo exists — record it as an open gate, do not claim desktop readiness. ### Real-repository benchmark battery 1. Use the existing acceptance/orchestrator harness against a real repo task set (not demo files): public task prompts, exact environment recorded. 2. Report per task: patch applied (yes/no), tests run (FAIL_TO_PASS + PASS_TO_PASS), resolution status, latency, memory, raw output, failure reasons. Never claim a pass without the raw test log. 3. Different run_id for different predictions; publish results JSON. ### Live external provider tests - Local mode remains default; provider adapters only run with user-supplied credentials, keep credentials server-side, never persist keys or prompts in artifacts. Live tests are explicitly unrun without credentials — record that as an intentional gap, never fabricate provider responses. ### Accessibility + usability audit 1. Automated: UI audit script + axe-style scan (if tooling available) for alt, labels, contrast candidates, ARIA name/role/value, missing `aria-live`. 2. Manual (non-automatable): keyboard traversal of every interactive element (visible focus, logical order, no traps), screen-reader pass, 200% zoom / 320px reflow, contrast 4.5:1 / 3:1, reduced motion, 24x24 target sizes, focus never obscured by sticky UI, command palette reachable by keyboard. 3. Fix defects by criterion, re-audit, record results in RESEARCH_LOG. ### CI pipeline hang — `node --test` never exits on ubuntu-latest (OPEN as of 2026-08-21) **What/why:** since Phase 5/6 every push leaves the `verify` job red: the architecture-tests step runs past its ceiling and is killed externally. Local Windows gates are green (check:arch 188/188, ci-run-all ~55s), so the trigger is CI-environment-specific. Branch protection requires the `verify` check, so this blocks the release gate entirely. **Verified mechanism (local repro, Node v26.4.0):** `--test-timeout` only MARKS a hung test/hook as timed-out — the runner still awaits the underlying promise forever. The file never completes, so `after()` hooks never run, so any handle cleanup placed there never executes, and the open handle keeps the child alive. A "timed out" line in output does NOT mean the runner moved on. **Attempted fixes (do not retry blindly):** 1. `--test-timeout=90000` on check:arch (c50209d) — insufficient alone (see mechanism above). 2. `closeAllConnections()` before `httpServer.close()` in `after()` across 9 test files (a6ff483) — correct hygiene, KEEP, but did NOT clear the hang (run #146 still killed at exactly 900s by `timeout 900`, exit 124). Explained by the mechanism: if the hang is inside a TEST BODY (not a hook), `after()` never runs at all. 3. Step split + `timeout 900` wrapper + ps-dump (4833c46) — proved no leftover child processes annotation appeared; kill is clean, hang is internal. **Diagnostic in flight:** f17dc97 wraps the arch step with `timeout -k 30 900`, tees output to /tmp/arch-out.txt, and on failure dumps the last 80 lines as `ARCH_TAIL1`/`ARCH_TAIL2` `::error::` annotations plus leftover processes as `ARCH_PS`. This names the exact hung test file/case. **SOP for the next cycle:** 1. Poll run status via REST (unauthenticated works for public repos): `/repos/AnonymousNomad/aide-sovereign-workbench/actions/runs`. 2. Fetch annotations: `/repos/.../commits//check-runs` → `annotations_url`. Logs endpoint needs `actions:read` (token lacked it); annotations do NOT need auth. 3. Read ARCH_TAIL*: last COMPLETED test names the hang point (the next test after it, or a named timed-out test, is the suspect). 4. Fix surgically in that test (missing dispose/close/abort), or convert an unawaited promise. Never weaken or delete the test. 5. Re-push, verify green END-TO-END (verify job + veritas step). 6. Veritas exit-1 is the SAME root cause: harness/checks.mjs runs `npm run check` internally with execFile timeouts (compile 120s, tests 300s) — fixing the hang fixes veritas; verify separately. **Threat matrix (issue → impact → status):** - Hung test body awaited forever → file never completes → after() skipped → process leak → step killed at ceiling → verify red → release blocked. CONFIRMED mechanism; specific test UNKNOWN until #148 annotations. - WS sockets left open by tests failing before socket.close() → httpServer.close() callback never fires → PROCESS-STILL-ALIVE class. Mitigated (a6ff483) but hang persisted → likely NOT the whole story. - ubuntu-latest vs Windows env delta (IPv6 localhost, pipe/EPIPE behavior, no Defender) → candidate discriminator; not yet isolated. - Stale runs #135–#140 stuck in_progress forever (pre-timeout workflow version) → queue noise; cancel via API/UI (needs actions:write token). - Local machine stalls masquerading as failures: wedged git fsmonitor (use `git -c core.fsmonitor=false ...`) and Invoke-RestMethod without `-TimeoutSec` (always set one). **Pitfalls (each cost a run):** - Bare `tsc`/`eslint` in `run:` steps → exit 127 (no node_modules/.bin on PATH) — use `npx` (573bb44 → af1fe5d). - Treating a "timed out" test marker as "runner moved on" — it did not. - Playwright `selectOption({label: regex})` is invalid — resolve the value via getAttribute first. - TS `erasableSyntaxOnly` + `exactOptionalPropertyTypes`: conditional spreads / normalizeOptions, never direct optional-prop assignment. ### Synchronized release build 1. `npm run check`, full `npm test`, `npm run veritas` (compile, tests, Git whitespace, manifest validation, path boundaries, secret scanning) all pass. 2. Benchmarks + arena results fresh; README claims limited to what the release proves; release assets = checksums + known limitations published. 3. Status stays pre-production release candidate; no VS Code parity claim. ## Release Gates - No claim without recorded numbers; a failed gate is recorded, not hidden. - Plugin execution: trust + capability-gated permission model enforced. - DAP: real debuggee fixture passes the full lifecycle before readiness. - Editor: search/undo/split/recovery each have failing-on-revert tests. - Desktop: no production-ready claim until installer smokes pass on CI. - Benchmarks: raw logs published; no fabricated pass rates. - A11y: audit fixes verified per criterion. - Training/GPU processes are never interrupted (R2). ## References Detailed sources with URLs: `references/sources.md` (same directory).