@deepseek-insight/dsi 0.6.14 → 0.6.16

package/.agents/skills/dsi-ports/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: dsi-ports
+description: Fast feedback-loop port inventory — run /dsi-ports (or ask "what's running / which ports are open / what's eating memory") to list every TCP listener with pid, process, memory usage, and its purpose (DSH host, DSI UI, Playwright, inspector, test floors). Backed by the Port Ledger KB.
+---
+
+# dsi-ports — the Port Ledger, live
+
+Companion KB: `dev/kb/open-ports/2026-10-12 - The Port Ledger — Who Opens What, Why, and How Test Floors Stay Isolated.md` — read it for WHY each port exists. This skill is the LOOK-path: one command, one table, no judgment.
+
+## Run
+
+Execute this single pipeline (macOS; safe, read-only). AGENT HYGIENE: write
+the block to a temp file (`/tmp/dsi-ports.sh`) and run `sh` on it — inlining
+shell `$-expansions` inside a JS template string breaks the tool call
+(observed 2026-10-12); the failure is the caller's, not the pipeline's.
+
+```sh
+for pid_port in $(lsof -nP -iTCP -sTCP:LISTEN | awk 'NR>1 {match($9, /[^:]*$/); print substr($9, RSTART) "/" $2}' | sort -u); do
+  port=${pid_port%%/*}; pid=${pid_port##*/}
+  rss=$(ps -o rss= -p "$pid" 2>/dev/null | awk '{printf "%.0f MB", $1/1024}')
+  cmd=$(ps -o command= -p "$pid" 2>/dev/null | cut -c1-70)
+  echo "$port | $pid | ${rss:-?} | $cmd"
+done | sort -n
+```
+
+## Format the output
+
+Present EXACTLY this table (port ascending), then the purpose line:
+
+| Port | PID | Process | Memory (RSS) | Purpose |
+|---|---|---|---|---|
+| 3080 | 1234 | node …/vite.js dev | 412 MB | **DSH host** — browser RPC + token announce |
+| 5175 | 1234 | node …/vite.js dev | 388 MB | **DSI dev UI** — the page the operator uses |
+
+Purpose lookup (from the Port Ledger KB — first match wins):
+
+| Port | Purpose |
+|---|---|
+| 3080 | DSH host — browser RPC, token announce |
+| 5174 | DSI built UI (production page) |
+| 5175 | DSI dev UI (Vite, HMR) |
+| 5176 | Playwright webServer (vite preview, e2e backend) |
+| 9229 | Node inspector (D7 — one debugger for DSI + embedded host) |
+| 1933 | OpenViking memory server |
+| 34xx | test-floor DSH host (isolated) |
+| 51xx (5180+) | test-floor UI (isolated) |
+| anything else | **unknown — name the binary and ask** (never guess a purpose) |
+
+## Reading the table (tell the operator, one line each)
+
+- Same PID on TWO ports (e.g. 3080 + 5175) → the **in-process floor** (one process, D7).
+- 5175 up but 3080 down → UI-only floor; the page will show "Failed to fetch".
+- 3080 up but no 5175/5174 → bare host (tandem's other half missing, or runCli host only).
+- Two PIDs on the same port → TWO listeners — list both rows, flag it.
+- Biggest RSS → name it; vite dev floors routinely sit at 300–500 MB (normal).
+
+## Boundaries
+
+- Read-only: `lsof`, `ps`, `sort`. Never kill, never open, never edit — remediation is always a separate, confirmed step.
+- IPv6 vs IPv4 duplicates: same port with different PIDs means TWO listeners — list both rows, flag it.
+- The table is a snapshot; ports move between runs. Re-run, don't cache.

package/.agents/skills/dsi-restart/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: dsi-restart
+description: Restart the DSI/DSH floor with a before/after report — /dsi-restart snapshots every listener's port+pid+RSS, restarts (or waits for the operator's restart), re-snapshots, and prints the delta table (which ports restarted, memory freed/claimed). Answers "floor feels heavy, restart and show me what changed".
+---
+
+# dsi-restart — restart with receipts
+
+Companion: `dsi-ports` skill (the snapshot pipeline) and the Port Ledger KB (`dev/kb/open-ports/`). This skill adds the DELTA: before, restart, after, memory moved.
+
+## 0. Identify how the floor is running (do not skip)
+
+**Facts first (2026-10-12, hard rule):** classify launch shape ONLY from a full
+ancestry walk — `ps -o pid,ppid,lstart,command` repeated up the ppid chain
+until you reach pid 1 or an interactive `zsh`/`login`. Record each hop. An
+immediate-parent glance is not detection: the same zsh can own both a dead
+floor's corpse and the replacement the OPERATOR launched by hand (precedent
+2026-10-12: the assistant claimed a "detached relaunch" that was actually the
+operator re-running the command in their own terminal). **Never narrate a
+relaunch you did not perform and cannot cite a pid + start time for.**
+
+| Launch shape | Detection (full ancestry walk) | Who may restart it |
+|---|---|---|
+| Operator's foreground terminal | the `bin/dsi.mjs` chain's top parent is an interactive `zsh`/`login` (walk ppids; lstart proves which launch is which) | **the operator only** — or the Restart Verb with the operator's go (§2) |
+| Detached chain (plugin-rack / verb bounce) | the chain's top parent is pid 1 (launchd) | the skill, via the Restart Verb or `--sync-kills` + relaunch |
+
+If detection is ambiguous → **ask the operator** before killing anything (precedent: pid 37084, 2026-10-12 — the assistant killed the operator's live floor during cleanup).
+
+**Exit-143 rule (2026-10-12, corrected):** when the floor dies — Ctrl-C, kill,
+or the Restart Verb hitting a foreground-terminal floor — the terminal prints
+`ELIFECYCLE Command failed with exit code 143` and the floor is **DOWN. It
+does not come back by itself.** Only the detached restart chain (the verb's
+spawned one-shot) or a human re-running the command brings it back. Never
+write or say "the floor came back detached" without a pid + `lstart` you just
+read from `ps` — an unverified rebirth story cost the operator a dead floor
+and a wrong incident report (2026-10-12).
+
+## 1. Snapshot BEFORE
+
+Run the dsi-ports pipeline (see dsi-ports skill for the script) and save:
+
+```sh
+sh /tmp/dsi-ports.sh > /tmp/floor-before.txt
+```
+
+## 2. Restart
+
+- **PREFERRED, every shape: the Restart Verb (shipped — ADR "The Restart Verb,
+  One Button, One Route, Receipts", 2026-10).** With the operator's go, click
+  the power button in the sidebar header (or `POST /api/floor/restart`). It
+  spawns the same detached chain plugin-apply uses, so the floor re-serves in
+  the same mode (`--sync --dev in-process` fidelity) even when the previous
+  floor lived in the operator's terminal. Receipts still apply: BEFORE/AFTER
+  snapshots are mandatory.
+- **Fallback, detached/agent-owned floor:** `dsi dsh --sync-kills`, then
+  relaunch the exact previous command (copy it from `ps` BEFORE killing).
+- **Fallback, operator foreground floor (operator declines the verb):** print
+  the restart command and WAIT for the operator to run it (their Ctrl-C, their
+  terminal). Remember: once it dies, it stays dead until someone starts it.
+
+## 3. Snapshot AFTER (wait for both listeners first)
+
+Poll until the expected ports answer (host + UI), then:
+
+```sh
+sh /tmp/dsi-ports.sh > /tmp/floor-after.txt
+```
+
+## 4. The delta report (this is the deliverable)
+
+Present exactly this table — join BEFORE and AFTER on port purpose (not pid: pids always change):
+
+| Port | Purpose | RSS before | RSS after | Delta | PID before → after |
+|---|---|---|---|---|---|
+| 3080 | DSH host | 3262 MB | 1489 MB | **−1773 MB** | 38237 → 41200 |
+
+Then one summary line: total floor RSS before → after, and the verdict:
+- large negative delta + all expected ports up → **restart healthy**
+- a port missing after → **name it loud** (that half of the floor did not come back)
+- RSS after ≥ before → say so honestly; restart did not reclaim (possible leak — offer dsi-rca)
+
+## Boundaries
+
+- Never kill a process the operator owns without their confirmed go (§0).
+- Always restore the EXACT previous launch command/flags/env — a restart that changes the floor's shape is a config change, not a restart.
+- The report is the point: a restart without before/after receipts is just downtime.

package/bin/dsi.mjs

@@ -28,7 +28,8 @@ import { fileURLToPath } from 'node:url';
 import { parse, stringify } from 'yaml';
 
 import { mirrorSkills } from './lib/mirror-skills.mjs';
-import { dshLauncherCmd, parsePluginArgs } from './lib/plugin-chain.mjs';
+import { dshLauncherCmd, parsePluginArgs, takeoverFloorPorts } from './lib/plugin-chain.mjs';
+import { parseDevArg, devModeEnv, modeFromBoolean, resolveBounceMode, extractInspectArgs, parseInspectArgsFromEnv } from './lib/dev-mode.mjs';
 
 // Layman-facing help: wrapped near 76 columns, continuation lines indented,
 // the recommended one-liner first. --zai is optional on purpose — no GLM
@@ -56,7 +57,11 @@ const USAGE = [
 	'               store the dsh launch token as dsh.authToken in',
 	'               ~/.dsi/settings.yaml, then serve',
 	'      --dev    serve the Vite dev server instead of the built page (takes',
-	'               port 5175; needs a full checkout: pnpm install)',
+	'               port 5175; needs a full checkout: pnpm install). Optional',
+	'               value: --dev in-process boots the DSH host INSIDE the dev',
+	'               server process (one process, one Ctrl-C; host still on',
+	'               port 3080; token via in-process intercept). Bare --dev',
+	'               keeps the two-port pair; --dev pair is the same spelled out.',
 	'      --sync-kills',
 	'               kill orphaned dsh/dsi processes left by an earlier run',
 	'      --ov    install the OpenViking memory plugin into the active dsh',
@@ -195,15 +200,16 @@ if (command === 'dsh') {
 		// HMR surface as `pnpm dev`, beside the same synced host.
 		const rest = process.argv.slice(4);
 		const withZai = rest.includes('--zai');
-		const withDev = rest.includes('--dev');
 		const withOv = rest.includes('--ov');
 		if (withZai) addZaiProvider();
 		if (withOv) runOvPlugin();
 		runSkillsMirror();
-		runSyncedPair(
-			rest.filter((arg) => arg !== '--zai' && arg !== '--dev' && arg !== '--ov'),
-			withDev
-		);
+		// --dev parse (D4): 'in-process' | 'pair' consumed as a value; bare
+		// --dev stays 'pair'. dsi-side flags stripped before the host spawn.
+		const { mode, rest: hostArgs0 } = parseDevArg(rest);
+		// D7: inspector flags ride the vite child's execArgv, never the host.
+		const { rest: hostArgs, execArgv: inspectExecArgv } = extractInspectArgs(hostArgs0);
+		runSyncedPair(hostArgs, mode, inspectExecArgv);
 	} else if (flag === '--plugin' || flag === '--plugin-restart') {
 		// The Plugin Rack ADR (2026-09-27, D3/D5): the dsh CLI is the writer,
 		// dsi owns the bounce. Install/remove delegates to the launcher rule
@@ -240,7 +246,20 @@ if (command === 'dsh') {
 		// before the marker existed, or from plain `pnpm dev`, carries none.
 		// The vite dev process itself is visible to pgrep (unlike the npx
 		// shims — different argv rewriting), so ask the process table.
-		const dev = bounceDevMode(parsed.dev === true, isDevFloorAlive);
+		// D6 (2026-10-11): the boolean is no longer enough — an in-process
+		// floor re-served as 'pair' would double-spawn the host. Read the
+		// alive vite's DSI_DEV_MODE via ps -E BEFORE the sweep, resolve the
+		// enum, restore exactly what was running.
+		const floorEnvDump = readFloorEnv(devFloorPid());
+		const mode = resolveBounceMode({
+			flagDev: parsed.dev === true,
+			devFloorAlive: isDevFloorAlive(),
+			floorEnv: floorEnvDump
+		});
+		// The Faithful Bounce (ADR 2026-10-13, D3): the SAME floor env that
+		// records the mode records the inspector flags — re-forward them so
+		// the bounce boot comes back debuggable when it left that way.
+		const bounceExecArgv = parseInspectArgsFromEnv(floorEnvDump);
 		killOrphans();
 		// The pkill sweep cannot see every floor shape (RCA 2026-09-27: the
 		// npx shims — 'npm exec @deepseek-ai/dsh…' and '.bin/dsh web' — are
@@ -248,9 +267,11 @@ if (command === 'dsh') {
 		// 3080 and preflightPort exited 64, killing the detached chain
 		// silently). The bounce chain owns the DSI ports by contract, so
 		// free them by listener, not by name.
-		freeFloorPorts([3080, 5174, 5175]);
-		// Restore the SAME UI mode the floor was serving.
-		runSyncedPair([], dev);
+		await freeFloorPorts(floorPortSet());
+		// Restore the SAME UI mode the floor was serving. The bounce's
+		// boolean signal normalizes to 'pair'/'build' inside runSyncedPair;
+		// 3.5 teaches the bounce the full enum via DSI_DEV_MODE.
+		runSyncedPair([], mode, bounceExecArgv);
 	} else if (flag === '--sync-kills') {
 		killOrphans();
 		process.exit(0);
@@ -367,56 +388,80 @@ function openBrowser(url, delayMs = 2000) {
  *  the Vite dev server (`pnpm dev`'s surface) — as the UI. The pair shares
  *  one lifecycle — a signal or one child's exit tears down the other, so no
  *  orphan survives a Ctrl-C or a crash. */
-async function runSyncedPair(extraArgs, dev = false) {
+async function runSyncedPair(extraArgs, dev = 'build', execArgv = []) {
+	// dev accepts the D4 mode enum ('build' | 'pair' | 'in-process'); the
+	// legacy boolean true is normalized so older call sites keep working.
+	const mode = typeof dev === 'boolean' ? modeFromBoolean(dev) : dev;
 	const script = path.join(packageRoot, 'scripts', 'dsh-web-synced.sh');
-	if (!existsSync(script)) {
+	const inProcess = mode === 'in-process';
+	if (!inProcess && !existsSync(script)) {
 		console.error(`dsi dsh: no sync script at ${script}`);
 		process.exit(66);
 	}
 	// UI port: the built server takes 5174 — the same port `dsi web` uses,
 	// so plain `dsi dsh --sync` listens on ONE port. --dev's Vite dev server
 	// takes 5175 instead (vite.config.ts pins 5174 strictPort, so pair mode
-	// passes 5175 explicitly), giving the two-port dev shape.
-	const uiPort = process.env.PORT ?? (dev ? '5175' : '5174');
+	// passes 5175 explicitly), giving the two-port dev shape. in-process is
+	// also a vite floor: same 5175.
+	const uiPort = process.env.PORT ?? (mode === 'build' ? '5174' : '5175');
 	// The host half takes --port <n> when forwarded (a 3080 held by a
 	// dsh web this CLI does not own — e.g. another live conversation
 	// floor — is exactly the case the preflight must not kill). The
 	// forwarded flag goes to `dsh web` untouched; DSI follows via
 	// DSH_BASE_URL so the page dials the host wherever it landed.
+	// IN-PROCESS: no host child will be spawned, so preflighting 3080 is
+	// pointless — the plugin boots the host on 3080 AFTER vite is up, and
+	// a stale 3080 from a foreign floor is that floor's business (the
+	// embedded boot fails loud in the plugin, killing nothing).
 	warnIfFirstRunDownload();
-	const hostPort = hostPortFromArgs(extraArgs) ?? 3080;
+	// IN-PROCESS: the plugin reads its port from DSH_HOST_PORT (default 3080)
+	// — the UI half MUST dial the same port, so DSH_HOST_PORT participates in
+	// the dshBase derivation exactly like a forwarded --port flag. (Smoke
+	// bug 2026-10-11: DSH_HOST_PORT=3477 booted the host there while the
+	// page dialed 3080 — the production floor — → "Failed to fetch".)
+	const pluginPort = inProcess && process.env.DSH_HOST_PORT ? parseInt(process.env.DSH_HOST_PORT, 10) : undefined;
+	const hostPort = hostPortFromArgs(extraArgs) ?? pluginPort ?? 3080;
 	const dshBase = hostPort === 3080 ? undefined : `http://127.0.0.1:${hostPort}`;
-	// Preflight BOTH halves: a forgotten previous run holds not just the
-	// host port but often the UI port too — the host would only crash
-	// later, and the UI server would crash first with EADDRINUSE.
-	await preflightPort(hostPort, 'dsh host');
-	await preflightPort(uiPort, 'DSI page');
-	const host = spawn('/bin/sh', [script, ...extraArgs], {
+	if (inProcess) {
+		await preflightPort(uiPort, 'DSI page');
+	} else {
+		await preflightPort(hostPort, 'dsh host');
+		await preflightPort(uiPort, 'DSI page');
+	}
+	// IN-PROCESS: no sync script, no host child — the vite plugin owns the
+	// host lifecycle (vite close hook stops it; one Ctrl-C, no orphan).
+	const host = inProcess ? null : spawn('/bin/sh', [script, ...extraArgs], {
 		stdio: 'inherit',
 		env: { ...process.env, DSH_WEB_VERSION: dshWebVersion() }
 	});
-	const ui = dev ? startDsiDevServer(uiPort, dshBase) : startDsiServer(uiPort, dshBase);
+	const ui = mode === 'build' ? startDsiServer(uiPort, dshBase) : startDsiDevServer(uiPort, dshBase, mode, execArgv);
 	// The browser follows the UI: the built page (5174) — or, in --dev mode,
 	// the dev server (5175).
 	openBrowser(`http://localhost:${uiPort}/`);
 	for (const signal of ['SIGINT', 'SIGTERM']) {
 		process.on(signal, () => {
-			host.kill(signal);
+			if (host) host.kill(signal); // in-process: no host child — vite close hook stops it
 			ui.kill(signal);
 		});
 	}
 	const teardown = (code, signal) => {
-		host.kill('SIGTERM');
+		if (host) host.kill('SIGTERM');
 		ui.kill('SIGTERM');
 		process.exit(signal ? 1 : (code ?? 1));
 	};
-	host.on('exit', teardown);
+	if (host) host.on('exit', teardown);
 	ui.on('exit', teardown);
 }
 
 /** Kill orphaned dsh/dsi leftovers — a pair whose parent died before it
  *  could tear down its sibling, or a previous run the terminal lost. */
 function killOrphans() {
+	// Test-floor isolation (Port Ledger 34xx/51xx): a scratch floor's bounce
+	// must never pkill the production floor's shapes.
+	if (process.env.DSI_SKIP_ORPHAN_SWEEP === '1') {
+		console.log('dsi dsh: orphan sweep skipped (DSI_SKIP_ORPHAN_SWEEP=1)');
+		return;
+	}
 	for (const pattern of ORPHAN_PATTERNS) {
 		try {
 			spawnSync('pkill', ['-f', pattern], { stdio: 'pipe' });
@@ -428,20 +473,49 @@ function killOrphans() {
 	console.log('dsi dsh: orphan sweep done (dsh-web-synced.sh, dsh bin, dsi server)');
 }
 
-/** SIGTERM whatever LISTENS on these ports: the bounce chain's name-blind
- * second sweep (RCA 2026-09-27). pkill -f cannot match every floor shape
- * (the npx shim processes are invisible to it on macOS), so a surviving
- * dsh host held 3080, preflightPort exited 64, and the detached chain died
- * silently. Only the bounce uses this; a manual --sync preflight still
- * REFUSES a busy port it does not own. */
-function freeFloorPorts(ports) {
-	for (const port of ports) {
+/** The DSI ports the bounce owns. DSI_FLOOR_PORTS overrides for isolated
+ *  test floors (Port Ledger: 34xx host, 5180+ UI) so a scratch bounce never
+ *  touches the production ports. */
+function floorPortSet() {
+	const raw = process.env.DSI_FLOOR_PORTS;
+	if (!raw) return [3080, 5174, 5175];
+	const ports = raw.split(',').map((s) => Number(s.trim())).filter((n) => Number.isInteger(n) && n > 0);
+	return ports.length ? ports : [3080, 5174, 5175];
+}
+
+/** SIGTERM whatever LISTENS on these ports, then WAIT until they actually
+ *  free (The Port Takeover ADR 2026-10-12, D2/D3/D5): the fire-and-forget
+ *  kill of RCA 2026-09-27 raced the successor's bind — the dying in-process
+ *  host still held 3080 two seconds later and the new floor died on
+ *  EADDRINUSE (incident: tmp/bounce.log 2026-10-12T03:49:06Z). Every kill
+ *  and every freed port gets a receipt line; a port still held at the
+ *  budget exits 64 naming the port and the holder. Only the bounce uses
+ *  this — the click is the consent (ADR D1); a manual --sync preflight
+ *  still REFUSES a busy port it does not own. */
+async function freeFloorPorts(ports) {
+	const listListeners = (port) => {
 		try {
-			spawnSync('/bin/sh', ['-c', 'lsof -ti tcp:' + port + ' -sTCP:LISTEN | xargs kill 2>/dev/null || true'], { stdio: 'pipe' });
+			const probe = spawnSync('/bin/sh', ['-c', 'lsof -ti tcp:' + port + ' -sTCP:LISTEN 2>/dev/null || true'], { stdio: 'pipe', encoding: 'utf8' });
+			return (probe.stdout || '').split('\n').map((s) => Number(s.trim())).filter((n) => Number.isInteger(n) && n > 0);
 		} catch {
-			// no lsof (or no xargs): the pattern sweep above and the 5s
-			// preflight wait remain the honest fallbacks.
+			// no lsof (or no sh): nothing to signal; the wait loop below will
+			// report the port honestly if it never frees.
+			return [];
 		}
+	};
+	const result = await takeoverFloorPorts(ports, {
+		listListeners,
+		terminate: (pid) => {
+			try { process.kill(pid, 'SIGTERM'); } catch { /* already gone — the wait decides */ }
+		},
+		portFree: (port) => portInUse(port).then((busy) => !busy),
+		sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+		now: () => Date.now(),
+		log: (line) => console.log(line)
+	});
+	if (!result.ok) {
+		console.error('dsi dsh: port ' + result.port + ' is still in use by a process the takeover does not own (pid ' + result.pid + ') — free it yourself, then re-run');
+		process.exit(64);
 	}
 }
 
@@ -455,6 +529,28 @@ function isDevFloorAlive() {
 	return (probe.status ?? 1) === 0;
 }
 
+/** The alive dev floor's vite pid (first match), or null. Same match rule
+ *  as isDevFloorAlive — the pid feeds the D6 mode read (ps -E). */
+function devFloorPid() {
+	const probe = spawnSync('pgrep', ['-f', 'deepseek-insight/node_modules/vite/bin/vite.js'], { stdio: 'pipe' });
+	if ((probe.status ?? 1) !== 0) return null;
+	const first = (probe.stdout?.toString() || '').split('\n').find(Boolean);
+	return first ? first.trim() : null;
+}
+
+/** The floor's DSI_DEV_MODE via ps -E (macOS: own processes only). Returns
+ *  '' when the read fails for any reason — resolveBounceMode then falls back
+ *  to the boolean arms, the pre-D6 behavior, never a wrong restore. */
+function readFloorEnv(pid) {
+	if (!pid) return '';
+	try {
+		const ps = spawnSync('ps', ['-E', '-p', String(pid)], { stdio: 'pipe', timeout: 5000 });
+		return ps.status === 0 ? ps.stdout?.toString() || '' : '';
+	} catch {
+		return '';
+	}
+}
+
 /** Add the ZAI provider and default model to ~/.dsh/settings.yaml when
  *  absent. Existing entries always win — an already-configured host is
  *  rewritten only when at least one block was added. Exits non-zero when
@@ -573,7 +669,7 @@ function runSkillsMirror() {
  *  sources and devDependencies exist — a published tarball (bin + build)
  *  refuses loudly instead of half-booting. The --port CLI flag overrides the
  *  config's server.port while strictPort keeps the fail-loud contract. */
-function startDsiDevServer(defaultPort = '5175', dshBase = undefined) {
+function startDsiDevServer(defaultPort = '5175', dshBase = undefined, mode = 'pair', execArgv = []) {
 	const viteBin = path.join(packageRoot, 'node_modules', 'vite', 'bin', 'vite.js');
 	if (!existsSync(viteBin)) {
 		console.error(`dsi dsh --dev: no vite at ${viteBin} — --dev needs a full DSI checkout (pnpm install); use the built server instead`);
@@ -581,7 +677,13 @@ function startDsiDevServer(defaultPort = '5175', dshBase = undefined) {
 	}
 	// --host matches the built server's 127.0.0.1 bind: vite's default
 	// 'localhost' can resolve ::1-only and strand a 127.0.0.1 client.
-	return spawn(process.execPath, [viteBin, 'dev', '--host', process.env.HOST ?? '127.0.0.1', '--port', process.env.PORT ?? defaultPort], {
+	return spawn(process.execPath, [...execArgv, viteBin, 'dev', '--host', process.env.HOST ?? '127.0.0.1', '--port', process.env.PORT ?? defaultPort], {
+		// D7: inspector flags lead the child argv — node consumes options before
+		// the script path, so `node --inspect vite.js dev` debugs THIS process
+		// (vite + the embedded DSH host share one heap). The spawn execArgv
+		// OPTION was tried first and empirically never activated the inspector
+		// (silent no-op, probed 2026-10-11); leading args are the reliable form.
+		// NODE_OPTIONS is banned — it leaks to every child and collides on port.
 		stdio: 'inherit',
 		cwd: packageRoot,
 		env: {
@@ -592,6 +694,13 @@ function startDsiDevServer(defaultPort = '5175', dshBase = undefined) {
 			// this from the API server's env to re-serve --dev instead of the
 			// stale build. Nothing else may set it.
 			DSI_DEV: '1',
+			// D4/D6: the mode rides as env, never past the CLI to the host.
+			...devModeEnv(mode),
+			// The Faithful Bounce (ADR 2026-10-13, D1): the inspector flags are
+			// part of the launch record — stamped so every restorer (the bounce
+			// boot via ps -E, the delayed re-serve via inherited env) can put
+			// them back exactly as launched.
+			...(execArgv.length ? { DSI_INSPECT_ARGS: execArgv.join(' ') } : {}),
 			...(dshBase !== undefined ? { DSH_BASE_URL: dshBase } : {})
 		}
 	});

package/bin/lib/dev-mode.mjs

@@ -0,0 +1,138 @@
+/**
+ * dev-mode — parse the --dev flag's optional value and derive env markers.
+ *
+ * ADR: dev/architectural-decission/2026-10/2026-10-11 - The In-Process Host
+ * (D4: --dev gains an optional value; bare --dev keeps today's meaning;
+ * the mode rides to vite via env, never past the CLI to the dsh web host).
+ *
+ * Modes:
+ *   'build'      — the built page (no --dev)
+ *   'pair'       — vite dev server + separate host child (bare --dev / --dev pair)
+ *   'in-process' — vite dev server boots the host itself (--dev in-process)
+ */
+
+/** Tokens the --dev flag may consume as its value. Anything else after
+ *  --dev belongs to some other flag (or the host) and is left alone. */
+const DEV_VALUES = new Set(['in-process', 'pair']);
+
+/**
+ * Parse a rest-args array for --dev (and strip dsi-side flags).
+ * @param {string[]} rest — args AFTER the subcommand (e.g. after 'dsh --sync')
+ * @returns {{ mode: 'build'|'pair'|'in-process', rest: string[] }}
+ *   rest — args with --dev (and its value) plus other dsi-side flags removed,
+ *   safe to forward to the dsh web host.
+ */
+export function parseDevArg(rest) {
+	const out = [];
+	let mode = 'build';
+	for (let i = 0; i < rest.length; i++) {
+		const arg = rest[i];
+		if (arg === '--zai' || arg === '--ov') continue; // dsi-side, stripped (pre-existing contract)
+		if (arg === '--dev') {
+			const next = rest[i + 1];
+			if (next && DEV_VALUES.has(next)) {
+				mode = next === 'pair' ? 'pair' : 'in-process';
+				i++; // consume the value — it never reaches the host
+			} else {
+				mode = 'pair'; // bare --dev keeps today's meaning (D4)
+			}
+			continue;
+		}
+		out.push(arg);
+	}
+	return { mode, rest: out };
+}
+
+/**
+ * Env additions for the vite child expressing the chosen mode.
+ * DSI_DEV=1 is the pre-existing dev-floor marker (RCA 2026-09-27) — kept for
+ * the bounce chain's boolean probe; DSI_DEV_MODE is the D6 mode enum.
+ */
+export function devModeEnv(mode) {
+	if (mode === 'build') return {};
+	const env = { DSI_DEV: '1', DSI_DEV_MODE: mode };
+	if (mode === 'in-process') env.DSI_DEV_IN_PROCESS = '1';
+	return env;
+}
+
+/**
+ * Map the legacy boolean dev signal (bounceDevMode's return, older floors)
+ * to a mode. Wave 3.5 will teach the bounce the enum; until then the bounce
+ * can only ever restore 'pair' or 'build'.
+ */
+export function modeFromBoolean(dev) {
+	return dev ? 'pair' : 'build';
+}
+
+/**
+ * Parse ps -E -p <pid> output for the floor's DSI_DEV_MODE marker (D6).
+ * Pure: the ps invocation is injected by dsi.mjs.
+ * @param {string} psOutput — full environment dump of the vite process
+ * @returns {'in-process' | null} null = marker absent (pair/build floor)
+ */
+export function parseDevModeFromPsE(psOutput) {
+	const m = /(?:^|\s)DSI_DEV_MODE=(\S+)/.exec(psOutput || '');
+	return m && m[1] === 'in-process' ? 'in-process' : null;
+}
+
+/**
+ * Resolve the mode a bounce must RESTORE (D6 — the plugin-apply restart
+ * runs in a fresh CLI that cannot see the original argv).
+ *
+ * Priority:
+ *   1. the alive floor's own env says in-process → restore 'in-process'
+ *      (D6, sharpened 2026-10-12 Port Takeover: the floor's RECORDED mode is
+ *      authoritative over the bounce's --dev flag — the verb's chain always
+ *      carries --dev, and letting it win bounced in-process floors into
+ *      'pair', which spawned a sync-script host AND left the stale
+ *      DSI_DEV_IN_PROCESS marker active in the chain env, so two hosts
+ *      fought for 3080 and the floor died on EADDRINUSE every click)
+ *   2. explicit --dev flag on the bounce itself → 'pair' (legacy semantics;
+ *      the operator asked for a dev re-serve)
+ *   3. a dev floor is alive (boolean probe) → 'pair'
+ *   4. nothing alive → 'build'
+ * @param {{ flagDev?: boolean, devFloorAlive?: boolean, floorEnv?: string }} p
+ */
+export function resolveBounceMode(p = {}) {
+	if (p.floorEnv && parseDevModeFromPsE(p.floorEnv) === 'in-process') return 'in-process';
+	if (p.flagDev) return 'pair';
+	if (p.devFloorAlive) return 'pair';
+	return 'build';
+}
+
+/**
+ * Parse a ps -E environment dump for DSI_INSPECT_ARGS (ADR 2026-10-13
+ * "The Faithful Bounce", D3): the space-joined inspector flags the launcher
+ * stamped beside the dev-mode markers. Pure: the dump string is injected.
+ * @param {string} psOutput — full environment dump of the vite process
+ * @returns {string[]} inspector argv ([] = none recorded / pre-stamp floor)
+ */
+export function parseInspectArgsFromEnv(psOutput) {
+	// ps -E is ONE line of KEY=VALUE tokens — the value ends at the next
+	// KEY= token (identifier-shaped, so '--inspect=...' never trips it),
+	// at a newline, or at end-of-dump. Lazy capture + lookahead.
+	const m = /(?:^|\s)DSI_INSPECT_ARGS=(.*?)(?=\s+[A-Za-z_][A-Za-z0-9_]*=|\s*$|\n|\r)/.exec(psOutput || '');
+	if (!m) return [];
+	return m[1].trim().split(/\s+/).filter(Boolean);
+}
+
+/**
+ * Pull Node inspector flags out of the rest-args: --inspect, --inspect-brk,
+ * --inspect=<host:port>. Forwarded to the vite child's execArgv (D7) —
+ * NEVER via NODE_OPTIONS, which would leak the inspector to every child
+ * dsi.mjs spawns and collide on the default port.
+ * @param {string[]} rest
+ * @returns {{ rest: string[], execArgv: string[] }}
+ */
+export function extractInspectArgs(rest) {
+	const out = [];
+	const execArgv = [];
+	for (const arg of rest) {
+		if (arg === '--inspect' || arg === '--inspect-brk' || arg.startsWith('--inspect=')) {
+			execArgv.push(arg);
+			continue;
+		}
+		out.push(arg);
+	}
+	return { rest: out, execArgv };
+}

package/bin/lib/plugin-chain.mjs

@@ -70,6 +70,53 @@ export function bounceDevMode(flagDev, devFloorAlive) {
 	}
 }
 
+/** The takeover's bounded-wait budget and poll cadence (The Port Takeover
+ *  ADR 2026-10-12, D3): after the SIGTERM sweep the chain waits until every
+ *  DSI port actually frees — at most this budget — then re-serves. A port
+ *  still held at the deadline is an honest exit 64, never a half-boot. */
+export const TAKEOVER_BUDGET_MS = 10_000;
+export const TAKEOVER_POLL_MS = 250;
+
+/**
+ * The takeover sweep (The Port Takeover ADR 2026-10-12, D2/D3/D5): SIGTERM
+ * whatever LISTENS on the given ports, then WAIT until each port frees,
+ * bounded. Pure orchestration — every effect is injected, so unit tests run
+ * it against fakes and the real half stays in dsi.mjs.
+ *
+ * @param {number[]} ports
+ * @param {{ listListeners: (port: number) => number[], terminate: (pid: number) => void,
+ *            portFree: (port: number) => boolean | Promise<boolean>, sleep: (ms: number) => Promise<void>,
+ *            now: () => number, log: (line: string) => void }} effects
+ * @returns {Promise<{ ok: boolean, port?: number, pid?: number | string }>} ok:false names the port and holder (exit 64 is the caller's)
+ */
+export async function takeoverFloorPorts(ports, effects) {
+	const { listListeners, terminate, portFree, sleep, now, log } = effects;
+	const start = now();
+	for (const port of ports) {
+		for (const pid of listListeners(port)) {
+			terminate(pid);
+			log('takeover: SIGTERM pid ' + pid + ' on port ' + port);
+		}
+	}
+	for (const port of ports) {
+		let freed = null;
+		while (now() - start <= TAKEOVER_BUDGET_MS) {
+			if (await portFree(port)) {
+				freed = now() - start;
+				break;
+			}
+			await sleep(TAKEOVER_POLL_MS);
+		}
+		if (freed === null) {
+			const holder = listListeners(port)[0] ?? 'unknown';
+			log('takeover: port ' + port + ' still held by pid ' + holder + ' after ' + TAKEOVER_BUDGET_MS + 'ms — giving up');
+			return { ok: false, port, pid: holder };
+		}
+		log('takeover: port ' + port + ' free after ' + freed + 'ms');
+	}
+	return { ok: true };
+}
+
 /**
  * The dsh launcher rule (runOvPlugin's, generalized): DSH_WEB_CMD override,
  * else the pinned published dsh via npx. The webVersion pin comes from the