@dmsdc-ai/aigentry-telepty 0.3.5 → 0.4.1

package/CHANGELOG.md

@@ -2,6 +2,102 @@
 
 All notable changes to `@dmsdc-ai/aigentry-telepty` are documented here.
 
+## [0.4.1] - 2026-05-17
+
+### Fixed
+
+- **#25** — Windows PATHEXT resolution for `telepty allow`. npm-global CLIs
+  (`claude`, `codex`, `gemini`) now spawn correctly with bare names on
+  Windows. Previously `telepty allow … claude` failed with
+  `Cannot create process, error code: 2` (ERROR_FILE_NOT_FOUND) because
+  node-pty's `CreateProcessW` does not walk `%PATHEXT%` the way `cmd.exe`
+  does, so the npm-global `claude.cmd` shim was unreachable from the bare
+  name. New: `src/win-resolve-executable.js` resolver (Windows-only branch
+  walks `PATH` × `PATHEXT`; POSIX no-op) + 14 unit tests. macOS/Linux
+  behavior unchanged.
+
+### Notes
+
+- **Snyk SAST scan on changed files** — `src/win-resolve-executable.js`
+  + `test/win-resolve-executable.test.js` = **0 findings** (At-Inception
+  clean). `cli.js` shows **5 pre-existing findings** (2 Medium Command
+  Injection at `execSync` L469 + `pty.spawn` L1075, 3 Low Path Traversal
+  at L2287/L2289/L2598) verified identical fingerprint vs HEAD~1 — out
+  of #25 surgical scope. Tracked in **dmsdc-ai/aigentry-telepty#26** for
+  follow-up PR.
+
+## [0.4.0] — 2026-05-15
+
+### Added — Phase 1 sidecar supervisor spike (M1–M5)
+
+Out-of-process Rust supervisor (`crates/telepty-supervisor-{core,bin}`)
+incubating the future spawn/kill/IPC backend for `daemon.js`. Five
+milestones complete; **incubating only — not on the request path** in
+0.4.0. Daemon (`daemon.js`) and CLI (`cli.js`) routing is unchanged.
+
+- **M1** — spawn + observe (commit `07cd2e7`).
+- **M2** — graceful + forced kill gate, manifest cleanup invariant A8
+  (commit `ec00412`).
+- **M3** — IPC + wire contract conformance, NDJSON UDS frames + golden
+  fixtures (commit `76cde35`).
+- **M4** — cross-OS POSIX parity + reproducible RSS measurement, GitHub
+  Actions matrix (`.github/workflows/phase1-spike-ci.yml`); RSS PASS at
+  2.9–3.0 MiB / supervisor on macOS arm64 (commit `eb04c73`).
+- **M5** — manual integration bridge (`scripts/bridge-phase1.js`, 194
+  LOC Node stdlib only) — four parity scenarios A/B/C/D, exit 0 iff all
+  PASS; one-line Rust correctness fix (emit `shutdown_drain` before IPC
+  shutdown so connected clients receive the frame) (commit `be091e0`).
+
+Phase 1 LOC ceiling 1500 honored (Rust src/ tokei = 1240, 260 LOC
+headroom unused). Test suite: 23/23 (lib unit 12 + wire_golden 6 +
+ipc_protocol 5). Spec: `docs/specs/2026-05-10-supervisor-c3-kill-gate-spec.md`.
+Plan: `docs/plans/2026-05-12-phase1-sidecar-spike-plan.md`.
+
+### Fixed
+
+- **#18** — Bootstrap inject queue race. Welcome-banner bypass via
+  positive-override `is_ready` so queued injects flush in the correct
+  order without colliding with the banner (commit `744ad6a`).
+- **#16** — REPORT-based idle status detection. Replaces heuristic
+  prompt-symbol detection with explicit REPORT-frame anchoring
+  (commit `3ed1e83`).
+
+### Build
+
+- `package.json` — added `files` whitelist (22 entries) to constrain
+  npm-published surface to actual runtime distribution. Tarball
+  reduction: 228 MB → 123 kB (1850×). The Rust spike artifacts
+  (`target/`, `crates/`, `Cargo.lock/Cargo.toml`, `rust-toolchain.toml`)
+  ship in git but **not** to npm (commit `a0baf84`).
+
+### Docs
+
+- MD audit wave-2 fix: `CLAUDE.md` converted to `@AGENTS.md` stub
+  (101 → 27 lines), `AGENTS.md` gained Session Environment section
+  (`$TELEPTY_SESSION_ID`, `$TELEPTY_AVAILABLE`) and disclosed
+  cross-repo ADR location for `2026-05-05-telepty-devkit-boundary §6.2.1`.
+  Score delta `AGENTS.md` 80 → 87, `CLAUDE.md` 66 → 87 (commit `74a6374`,
+  full report `docs/reports/2026-05-14-md-audit.md`).
+
+### Notes
+
+- **Snyk SAST deferred for this release** — see follow-up task #130.
+  Waiver basis (Rule 32-A track B):
+  - M1–M5 spike code is Rust and is **excluded from the npm tarball** by
+    the new `files` whitelist — first-party code shipped to consumers is
+    JS only.
+  - The shipped JS files are unchanged or only minimally changed since
+    `0.3.5` (cli.js +51 / daemon.js +360 / src/prompt-symbol-registry.js
+    +44 / new session-state.js — additive, no breaks per Phase 1 audit).
+  - Dependency-side coverage exists via `npm audit` (10 pre-existing
+    vulns documented; not introduced by this release).
+  - Per CLAUDE.md user-instruction "Snyk At Inception" scope = *new
+    first-party code shipped* — 0 net-new shipped JS code in this
+    release, so the at-inception rule does not bind here. Follow-up
+    task #130 will land the standing SAST gate as a release-script
+    primitive (so future releases scan automatically without per-run
+    auth steps).
+
 ## [0.3.5] — 2026-05-05
 
 ### Added — `telepty init --print-snippet` (Issue #8)

package/cli.js

@@ -17,9 +17,11 @@ const { getRuntimeInfo } = require('./runtime-info');
 const { formatHostLabel, groupSessionsByHost, pickSessionTarget } = require('./session-routing');
 const { buildSharedContextPrompt, createSharedContextDescriptor, ensureSharedContextFile } = require('./shared-context');
 const { runInteractiveSkillInstaller } = require('./skill-installer');
+const { resolveWindowsExecutable } = require('./src/win-resolve-executable');
 const crossMachine = require('./cross-machine');
 const { parseHostSpec, buildDaemonUrl, buildDaemonWsUrl } = require('./host-spec');
 const { FileMailbox } = require('./src/mailbox/index');
+const readyRegistry = require('./src/prompt-symbol-registry');
 const args = process.argv.slice(2);
 let pendingTerminalInputError = null;
 let simulatedPromptErrorInjected = false;
@@ -1067,7 +1069,10 @@ async function main() {
     }
 
     function spawnChild() {
-      child = pty.spawn(command, cmdArgs, {
+      // Windows: walk %PATHEXT% so bare names (`claude`, `codex`, `gemini`)
+      // resolve to their npm-global `.cmd`/`.ps1` shims. POSIX: no-op. (#25)
+      const resolvedCommand = resolveWindowsExecutable(command, process.env);
+      child = pty.spawn(resolvedCommand, cmdArgs, {
         name: 'xterm-256color',
         cols: process.stdout.columns || 80,
         rows: process.stdout.rows || 30,
@@ -1080,15 +1085,14 @@ async function main() {
 
     spawnChild();
 
-    // Prompt-ready detection for safe inject delivery
-    const PROMPT_PATTERNS = {
-      claude: /[❯>]\s*$/,
-      gemini: /[❯>]\s*$/,
-      codex: /[❯>]\s*$/,
-    };
-    const cmdBase = path.basename(command).replace(/\..*$/, '');
-    const promptPattern = PROMPT_PATTERNS[cmdBase] || /[❯>$#%]\s*$/;
+    // Prompt-ready detection for safe inject delivery.
+    // Known AI CLIs use the centralized geometry-aware registry; generic
+    // commands keep the permissive legacy prompt regex for compatibility.
+    const knownAiCli = readyRegistry.isKnownAiCli(command);
+    const promptPattern = /[❯>$#%]\s*$/;
     let promptReady = false;  // wait for CLI prompt before accepting inject
+    let firstReadyObserved = false;
+    let outputTail = '';
     let lastUserInputTime = 0;  // timestamp of last user keystroke
     const IDLE_THRESHOLD = 2000; // ms after last user input to consider idle
 
@@ -1128,6 +1132,14 @@ async function main() {
       return promptReady && (Date.now() - lastUserInputTime > IDLE_THRESHOLD);
     }
 
+    function observePromptReady(data) {
+      if (knownAiCli) {
+        outputTail = (outputTail + data).slice(-20000);
+        return !!readyRegistry.detectOutput(command, outputTail).found;
+      }
+      return promptPattern.test(data);
+    }
+
     let queueFlushTimer = null;
     let idleCheckTimer = null;
 
@@ -1164,8 +1176,9 @@ async function main() {
           flushBridgeMailbox();
         }
       }, 500);
-      // Safety: flush after 5s regardless (prevent stuck queue when prompt not detected)
-      if (!queueFlushTimer) {
+      // Safety fallback is compatibility-only during known AI CLI bootstrap:
+      // first dispatch must wait for a strong ready signal.
+      if ((!knownAiCli || firstReadyObserved) && !queueFlushTimer) {
         queueFlushTimer = setTimeout(() => {
           queueFlushTimer = null;
           if (bridgePendingCount > 0) {
@@ -1238,10 +1251,16 @@ async function main() {
 
               const isCr = chunk === '\r';
               if (isCr && bridgePendingCount > 0) {
-                // CR with pending queued text — queue CR too and flush immediately.
+                // CR with pending queued text — queue CR too and wait for the
+                // same readiness gate as the text. This preserves order during
+                // bootstrap and busy-session delivery.
                 enqueueBridgeMessage(chunk);
-                if (queueFlushTimer) { clearTimeout(queueFlushTimer); queueFlushTimer = null; }
-                flushBridgeMailbox();
+                if (isIdle()) {
+                  if (queueFlushTimer) { clearTimeout(queueFlushTimer); queueFlushTimer = null; }
+                  flushBridgeMailbox();
+                } else {
+                  scheduleIdleFlush();
+                }
               } else if (isCr) {
                 // CR always written immediately — never idle-gated.
                 child.write(chunk);
@@ -1353,8 +1372,9 @@ async function main() {
         daemonWs.send(JSON.stringify({ type: 'output', data }));
       }
       // Detect prompt in output to enable inject delivery
-      if (promptPattern.test(data)) {
+      if (observePromptReady(data)) {
         promptReady = true;
+        firstReadyObserved = true;
         flushBridgeMailbox();
         // Notify daemon that CLI is ready for inject
         if (!readyNotified && wsReady && daemonWs.readyState === 1) {
@@ -1383,6 +1403,10 @@ async function main() {
           setTimeout(() => {
             try {
               spawnChild();
+              promptReady = false;
+              firstReadyObserved = false;
+              readyNotified = false;
+              outputTail = '';
               // Re-attach output relay, prompt detection, and exit handler
               child.onData((data) => {
                 const rewritten = rewriteTitleSequences(data);
@@ -1390,8 +1414,9 @@ async function main() {
                 if (wsReady && daemonWs.readyState === 1) {
                   daemonWs.send(JSON.stringify({ type: 'output', data }));
                 }
-                if (promptPattern.test(data)) {
+                if (observePromptReady(data)) {
                   promptReady = true;
+                  firstReadyObserved = true;
                   flushBridgeMailbox();
                   if (wsReady && daemonWs.readyState === 1) {
                     daemonWs.send(JSON.stringify({ type: 'ready' }));

package/daemon.js

@@ -15,6 +15,7 @@ const { UnixSocketNotifier } = require('./src/mailbox/notifier');
 const { SessionStateManager, STATE_DISPLAY, stripAnsi: stripAnsiState } = require('./session-state');
 const { classifyReportPrompt, buildAutoSummary } = require('./src/report-enforcement');
 const submitGate = require('./src/submit-gate');
+const readyRegistry = require('./src/prompt-symbol-registry');
 
 const config = getConfig();
 const EXPECTED_TOKEN = config.authToken;
@@ -26,6 +27,8 @@ const SESSION_STALE_SECONDS = Math.max(1, Number(process.env.TELEPTY_SESSION_STA
 const SESSION_CLEANUP_SECONDS = Math.max(SESSION_STALE_SECONDS, Number(process.env.TELEPTY_SESSION_CLEANUP_SECONDS || 300));
 const DELIVERY_TIMEOUT_MS = Math.max(100, Number(process.env.TELEPTY_DELIVERY_TIMEOUT_MS || 5000));
 const HEALTH_POLL_MS = Math.max(100, Number(process.env.TELEPTY_HEALTH_POLL_MS || 10000));
+const BOOTSTRAP_READY_TIMEOUT_MS = Math.max(500, Number(process.env.TELEPTY_BOOTSTRAP_READY_TIMEOUT_MS || 30000));
+const WRAPPED_SUBMIT_DELAY_MS = 500;
 
 // Session state machine manager — auto-detects session state from PTY output
 const sessionStateManager = new SessionStateManager({
@@ -354,6 +357,292 @@ function getSessionHealthReason(session, healthStatus) {
   return session.ptyProcess && !session.ptyProcess.killed ? 'PTY_RUNNING' : 'PTY_EXITED';
 }
 
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isBootstrapGatedSession(session) {
+  return !!(session && session.type === 'wrapped' && readyRegistry.isKnownAiCli(session.command));
+}
+
+function initializeBootstrapState(session) {
+  if (!session) return session;
+  if (!Array.isArray(session.bootstrapQueue)) {
+    session.bootstrapQueue = [];
+  }
+  session.bootstrapDraining = session.bootstrapDraining === true;
+  session.bootstrapDrainPromise = session.bootstrapDrainPromise || null;
+  session.bootstrapPromptPoll = session.bootstrapPromptPoll || null;
+
+  if (isBootstrapGatedSession(session)) {
+    session.bootstrapReady = session.bootstrapReady === true;
+    session.bootstrapReadyAt = session.bootstrapReadyAt || null;
+    session.bootstrapReadyReason = session.bootstrapReadyReason || null;
+    session.ready = session.bootstrapReady === true;
+  } else {
+    session.bootstrapReady = true;
+    session.bootstrapReadyAt = session.bootstrapReadyAt || new Date().toISOString();
+    session.bootstrapReadyReason = session.bootstrapReadyReason || 'generic_command_compat';
+    session.ready = true;
+  }
+  return session;
+}
+
+function isBootstrapReady(session) {
+  return !isBootstrapGatedSession(session) || session.bootstrapReady === true;
+}
+
+function buildBootstrapBlock(session) {
+  return {
+    gated: isBootstrapGatedSession(session),
+    ready: isBootstrapReady(session),
+    ready_at: session.bootstrapReadyAt || null,
+    reason: session.bootstrapReadyReason || null,
+    queued: Array.isArray(session.bootstrapQueue) ? session.bootstrapQueue.length : 0,
+    draining: session.bootstrapDraining === true
+  };
+}
+
+function shouldQueueBootstrapOperation(session) {
+  return isBootstrapGatedSession(session) && !isBootstrapReady(session);
+}
+
+function hasBootstrapBacklog(session) {
+  return !!(session && Array.isArray(session.bootstrapQueue) && session.bootstrapQueue.length > 0);
+}
+
+function emitBootstrapEvent(eventType, sessionId, session, extra = {}) {
+  broadcastSessionEvent(eventType, sessionId, session, {
+    extra: {
+      bootstrap: buildBootstrapBlock(session),
+      ...extra
+    }
+  });
+}
+
+function enqueueBootstrapOperation(sessionId, session, operation) {
+  initializeBootstrapState(session);
+  const op = {
+    op_id: crypto.randomUUID(),
+    queued_at: new Date().toISOString(),
+    ...operation
+  };
+
+  if (op.type === 'submit') {
+    op.promise = new Promise((resolve) => {
+      op.resolve = resolve;
+    });
+  }
+
+  session.bootstrapQueue.push(op);
+  emitBootstrapEvent('bootstrap_queue_queued', sessionId, session, {
+    op_id: op.op_id,
+    operation: op.type,
+    depth: session.bootstrapQueue.length
+  });
+  scheduleBootstrapPromptPoll(sessionId, session);
+  return op;
+}
+
+function resolveBootstrapSubmit(op, result) {
+  if (op && typeof op.resolve === 'function') {
+    op.resolve(result);
+    op.resolve = null;
+  }
+}
+
+function bootstrapQueuedResponse(op, extra = {}) {
+  return {
+    success: true,
+    strategy: 'bootstrap_queue',
+    queued: true,
+    bootstrap_queued: true,
+    bootstrap_op_id: op.op_id,
+    ...extra
+  };
+}
+
+async function executeBootstrapInject(sessionId, session, op) {
+  const prompt = typeof op.prompt === 'string' ? op.prompt : '';
+  const textResult = await writeDataToSession(sessionId, session, prompt);
+  if (!textResult.success) return textResult;
+
+  if (!op.noEnter) {
+    await sleep(WRAPPED_SUBMIT_DELAY_MS);
+    const submitResult = await writeDataToSession(sessionId, session, '\r');
+    if (!submitResult.success) return submitResult;
+  }
+
+  session.lastActivityAt = new Date().toISOString();
+  return {
+    success: true,
+    strategy: 'bootstrap_direct',
+    submit: op.noEnter ? 'skipped' : 'sent'
+  };
+}
+
+async function executeBootstrapSubmit(sessionId, session, op) {
+  const strategy = terminalLevelSubmit(sessionId, session);
+  if (!strategy) {
+    return {
+      status: 503,
+      body: {
+        error: 'Submit failed via all strategies (kitty/cmux/pty)',
+        strategy: 'none',
+        attempts: 0,
+        gated: false,
+        bootstrap_queued: true
+      }
+    };
+  }
+  return {
+    status: 200,
+    body: {
+      success: true,
+      strategy,
+      attempts: 1,
+      gated: false,
+      verify: null,
+      bootstrap_queued: true
+    }
+  };
+}
+
+async function drainBootstrapQueue(sessionId, session) {
+  if (!session || session.bootstrapDraining) {
+    return session ? session.bootstrapDrainPromise : null;
+  }
+  if (!isBootstrapReady(session)) {
+    return null;
+  }
+
+  session.bootstrapDraining = true;
+  session.bootstrapDrainPromise = (async () => {
+    while (hasBootstrapBacklog(session)) {
+      const op = session.bootstrapQueue.shift();
+      try {
+        if (op.cancelled) {
+          continue;
+        }
+        if (op.type === 'inject') {
+          const result = await executeBootstrapInject(sessionId, session, op);
+          if (!result.success) {
+            emitBootstrapEvent('bootstrap_queue_failed', sessionId, session, {
+              op_id: op.op_id,
+              operation: op.type,
+              code: result.code || 'DELIVERY_FAILED',
+              error: result.error || 'bootstrap delivery failed'
+            });
+          }
+        } else if (op.type === 'submit') {
+          const result = await executeBootstrapSubmit(sessionId, session, op);
+          resolveBootstrapSubmit(op, result);
+          if (result.status >= 400) {
+            emitBootstrapEvent('bootstrap_queue_failed', sessionId, session, {
+              op_id: op.op_id,
+              operation: op.type,
+              code: result.body.code || 'SUBMIT_FAILED',
+              error: result.body.error || 'bootstrap submit failed'
+            });
+          }
+        }
+      } catch (error) {
+        if (op.type === 'submit') {
+          resolveBootstrapSubmit(op, {
+            status: 500,
+            body: {
+              error: error.message || 'bootstrap submit failed',
+              strategy: 'none',
+              attempts: 0,
+              gated: false,
+              bootstrap_queued: true
+            }
+          });
+        }
+        emitBootstrapEvent('bootstrap_queue_failed', sessionId, session, {
+          op_id: op.op_id,
+          operation: op.type,
+          code: 'BOOTSTRAP_DRAIN_FAILED',
+          error: error.message || 'bootstrap drain failed'
+        });
+      }
+    }
+
+    emitBootstrapEvent('bootstrap_queue_drained', sessionId, session);
+  })().finally(() => {
+    session.bootstrapDraining = false;
+    session.bootstrapDrainPromise = null;
+  });
+
+  return session.bootstrapDrainPromise;
+}
+
+function markBootstrapReady(sessionId, session, reason) {
+  if (!session) return false;
+  initializeBootstrapState(session);
+  if (!isBootstrapGatedSession(session)) {
+    return false;
+  }
+  if (session.bootstrapReady === true) {
+    return false;
+  }
+
+  session.bootstrapReady = true;
+  session.bootstrapReadyAt = new Date().toISOString();
+  session.bootstrapReadyReason = reason || 'ready';
+  session.ready = true;
+  emitBootstrapEvent('bootstrap_ready', sessionId, session, { reason: session.bootstrapReadyReason });
+  drainBootstrapQueue(sessionId, session);
+  return true;
+}
+
+function scheduleBootstrapPromptPoll(sessionId, session) {
+  if (!session || !isBootstrapGatedSession(session) || isBootstrapReady(session)) return;
+  if (session.bootstrapPromptPoll || session.backend !== 'cmux' || !session.cmuxWorkspaceId) return;
+  if (!isOpenWebSocket(session.ownerWs)) return;
+
+  session.bootstrapPromptPoll = submitGate.awaitPromptSymbol(session, {
+    timeoutMs: BOOTSTRAP_READY_TIMEOUT_MS
+  }).then((result) => {
+    session.bootstrapPromptPoll = null;
+    if (result && result.ready && isOpenWebSocket(session.ownerWs)) {
+      markBootstrapReady(sessionId, session, 'cmux_prompt_symbol');
+    } else if (result && result.reason) {
+      emitBootstrapEvent('bootstrap_ready_timeout', sessionId, session, {
+        reason: result.reason,
+        waited_ms: result.waited_ms || 0
+      });
+    }
+  }).catch((error) => {
+    session.bootstrapPromptPoll = null;
+    emitBootstrapEvent('bootstrap_ready_timeout', sessionId, session, {
+      reason: 'prompt_symbol_error',
+      error: error.message || String(error)
+    });
+  });
+}
+
+async function waitForBootstrapSubmit(op, session, timeoutMs) {
+  const timeout = sleep(timeoutMs).then(() => {
+    op.cancelled = true;
+    return {
+      status: 504,
+      body: {
+        error: 'Submit bootstrap-timeout — target CLI did not become ready',
+        reason: 'bootstrap_not_ready',
+        last_state: sessionStateManager.getState(session.id)?.state || null,
+        strategy: 'none',
+        attempts: 0,
+        gated: true,
+        bootstrap_queued: true,
+        bootstrap_op_id: op.op_id,
+        bootstrap: buildBootstrapBlock(session)
+      }
+    };
+  });
+  return Promise.race([op.promise, timeout]);
+}
+
 function buildSessionTransportBlock(session, options = {}) {
   if (!session) {
     return null;
@@ -380,7 +669,8 @@ function buildSessionTransportBlock(session, options = {}) {
     last_disconnected_at: session.lastDisconnectedAt || null,
     last_inject_from: session.lastInjectFrom || null,
     last_reply_to: session.lastInjectReplyTo || null,
-    last_thread_id: session.lastThreadId || null
+    last_thread_id: session.lastThreadId || null,
+    bootstrap: buildBootstrapBlock(session)
   };
 }
 
@@ -645,6 +935,28 @@ function terminalLevelSubmit(id, session) {
 
 async function deliverInjectionToSession(id, session, prompt, options = {}) {
   const now = Date.now();
+  if (!options.bypassBootstrapQueue && shouldQueueBootstrapOperation(session)) {
+    const healthStatus = getSessionHealthStatus(session, { nowMs: now });
+    if (healthStatus === 'STALE') {
+      return { success: false, httpStatus: 410, code: 'STALE', error: 'Session is stale and awaiting cleanup.' };
+    }
+    const op = enqueueBootstrapOperation(id, session, {
+      type: 'inject',
+      prompt,
+      noEnter: !!options.noEnter,
+      options: {
+        source: options.source || 'inject',
+        from: options.from || 'daemon'
+      }
+    });
+    session.lastActivityAt = new Date(now).toISOString();
+    return bootstrapQueuedResponse(op, {
+      msg_id: op.op_id,
+      pending: session.bootstrapQueue.length,
+      submit: options.noEnter ? 'skipped' : 'queued'
+    });
+  }
+
   const injectFailure = getInjectFailure(session, { nowMs: now });
   if (injectFailure) {
     return { success: false, ...injectFailure };
@@ -834,6 +1146,7 @@ for (const [id, meta] of Object.entries(_persisted)) {
       lastStateReportAt: meta.lastStateReportAt || null,
       stateReport: meta.stateReport || null,
       clients: new Set(), isClosing: false, outputRing: [], ready: true,     };
+    initializeBootstrapState(sessions[id]);
     console.log(`[PERSIST] Restored session ${id} (awaiting reconnect)`);
   }
 }
@@ -1020,6 +1333,7 @@ app.post('/api/sessions/register', (req, res) => {
       existing.ready = true;
       markSessionConnected(existing);
     }
+    initializeBootstrapState(existing);
     console.log(`[REGISTER] Re-registered session ${session_id} (type: ${existing.type}, updated metadata)`);
     return res.status(200).json({ session_id, type: existing.type, command: existing.command, cwd: existing.cwd, reregistered: true });
   }
@@ -1049,8 +1363,9 @@ app.post('/api/sessions/register', (req, res) => {
     clients: new Set(),
     isClosing: false,
     outputRing: [],
-    ready: true,  // all sessions are injectable once registered (#150)
-      };
+    ready: true,  // unknown commands remain injectable once registered (#150)
+  };
+  initializeBootstrapState(sessionRecord);
   // Check for existing session with same base alias and emit replaced event
   const baseAlias = session_id.replace(/-\d+$/, '');
   const replaced = Object.keys(sessions).find(id => {
@@ -1521,6 +1836,18 @@ app.post('/api/sessions/:id/submit', async (req, res) => {
 
   console.log(`[SUBMIT] Session ${id} (${session.command})${retries > 0 ? `, retries: ${retries}, pre_delay: ${preDelayMs}ms` : ''}${gateOff ? ' [gate=off]' : ''}`);
 
+  if (isBootstrapGatedSession(session) && (!isBootstrapReady(session) || hasBootstrapBacklog(session) || session.bootstrapDraining)) {
+    const op = enqueueBootstrapOperation(id, session, {
+      type: 'submit',
+      body: { ...(req.body || {}) }
+    });
+    if (isBootstrapReady(session)) {
+      drainBootstrapQueue(id, session);
+    }
+    const queuedSubmit = await waitForBootstrapSubmit(op, session, gateTimeoutMs);
+    return res.status(queuedSubmit.status).json(queuedSubmit.body);
+  }
+
   function emitSubmitBus(payload) {
     const busMsg = JSON.stringify({
       type: 'submit',
@@ -1805,6 +2132,12 @@ app.post('/api/sessions/:id/inject', async (req, res) => {
             delete pendingReports[senderAlias];
             const elapsedSecs = Number(((Date.now() - new Date(senderPending.injectedAt).getTime()) / 1000).toFixed(1));
             const senderSession = sessions[senderAlias];
+            sessionStateManager.markIdle(senderAlias, 1.0, {
+              trigger: 'report_inject',
+              report_inject_id: inject_id,
+              report_status: classification,
+              source: senderPending.source
+            });
             const eventType =
               classification === 'report_blocked' ? 'TASK_BLOCKED_WITH_REASON' :
               classification === 'report_dismissed' ? 'TASK_DISMISSED' :
@@ -1881,7 +2214,17 @@ app.post('/api/sessions/:id/inject', async (req, res) => {
       });
     }
 
-    res.json({ success: true, inject_id, strategy: delivery.strategy, submit: delivery.submit });
+    res.json({
+      success: true,
+      inject_id,
+      strategy: delivery.strategy,
+      submit: delivery.submit,
+      ...(delivery.bootstrap_queued ? {
+        bootstrap_queued: true,
+        bootstrap_op_id: delivery.bootstrap_op_id || delivery.msg_id,
+        pending: delivery.pending
+      } : {})
+    });
   } catch (err) {
     emitInjectFailureEvent(id, 'DELIVERY_FAILED', err.message, { inject_id }, session);
     res.status(500).json(buildErrorBody('DELIVERY_FAILED', err.message));
@@ -2607,6 +2950,7 @@ wss.on('connection', (ws, req) => {
       outputRing: [],
       ready: true,
           };
+    initializeBootstrapState(autoSession);
     sessions[sessionId] = autoSession;
     console.log(`[WS] Auto-registered wrapped session ${sessionId} on reconnect`);
     // Set tab title via kitty (no \x0c redraw — it causes flickering on multi-session reconnect)
@@ -2639,7 +2983,9 @@ wss.on('connection', (ws, req) => {
     }
     activeSession.ownerWs = ws;
     markSessionConnected(activeSession);
+    initializeBootstrapState(activeSession);
     console.log(`[WS] Wrap owner ${isOwnerConnect && activeSession.clients.size > 1 ? 're-' : ''}connected for session ${sessionId} (Total: ${activeSession.clients.size})`);
+    scheduleBootstrapPromptPoll(sessionId, activeSession);
     if (hadDisconnectedOwner) {
       emitSessionLifecycleEvent('session_reconnect', sessionId, activeSession);
     }
@@ -2665,7 +3011,11 @@ wss.on('connection', (ws, req) => {
               }
             });
           } else if (type === 'ready') {
-            activeSession.ready = true;
+            if (isBootstrapGatedSession(activeSession)) {
+              markBootstrapReady(sessionId, activeSession, 'bridge_ready');
+            } else {
+              activeSession.ready = true;
+            }
             activeSession.lastActivityAt = new Date().toISOString();
             console.log(`[READY] Session ${sessionId} CLI is ready for inject`);
             // Broadcast readiness to bus (cmux/kitty paths now enabled for this session)