mixdog 0.9.20 → 0.9.22

package/src/runtime/shared/atomic-file.mjs

@@ -20,6 +20,14 @@ const LOCK_WAIT_CODES = new Set(['EEXIST', 'EPERM', 'EACCES', 'EBUSY']);
 const DEFAULT_BACKOFFS_MS = Object.freeze([25, 50, 100, 200, 400, 800, 1200, 1600]);
 const DEFAULT_LOCK_TIMEOUT_MS = 8000;
 
+// Per-process owner identity. A bare pid is not a durable holder identity:
+// after a holder crashes the OS can recycle its pid onto an unrelated live
+// process (or onto THIS process), making a corpse lock look "held by a live
+// pid" — including "held by me" — which starves every waiter. Stamping a
+// random per-instance token alongside the pid lets reclaim/release tell our
+// current lock apart from a same-pid prior/other instance's leftover.
+const _OWNER_TOKEN = randomBytes(12).toString('hex');
+
 function sleepSync(ms) {
   try {
     const buf = new SharedArrayBuffer(4);
@@ -73,55 +81,11 @@ export function withFileLockSync(lockPath, fn, opts = {}) {
         contErr.cause = err;
         throw contErr;
       }
+      // Stale-lock reclaim (shared with the async variant). Covers a dead
+      // owner pid, a same-pid-but-foreign-token corpse from a reused pid, and
+      // a pidless/empty corpse lock; a live foreign holder is never stolen.
       try {
-        const st = statSync(lockPath);
-        // Dead-owner fast path: if the lock's recorded owner pid is gone,
-        // force-release immediately instead of waiting out staleMs. A crashed
-        // owner would otherwise hold the path until the 30s stale window,
-        // starving waiters past the 8s acquire timeout (the restart stall).
-        const ownerPidEarly = _readLockOwnerPid(lockPath);
-        const ownerDead = ownerPidEarly !== null && _pidIsDead(ownerPidEarly);
-        if (ownerDead || Date.now() - st.mtimeMs > staleMs) {
-          // Only steal a stale lock when we can prove the owner is
-          // gone. Reading the pid from the lock file and probing it
-          // with kill(pid, 0) protects a slow-but-live holder from
-          // having its lock yanked out from under it; the next
-          // process that acquires the lock would otherwise race
-          // against the original holder and clobber its write.
-          //
-          // Two-waiter stale-reclaim race: a pure rename "claim" is
-          // not enough. A waiter that proved pid D dead can stall;
-          // another waiter can then remove D and acquire a live lock,
-          // and the stalled waiter would rename that live lock away.
-          // Instead, serialize stale removal behind a tiny pid-stamped
-          // reclaim guard, then re-read the lock while the stale file
-          // is still present at lockPath. If the owner token no longer
-          // matches the pid we proved dead, treat the holder as live
-          // and back off. We never move or unlink a mismatched live-
-          // token file. Guard cleanup is only a best-effort unblocker:
-          // path unlink is not a portable unlink-if-token-still-matches
-          // primitive, so live-lock safety rests on the lockPath token
-          // reverify immediately before the lockPath unlink below.
-          const deadPid = ownerPidEarly;
-          if (ownerDead) {
-            const reclaim = _tryAcquireReclaimGuard(lockPath, staleMs);
-            if (reclaim !== null) {
-              let reclaimed = false;
-              try {
-                const currentSt = statSync(lockPath);
-                if (ownerDead || Date.now() - currentSt.mtimeMs > staleMs) {
-                  const currentPid = _readLockOwnerPid(lockPath);
-                  if (currentPid === deadPid && _pidIsDead(currentPid)) {
-                    try { unlinkSync(lockPath); reclaimed = true; } catch {}
-                  }
-                }
-              } finally {
-                _releaseReclaimGuard(reclaim);
-              }
-              if (reclaimed) continue;
-            }
-          }
-        }
+        if (_tryReclaimStaleLock(lockPath, staleMs)) continue;
       } catch {}
       if (Date.now() >= deadline) break;
       const base = DEFAULT_BACKOFFS_MS[Math.min(attempt, DEFAULT_BACKOFFS_MS.length - 1)];
@@ -130,10 +94,12 @@ export function withFileLockSync(lockPath, fn, opts = {}) {
       attempt += 1;
       continue;
     }
-    // Stamp our pid into the lock so stale-lock recovery and the
-    // finally-unlink below can verify ownership instead of blindly
-    // deleting whatever lock file happens to be at this path.
-    try { writeFileSync(fd, `${process.pid} ${Date.now()}\n`, 'utf8'); } catch {}
+    // Stamp pid + per-instance token so stale-lock recovery and the
+    // finally-unlink below can verify OUR identity instead of blindly
+    // deleting whatever lock file happens to be at this path. Format
+    // `<pid> <ts> <token>` is a superset of the old `<pid> <ts>`; a
+    // tokenless (old-format) lock is still read as pid-authoritative.
+    try { writeFileSync(fd, `${process.pid} ${Date.now()} ${_OWNER_TOKEN}\n`, 'utf8'); } catch {}
     // For secret-bearing critical sections, the lock file sits beside
     // the secret in the same (shared-home) directory; clamp it owner-only
     // too. Fail-closed: an unenforceable ACL aborts before fn() runs.
@@ -148,7 +114,7 @@ export function withFileLockSync(lockPath, fn, opts = {}) {
       // owner's lock and break mutual exclusion for whoever is
       // queued behind it.
       try {
-        if (_lockOwnedByPid(lockPath, process.pid)) unlinkSync(lockPath);
+        if (_lockOwnedBySelf(lockPath)) unlinkSync(lockPath);
       } catch {}
     }
   }
@@ -189,8 +155,109 @@ function _pidIsDead(pid) {
   }
 }
 
-function _lockOwnedByPid(lockPath, pid) {
-  return _readLockOwnerPid(lockPath) === pid;
+// Full owner identity: pid plus per-instance token. token is null for an
+// old-format (`<pid> <ts>`) lock, in which case callers fall back to
+// pid-authoritative handling so a still-running old-format holder is
+// respected. A read/parse error yields {pid:null, token:null} ("unknown").
+function _readLockOwner(lockPath) {
+  try {
+    const raw = readFileSync(lockPath, 'utf8');
+    const parts = String(raw).trim().split(/\s+/);
+    const pid = Number.parseInt(parts[0], 10);
+    return {
+      pid: Number.isFinite(pid) && pid > 0 ? pid : null,
+      token: parts.length >= 3 ? parts[2] : null,
+    };
+  } catch {
+    return { pid: null, token: null };
+  }
+}
+
+// Is this recorded owner a genuinely live holder?
+//  - pid null (empty/unparseable): not live (unknown owner).
+//  - pid === our pid: treated as LIVE. A foreign/absent token on our own
+//    pid is ambiguous — it may be a recycled-pid corpse, but it may also
+//    be a live sibling worker_thread (which shares process.pid yet owns a
+//    separate _OWNER_TOKEN module instance). We cannot distinguish them
+//    from the token alone, so we never call a same-pid owner instantly
+//    dead; the reclaim path gates a same-pid foreign-token steal behind
+//    stale mtime (see _ownerIsSelfForeign / _tryReclaimStaleLock) so a
+//    live sibling is never yanked, while a real corpse still frees once
+//    mtime goes stale.
+//  - foreign pid: probed with kill(pid, 0); ESRCH ⇒ dead, else live.
+function _ownerIsLive(owner) {
+  if (owner.pid === null) return false;
+  if (owner.pid === process.pid) return true;
+  try {
+    process.kill(owner.pid, 0);
+    return true;
+  } catch (err) {
+    return err?.code !== 'ESRCH';
+  }
+}
+
+// Our own pid but a foreign (present, non-matching) token: either a
+// recycled-pid corpse or a live sibling worker_thread. Reclaimable only
+// once mtime is past staleMs (handled by the pidless-style stale gate).
+function _ownerIsSelfForeign(owner) {
+  return owner.pid === process.pid
+    && owner.token !== null
+    && owner.token !== _OWNER_TOKEN;
+}
+
+// Release-time guard: unlink only if the lock still carries OUR identity
+// (our pid AND our token). Protects against deleting a lock another
+// instance stole+recreated, and against a same-pid sibling.
+function _lockOwnedBySelf(lockPath) {
+  const owner = _readLockOwner(lockPath);
+  if (owner.pid !== process.pid) return false;
+  return owner.token === null ? true : owner.token === _OWNER_TOKEN;
+}
+
+// Shared stale-lock reclaim used by BOTH withFileLockSync and withFileLock.
+// The whole operation is synchronous; the two variants differ only in how
+// they wait between attempts. Returns true iff lockPath was reclaimed.
+//
+// Reclaim decision table (owner = identity recorded in the lock file):
+//   owner pid DEAD (ESRCH / self-pid+foreign-token corpse) → reclaim
+//   owner pid NULL (empty/unparseable) AND mtime past staleMs → reclaim
+//   owner token MISMATCH on guarded re-read (new holder took over) → back off
+//   owner LIVE (foreign pid alive, or our own current token) → back off
+function _tryReclaimStaleLock(lockPath, staleMs) {
+  let st;
+  try { st = statSync(lockPath); } catch { return false; }
+  const owner = _readLockOwner(lockPath);
+  const stale = Date.now() - st.mtimeMs > staleMs;
+  const dead = owner.pid !== null && !_ownerIsLive(owner);
+  const pidless = owner.pid === null;
+  const selfForeign = _ownerIsSelfForeign(owner);
+  // A dead foreign owner reclaims immediately. A pidless corpse, or a
+  // same-pid foreign-token owner (which may still be a live sibling
+  // worker_thread), reclaims only once mtime is past staleMs; a live
+  // foreign holder is never stolen even after mtime goes stale.
+  if (!dead && !((pidless || selfForeign) && stale)) return false;
+  const reclaim = _tryAcquireReclaimGuard(lockPath, staleMs);
+  if (reclaim === null) return false;
+  try {
+    let cur;
+    try { cur = statSync(lockPath); } catch { return false; }
+    const curOwner = _readLockOwner(lockPath);
+    // Re-verify the SAME identity (pid AND token) we decided to reclaim is
+    // still present. A reused-pid new holder that grabbed the lock during
+    // the guard window has a different token and is not mistaken for the
+    // corpse — so we never yank a freshly-acquired live lock.
+    if (curOwner.pid !== owner.pid || curOwner.token !== owner.token) return false;
+    const curStale = Date.now() - cur.mtimeMs > staleMs;
+    const curDead = curOwner.pid !== null && !_ownerIsLive(curOwner);
+    const curPidless = curOwner.pid === null;
+    const curSelfForeign = _ownerIsSelfForeign(curOwner);
+    if (curDead || ((curPidless || curSelfForeign) && curStale)) {
+      try { unlinkSync(lockPath); return true; } catch { return false; }
+    }
+    return false;
+  } finally {
+    _releaseReclaimGuard(reclaim);
+  }
 }
 
 function _reclaimGuardIsUnreadableAndStale(guardPath, staleMs) {
@@ -211,8 +278,24 @@ function _reclaimGuardMatchesToken(guardPath, token) {
   }
 }
 
-function _unlinkReclaimGuardIfPidMatches(guardPath, pid) {
-  if (_readLockOwnerPid(guardPath) !== pid) return false;
+function _readGuardContent(guardPath) {
+  try { return readFileSync(guardPath, 'utf8'); } catch { return null; }
+}
+
+function _parseStampPid(raw) {
+  if (raw === null) return null;
+  const tok = String(raw).trim().split(/\s+/)[0];
+  const pid = Number.parseInt(tok, 10);
+  return Number.isFinite(pid) && pid > 0 ? pid : null;
+}
+
+// Unlink the guard only if its FULL content (pid ts token) is still the
+// exact content the stale/dead decision was made against. A regenerated
+// guard — even one whose pid was recycled to the same value (same-pid
+// ABA) — carries a fresh ts+token and therefore never matches, so a
+// fresh guard is never removed by a stale decision.
+function _unlinkReclaimGuardIfContentMatches(guardPath, content) {
+  if (_readGuardContent(guardPath) !== content) return false;
   try { unlinkSync(guardPath); return true; } catch { return false; }
 }
 
@@ -222,14 +305,25 @@ function _unlinkUnreadableStaleReclaimGuard(guardPath, staleMs) {
 }
 
 function _tryClearStaleReclaimGuard(guardPath, staleMs) {
-  const guardPid = _readLockOwnerPid(guardPath);
+  const guardContent = _readGuardContent(guardPath);
+  const guardPid = _parseStampPid(guardContent);
   if (guardPid !== null) {
-    // Re-read the guard immediately before unlinking so a regenerated
-    // guard with a different owner is not removed by a stale decision.
+    // Re-read the guard's full content immediately before unlinking so a
+    // regenerated guard (different owner OR same-pid ABA) is not removed
+    // by a stale decision.
     // This is still not a serialized primitive: correctness comes from
     // the lockPath owner-token reverify before unlinking lockPath, not
     // from making guard cleanup itself authoritative.
-    if (_pidIsDead(guardPid)) _unlinkReclaimGuardIfPidMatches(guardPath, guardPid);
+    // A guard whose pid was recycled onto a LIVE process would otherwise
+    // never clear, starving reclaim permanently; so also clear a guard
+    // past staleMs regardless of apparent pid-liveness. Safe because the
+    // guard is best-effort — the lockPath owner-token reverify still gates
+    // the actual lock unlink.
+    let guardStale = false;
+    try { guardStale = Date.now() - statSync(guardPath).mtimeMs > staleMs; } catch {}
+    if (_pidIsDead(guardPid) || guardStale) {
+      _unlinkReclaimGuardIfContentMatches(guardPath, guardContent);
+    }
     return;
   }
   // A crash between openSync('wx') and the pid write can leave an empty
@@ -294,29 +388,11 @@ export async function withFileLock(lockPath, fn, opts = {}) {
         contErr.cause = err;
         throw contErr;
       }
+      // Stale-lock reclaim (shared with the sync variant): dead owner pid,
+      // a same-pid-but-foreign-token corpse from a reused pid, or a
+      // pidless/empty corpse lock. A live foreign holder is never stolen.
       try {
-        const st = statSync(lockPath);
-        if (Date.now() - st.mtimeMs > staleMs) {
-          const deadPid = _readLockOwnerPid(lockPath);
-          if (deadPid !== null && _pidIsDead(deadPid)) {
-            const reclaim = _tryAcquireReclaimGuard(lockPath, staleMs);
-            if (reclaim !== null) {
-              let reclaimed = false;
-              try {
-                const currentSt = statSync(lockPath);
-                if (Date.now() - currentSt.mtimeMs > staleMs) {
-                  const currentPid = _readLockOwnerPid(lockPath);
-                  if (currentPid === deadPid && _pidIsDead(currentPid)) {
-                    try { unlinkSync(lockPath); reclaimed = true; } catch {}
-                  }
-                }
-              } finally {
-                _releaseReclaimGuard(reclaim);
-              }
-              if (reclaimed) continue;
-            }
-          }
-        }
+        if (_tryReclaimStaleLock(lockPath, staleMs)) continue;
       } catch {}
       if (Date.now() >= deadline) break;
       const base = DEFAULT_BACKOFFS_MS[Math.min(attempt, DEFAULT_BACKOFFS_MS.length - 1)];
@@ -325,14 +401,14 @@ export async function withFileLock(lockPath, fn, opts = {}) {
       attempt += 1;
       continue;
     }
-    try { writeFileSync(fd, `${process.pid} ${Date.now()}\n`, 'utf8'); } catch {}
+    try { writeFileSync(fd, `${process.pid} ${Date.now()} ${_OWNER_TOKEN}\n`, 'utf8'); } catch {}
     try {
       if (opts.secret === true) _enforceOwnerOnlyAclWin32(lockPath);
       return await fn();
     } finally {
       try { closeSync(fd); } catch {}
       try {
-        if (_lockOwnedByPid(lockPath, process.pid)) unlinkSync(lockPath);
+        if (_lockOwnedBySelf(lockPath)) unlinkSync(lockPath);
       } catch {}
     }
   }

package/src/runtime/shared/child-guardian.mjs

@@ -1,18 +1,70 @@
 'use strict';
 
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 
 function positiveInt(value) {
   const n = Number(value);
   return Number.isInteger(n) && n > 0 ? n : null;
 }
 
-function guardianScript({ parentPid, childPid, childGroupPid, platform, pollMs, orphanGraceMs, forceGraceMs }) {
+// On Windows a windowless, orphaned pwsh->cli chain keeps the immediate parent
+// PID alive after its terminal window is closed, so parent-liveness alone never
+// releases the worker. When the session is genuinely interactive (a TTY), the
+// controlling console window is owned by a host process (conhost.exe) that dies
+// with the terminal — monitoring that PID turns "terminal closed" into a fatal
+// orphan signal. Returns null for non-interactive/service/hidden-console starts
+// (no TTY, or no console window) so those are never treated as terminal loss.
+function detectControllingTerminalPid() {
+  if (process.platform !== 'win32') return null;
+  // Gate on a real TTY: a service/pipe/hidden launch has no controlling
+  // terminal, and probing one there would spawn a transient console whose host
+  // dies immediately — a false "terminal lost" that would kill a healthy worker.
+  const interactive = Boolean(
+    (process.stdin && process.stdin.isTTY) || (process.stdout && process.stdout.isTTY),
+  );
+  if (!interactive) return null;
+  try {
+    const systemRoot = process.env.SystemRoot || process.env.WINDIR || 'C:\\Windows';
+    const powershell = systemRoot + '\\System32\\WindowsPowerShell\\v1.0\\powershell.exe';
+    const script = [
+      'Add-Type @"',
+      'using System;',
+      'using System.Runtime.InteropServices;',
+      'public class MixdogTerm {',
+      '  [DllImport("kernel32.dll")] public static extern IntPtr GetConsoleWindow();',
+      '  [DllImport("user32.dll")] public static extern int GetWindowThreadProcessId(IntPtr h, out int pid);',
+      '}',
+      '"@',
+      '$h=[MixdogTerm]::GetConsoleWindow()',
+      'if($h -eq [IntPtr]::Zero){ Write-Output 0 } else { $p=0; [void][MixdogTerm]::GetWindowThreadProcessId($h,[ref]$p); Write-Output $p }',
+    ].join('\n');
+    // NO windowsHide: CREATE_NO_WINDOW gives the probe its own/absent console so
+    // GetConsoleWindow() returns 0 or a foreign hwnd. A plain console app spawned
+    // from a console-attached parent (this runs at the guardian start site, in the
+    // guarded parent) inherits that console with no window flash. Under Windows
+    // Terminal/ConPTY the owner is the tab's conhost (dies on tab close), which is
+    // exactly the pid we want to monitor.
+    const res = spawnSync(powershell, ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', script], {
+      timeout: 4000,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const pid = positiveInt(String((res && res.stdout) || '').trim());
+    // Ignore our own PID: that would make the guardian its own kill trigger.
+    if (pid && pid !== process.pid) return pid;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function guardianScript({ parentPid, childPid, childGroupPid, terminalPid, platform, pollMs, orphanGraceMs, forceGraceMs }) {
   return `
 const { spawnSync } = require('node:child_process');
 const parentPid = ${JSON.stringify(parentPid)};
 const childPid = ${JSON.stringify(childPid)};
 const childGroupPid = ${JSON.stringify(childGroupPid || childPid)};
+const terminalPid = ${JSON.stringify(terminalPid || 0)};
 const platform = ${JSON.stringify(platform)};
 const pollMs = ${JSON.stringify(pollMs)};
 const orphanGraceMs = ${JSON.stringify(orphanGraceMs)};
@@ -42,7 +94,12 @@ let killing = false;
 let orphanedAt = 0;
 const timer = setInterval(() => {
   if (!alive(childPid)) process.exit(0);
-  if (alive(parentPid)) {
+  // Orphaned when the parent PID dies OR (interactive only) the controlling
+  // terminal's console host dies — the latter catches a windowless pwsh->cli
+  // chain that outlives its closed terminal window. terminalPid is 0 for
+  // non-interactive starts, so those fall back to pure parent-liveness.
+  const terminalLost = terminalPid > 0 && !alive(terminalPid);
+  if (alive(parentPid) && !terminalLost) {
     orphanedAt = 0;
     return;
   }
@@ -77,6 +134,7 @@ export function startChildGuardian({
         parentPid: parent,
         childPid: child,
         childGroupPid: positiveInt(childGroupPid) || child,
+        terminalPid: detectControllingTerminalPid() || 0,
         platform: process.platform,
         pollMs: Math.max(100, Math.floor(Number(pollMs) || 750)),
         orphanGraceMs: Math.max(100, Math.floor(Number(orphanGraceMs) || Number(graceMs) || 3000)),

package/src/session-runtime/runtime-core.mjs

@@ -322,6 +322,13 @@ export async function createMixdogSessionRuntime({
 } = {}) {
   bootProfile('session-runtime:start', { provider, model, toolMode, cwd });
   let remoteEnabled = remote === true;
+  // Transient marker: an AUTO start (config/delayed autoStart) has forked the
+  // worker to ATTEMPT a claim-if-vacant but has NOT asserted remote for this
+  // session yet. remoteEnabled flips only if the worker reports it acquired the
+  // seat (the 'acquired' notification). Lets the deferred start chain proceed
+  // past its remoteEnabled guards without prematurely showing this session as
+  // remote (single-holder: a live owner must not be stolen by autoStart).
+  let remoteClaimPending = false;
   // Remote-mode transcript writer (Discord outbound). Lazily created per
   // session.id + cwd inside ask(); only active while remoteEnabled.
   let _transcriptWriter = null;
@@ -882,6 +889,8 @@ export async function createMixdogSessionRuntime({
       // newer remote session. Drop remote mode entirely on this session (no
       // handover, no retry) and tell UI listeners so the indicator updates.
       if (msg?.method === 'notifications/mixdog/remote') {
+        // Any acquire/supersede verdict resolves an in-flight auto claim attempt.
+        remoteClaimPending = false;
         if (msg?.params?.state === 'superseded' && remoteEnabled) {
           stopRemote('superseded-by-newer-remote-session');
           emitRemoteStateChange(false, 'superseded');
@@ -1521,8 +1530,23 @@ export async function createMixdogSessionRuntime({
   // rebinds output forwarding to this session, even when the worker is
   // already running (e.g. `/remote` re-issued after another session took the
   // seat, or to re-pin forwarding onto the current transcript).
-  function startRemote() {
-    remoteEnabled = true;
+  function startRemote(options = {}) {
+    const intent = options?.intent === 'auto' ? 'auto' : 'explicit';
+    // Claim intent reaches the worker's boot claim via MIXDOG_REMOTE_INTENT
+    // (last-wins for explicit, claim-if-vacant for auto). It is set transiently
+    // around the worker fork below (see invokeChannelStart) and restored right
+    // after — NOT here on the shared process.env — so unrelated children forked
+    // during the boot window never inherit a stale intent.
+    if (intent === 'auto') {
+      // Auto-start (config/delayed): do NOT flip this session to remote up
+      // front. Boot the worker to ATTEMPT a claim-if-vacant; remoteEnabled is
+      // set only when the worker reports it actually acquired the seat (the
+      // 'acquired' notification). A live owner already holding the seat makes
+      // the worker back off silently and this session stays non-remote.
+      remoteClaimPending = true;
+    } else {
+      remoteEnabled = true;
+    }
     // Boot the memory daemon eagerly. The channels worker forwards
     // transcript ingests/entries to the memory HTTP service, whose port is
     // published to active-instance.json by getMemoryModule().init(). Without
@@ -1616,23 +1640,46 @@ export async function createMixdogSessionRuntime({
       // Re-check after the awaits above: stopRemote()/superseded or runtime
       // close may have landed mid-chain — do not boot/claim for a session
       // that already turned remote off.
-      if (!remoteEnabled || closeRequested) return;
-      await invokeChannelStart();
-      if (!remoteEnabled || closeRequested) return;
-      // Unconditional claim + forwarder rebind. A freshly-forked worker
-      // already claims in its own start(), so this is idempotent there; the
-      // already-running case is where it matters (last-wins seat overwrite +
-      // transcript rebind onto this session).
-      await channels.execute('activate_channel_bridge', { active: true });
-    })().catch((error) => bootProfile('channels:claim-failed', { error: error?.message || String(error) }));
+      if ((!remoteEnabled && !remoteClaimPending) || closeRequested) { remoteClaimPending = false; return; }
+      // Set the fork-inherited intent immediately before the worker fork (the
+      // fork reads process.env synchronously inside invokeChannelStart) and
+      // restore the prior value the instant it resolves, so the pollution
+      // window is just this fork rather than the whole boot chain.
+      const _prevIntent = process.env.MIXDOG_REMOTE_INTENT;
+      try {
+        process.env.MIXDOG_REMOTE_INTENT = intent;
+        await invokeChannelStart();
+      } finally {
+        if (_prevIntent === undefined) delete process.env.MIXDOG_REMOTE_INTENT;
+        else process.env.MIXDOG_REMOTE_INTENT = _prevIntent;
+      }
+      if ((!remoteEnabled && !remoteClaimPending) || closeRequested) { remoteClaimPending = false; return; }
+      // Explicit start: unconditional claim + forwarder rebind (last-wins seat
+      // overwrite + transcript rebind onto this session). AUTO start SKIPS this
+      // — the freshly-forked worker already ran its claim-if-vacant boot claim,
+      // and forcing activate here would steal a live owner that autoStart is
+      // meant to yield to. The worker's acquire notification drives remote ON.
+      if (intent !== 'auto') {
+        await channels.execute('activate_channel_bridge', { active: true });
+      }
+      // Claim attempt dispatched; the worker's acquire/supersede notification
+      // now owns the remoteEnabled transition. Drop the transient marker.
+      remoteClaimPending = false;
+    })().catch((error) => { remoteClaimPending = false; bootProfile('channels:claim-failed', { error: error?.message || String(error) }); });
     return true;
   }
 
   function stopRemote(reason) {
     remoteEnabled = false;
+    // A pending auto-claim is abandoned by an explicit stop/supersede.
+    remoteClaimPending = false;
     // Cancel any pending deferred start so it can't fire after remote is off.
     if (prewarmTimers.channelStartTimer) { clearTimeout(prewarmTimers.channelStartTimer); prewarmTimers.channelStartTimer = null; }
-    channels.stop(reason || 'remote-disabled', { waitForExit: false }).catch(() => {});
+    // Route /remote-off and supersede through a WAITING stop: the runtime keeps
+    // running, so we don't block on it (no await), but the waiting path runs the
+    // full SIGTERM -> taskkill /T /F escalation ladder to guarantee the worker
+    // dies rather than lingering as a zombie holding the bridge seat.
+    channels.stop(reason || 'remote-disabled').catch(() => {});
     return true;
   }
 
@@ -1685,11 +1732,18 @@ export async function createMixdogSessionRuntime({
   // cfgMod.loadConfig returns — read it via the shared whole-file reader.
   // `config?.remote?.autoStart` is kept for back-compat with agent-section
   // placement.
+  // `remote` (from `mixdog --remote`) is EXPLICIT force-takeover. Config
+  // `remote.autoStart` is AUTO: it must claim the seat ONLY if no live owner
+  // exists (claim-if-vacant) and back off silently otherwise — so it does NOT
+  // set remoteEnabled up front (that would assert remote before the claim is
+  // known to have won). Track it as a separate deferred auto request; the
+  // worker's acquire notification flips remoteEnabled if/when it wins the seat.
+  let remoteAutoStartRequested = false;
   if (!remoteEnabled) {
     try {
       if (config?.remote?.autoStart === true
         || sharedCfgMod?.readSection?.('remote')?.autoStart === true) {
-        remoteEnabled = true;
+        remoteAutoStartRequested = true;
       }
     } catch { /* unreadable config never blocks boot */ }
   }
@@ -1702,13 +1756,17 @@ export async function createMixdogSessionRuntime({
   // early /remote (startRemote clears it), stopRemote(), and close() all
   // cancel it through the existing clearTimeout paths. Runtime /remote calls
   // still start immediately (user-initiated, UI already painted).
-  if (remoteEnabled) {
+  if (remoteEnabled || remoteAutoStartRequested) {
+    const remoteStartIntent = remoteEnabled ? 'explicit' : 'auto';
     const remoteAutoStartDelayMs = envDelayMs('MIXDOG_REMOTE_AUTOSTART_DELAY_MS', 1_500, { min: 0, max: 60_000 });
-    bootProfile('channels:autostart-deferred', { delayMs: remoteAutoStartDelayMs });
+    bootProfile('channels:autostart-deferred', { delayMs: remoteAutoStartDelayMs, intent: remoteStartIntent });
     prewarmTimers.channelStartTimer = setTimeout(() => {
       prewarmTimers.channelStartTimer = null;
-      if (closeRequested || !remoteEnabled) return;
-      startRemote();
+      if (closeRequested) return;
+      // Explicit: a /remote-off before the timer clears remoteEnabled — skip.
+      // Auto: always attempt (claim-if-vacant is safe when a live owner exists).
+      if (remoteStartIntent === 'explicit' && !remoteEnabled) return;
+      startRemote({ intent: remoteStartIntent });
     }, remoteAutoStartDelayMs);
     prewarmTimers.channelStartTimer.unref?.();
   }