clisbot 0.1.36 → 0.1.38

package/dist/main.js

@@ -54623,6 +54623,12 @@ function parseCliArgs(argv) {
       args: args.slice(1)
     };
   }
+  if (command === "runner") {
+    return {
+      name: "runner",
+      args: args.slice(1)
+    };
+  }
   if (command === "pairing") {
     return {
       name: "pairing",
@@ -54685,6 +54691,7 @@ function renderCliHelp() {
     "  clisbot message <subcommand>",
     "  clisbot agents <subcommand>",
     "  clisbot auth <subcommand>",
+    "  clisbot runner <subcommand>",
     "  clisbot pairing <subcommand>",
     "  clisbot init [--cli <codex|claude|gemini>] [--bot-type <personal|team>] [--persist]",
     "              [--slack-account <id> --slack-app-token <ENV_NAME|${ENV_NAME}|literal> --slack-bot-token <ENV_NAME|${ENV_NAME}|literal>]...",
@@ -54728,6 +54735,8 @@ function renderCliHelp() {
     "  agents             Manage configured agents and top-level bindings.",
     "                     See `clisbot agents --help` for focused add/bootstrap/binding help.",
     "  auth               Manage app and agent auth roles, principals, and permissions in config. See `clisbot auth --help`.",
+    "  runner             Validate and inspect runner-facing operator contracts such as `runner smoke`.",
+    "                     See `clisbot runner --help` for the current smoke surface.",
     "  pairing            Run the pairing control CLI. See `clisbot pairing --help`.",
     `  init               Seed ${configPath} and optionally create the first agent without starting clisbot.`,
     "                     See `clisbot init --help` for bootstrap-focused flags and examples.",
@@ -64255,6 +64264,8 @@ function resolveAgentTargetInternal(loadedConfig, target) {
 }
 
 // src/agents/job-queue.ts
+var QUEUE_PENDING_POLL_INTERVAL_MS = 25;
+
 class ClearedQueuedTaskError extends Error {
   constructor() {
     super("Queued task was cleared before execution.");
@@ -64282,6 +64293,7 @@ class AgentJobQueue {
       text: options.text,
       createdAt: Date.now(),
       status: "pending",
+      canStart: options.canStart,
       task,
       resolve,
       reject,
@@ -64349,6 +64361,10 @@ class AgentJobQueue {
         if (!nextEntry) {
           break;
         }
+        if (nextEntry.canStart && !await nextEntry.canStart()) {
+          await sleep(QUEUE_PENDING_POLL_INTERVAL_MS);
+          continue;
+        }
         nextEntry.status = "running";
         try {
           nextEntry.resolve(await nextEntry.task());
@@ -64609,12 +64625,22 @@ function isInterruptStatusLine(line) {
   }
   return CODEX_WORKING_STATUS_PATTERN.test(trimmed) || CODEX_INTERRUPT_FOOTER_PATTERN.test(trimmed);
 }
+function isActiveTimerStatusLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) {
+    return false;
+  }
+  return isInterruptStatusLine(trimmed) || GEMINI_THINKING_STATUS_PATTERN.test(trimmed) || CLAUDE_TIMER_FOOTER_PATTERN.test(trimmed);
+}
 function isTimerDrivenStatusLine(line) {
   const trimmed = line.trim();
   if (!trimmed) {
     return false;
   }
-  return isInterruptStatusLine(trimmed) || GEMINI_THINKING_STATUS_PATTERN.test(trimmed) || CLAUDE_WORKED_STATUS_PATTERN.test(trimmed) || CLAUDE_TIMER_FOOTER_PATTERN.test(trimmed);
+  return isActiveTimerStatusLine(trimmed) || CLAUDE_WORKED_STATUS_PATTERN.test(trimmed);
+}
+function hasActiveTimerStatus(snapshot) {
+  return splitNormalizedLines(snapshot).some((line) => isActiveTimerStatusLine(line));
 }
 function shouldDropCodexChromeLine(line) {
   const trimmed = line.trim();
@@ -66145,8 +66171,10 @@ var FIRST_OUTPUT_POLL_INTERVAL_MS = 250;
 async function monitorTmuxRun(params) {
   let previousSnapshot = params.initialSnapshot;
   let previousRunningSnapshot = "";
-  let lastActivityAt = params.startedAt;
+  let lastPaneChangeAt = params.startedAt;
   let sawActivity = false;
+  let sawPaneChange = false;
+  let sawPromptSubmission = Boolean(params.prompt);
   let detachedNotified = params.detachedAlready;
   let firstMeaningfulDeltaLogged = false;
   let noOutputThresholdLogged = false;
@@ -66162,6 +66190,8 @@ async function monitorTmuxRun(params) {
       promptSubmitDelayMs: params.promptSubmitDelayMs,
       timingContext: params.timingContext
     });
+    sawPromptSubmission = true;
+    lastPaneChangeAt = Date.now();
     await params.onPromptSubmitted?.();
     logLatencyDebug("tmux-submit-complete", params.timingContext, {
       sessionName: params.sessionName,
@@ -66173,11 +66203,16 @@ async function monitorTmuxRun(params) {
     await sleep(sawActivity ? params.updateIntervalMs : Math.min(params.updateIntervalMs, FIRST_OUTPUT_POLL_INTERVAL_MS));
     const snapshot = normalizePaneText(await params.tmux.capturePane(params.sessionName, params.captureLines));
     const now = Date.now();
+    const paneChanged = snapshot !== previousSnapshot;
+    if (paneChanged) {
+      lastPaneChangeAt = now;
+      sawPaneChange = true;
+    }
+    const hasActiveTimer = hasActiveTimerStatus(snapshot);
     const runningSnapshot = params.initialSnapshot ? deriveRunningInteractionText(params.initialSnapshot, snapshot) : deriveRunningInteractionSnapshot(snapshot);
     previousSnapshot = snapshot;
     if (runningSnapshot && runningSnapshot !== previousRunningSnapshot) {
       previousRunningSnapshot = runningSnapshot;
-      lastActivityAt = now;
       sawActivity = true;
       if (!firstMeaningfulDeltaLogged) {
         firstMeaningfulDeltaLogged = true;
@@ -66200,7 +66235,7 @@ async function monitorTmuxRun(params) {
         initialSnapshot: params.initialSnapshot
       });
     }
-    if (sawActivity && now - lastActivityAt >= params.idleTimeoutMs) {
+    if (!hasActiveTimer && (sawActivity || sawPaneChange || sawPromptSubmission) && now - lastPaneChangeAt >= params.idleTimeoutMs) {
       await params.onCompleted({
         snapshot: deriveInteractionText(params.initialSnapshot, previousSnapshot),
         fullSnapshot: previousSnapshot,
@@ -66221,9 +66256,20 @@ async function monitorTmuxRun(params) {
 // src/agents/session-service.ts
 var OBSERVER_RETRYABLE_FAILURE_LIMIT = 3;
 var DETACHED_OBSERVER_INTERVAL_MS = 5 * 60000;
+var TMUX_MISSING_SESSION_PATTERN3 = /(?:can't find session:|no server running on )/i;
+var TMUX_SERVER_UNAVAILABLE_PATTERN3 = /(?:No such file or directory|error connecting to|failed to connect to server)/i;
 function formatObserverError(error) {
   return error instanceof Error ? error.stack ?? error.message : String(error);
 }
+function isMissingTmuxSessionError2(error) {
+  return error instanceof Error && TMUX_MISSING_SESSION_PATTERN3.test(error.message);
+}
+function isTmuxServerUnavailableError2(error) {
+  return error instanceof Error && TMUX_SERVER_UNAVAILABLE_PATTERN3.test(error.message);
+}
+function isBootstrapSessionLostError2(error) {
+  return error instanceof Error && /tmux session disappeared before startup finished|tmux server became unavailable before startup finished/i.test(error.message);
+}
 function listObserverErrorCodes(error) {
   const codes = new Set;
   const visit = (value) => {
@@ -66295,6 +66341,7 @@ class SessionService {
   runnerSessions;
   resolveTarget;
   activeRuns = new Map;
+  nextRunId = 1;
   stopping = false;
   constructor(tmux, sessionState, runnerSessions, resolveTarget) {
     this.tmux = tmux;
@@ -66308,42 +66355,10 @@ class SessionService {
       if (!entry.runtime || entry.runtime.state === "idle") {
         continue;
       }
-      const resolved = this.resolveTarget({
+      await this.reconcilePersistedActiveRun({
         agentId: entry.agentId,
         sessionKey: entry.sessionKey
       });
-      if (!await this.tmux.hasSession(resolved.sessionName)) {
-        await this.sessionState.setSessionRuntime(resolved, {
-          state: "idle"
-        });
-        continue;
-      }
-      const fullSnapshot = normalizePaneText(await this.tmux.capturePane(resolved.sessionName, resolved.stream.captureLines));
-      const initialResult = createDeferred();
-      const update = this.createRunUpdate({
-        resolved,
-        status: entry.runtime.state === "detached" ? "detached" : "running",
-        snapshot: deriveInteractionText("", fullSnapshot),
-        fullSnapshot,
-        initialSnapshot: "",
-        note: entry.runtime.state === "detached" ? this.buildDetachedNote(resolved) : undefined
-      });
-      this.activeRuns.set(resolved.sessionKey, {
-        resolved,
-        observers: new Map,
-        observerFailures: new Map,
-        initialResult,
-        latestUpdate: update,
-        steeringReady: true,
-        startedAt: entry.runtime.startedAt ?? Date.now()
-      });
-      this.startRunMonitor(resolved.sessionKey, {
-        prompt: undefined,
-        initialSnapshot: fullSnapshot,
-        startedAt: entry.runtime.startedAt ?? Date.now(),
-        detachedAlready: entry.runtime.state === "detached",
-        timingContext: undefined
-      });
     }
   }
   async executePrompt(target, prompt, observer, options = {}) {
@@ -66354,21 +66369,15 @@ class SessionService {
     if (existingActiveRun) {
       throw new ActiveRunInProgressError(existingActiveRun.latestUpdate);
     }
-    const existingEntry = await this.sessionState.getEntry(target.sessionKey);
-    if (existingEntry?.runtime?.state && existingEntry.runtime.state !== "idle") {
-      const resolvedExisting = this.resolveTarget(target);
-      throw new ActiveRunInProgressError(this.createRunUpdate({
-        resolved: resolvedExisting,
-        status: existingEntry.runtime.state === "detached" ? "detached" : "running",
-        snapshot: "",
-        fullSnapshot: "",
-        initialSnapshot: "",
-        note: existingEntry.runtime.state === "detached" ? this.buildDetachedNote(resolvedExisting) : "This session already has an active run. Use `/attach`, `/watch every 30s`, or `/stop` before sending a new prompt."
-      }));
+    const reconciledRun = await this.reconcilePersistedActiveRun(target);
+    if (reconciledRun) {
+      throw new ActiveRunInProgressError(reconciledRun.latestUpdate);
     }
     const initialResult = createDeferred();
     const provisionalResolved = this.resolveTarget(target);
+    const runId = this.allocateRunId();
     this.activeRuns.set(provisionalResolved.sessionKey, {
+      runId,
       resolved: provisionalResolved,
       observers: new Map([[observer.id, { ...observer }]]),
       observerFailures: new Map,
@@ -66416,6 +66425,7 @@ class SessionService {
         startedAt
       });
       this.startRunMonitor(resolved.sessionKey, {
+        runId,
         prompt,
         initialSnapshot,
         startedAt,
@@ -66424,12 +66434,12 @@ class SessionService {
       });
       return initialResult.promise;
     } catch (error) {
-      await this.failActiveRun(provisionalResolved.sessionKey, error);
+      await this.failActiveRun(provisionalResolved.sessionKey, runId, error);
       throw error;
     }
   }
   async observeRun(target, observer) {
-    const existingRun = this.activeRuns.get(target.sessionKey);
+    const existingRun = this.activeRuns.get(target.sessionKey) ?? await this.reconcilePersistedActiveRun(target);
     if (existingRun) {
       existingRun.observers.set(observer.id, {
         ...observer
@@ -66592,8 +66602,8 @@ class SessionService {
       }
     }
   }
-  async finishActiveRun(sessionKey, update) {
-    const run = this.activeRuns.get(sessionKey);
+  async finishActiveRun(sessionKey, runId, update) {
+    const run = this.getRun(sessionKey, runId);
     if (!run) {
       return;
     }
@@ -66604,8 +66614,8 @@ class SessionService {
     run.initialResult.resolve(update);
     this.activeRuns.delete(run.resolved.sessionKey);
   }
-  async failActiveRun(sessionKey, error) {
-    const run = this.activeRuns.get(sessionKey);
+  async failActiveRun(sessionKey, runId, error) {
+    const run = this.getRun(sessionKey, runId);
     if (!run) {
       return;
     }
@@ -66631,7 +66641,7 @@ class SessionService {
     if (!this.runnerSessions.canRecoverMidRun(error)) {
       return false;
     }
-    const run = this.activeRuns.get(sessionKey);
+    const run = this.getRun(sessionKey, params.runId);
     if (!run) {
       return true;
     }
@@ -66648,7 +66658,7 @@ class SessionService {
     }));
     try {
       const recovered = await this.runnerSessions.reopenRunContext(target, params.timingContext);
-      const currentRun = this.activeRuns.get(sessionKey);
+      const currentRun = this.getRun(sessionKey, params.runId);
       if (!currentRun) {
         return true;
       }
@@ -66664,6 +66674,7 @@ class SessionService {
       });
       await this.notifyRunObservers(currentRun, currentRun.latestUpdate);
       this.startRunMonitor(sessionKey, {
+        runId: currentRun.runId,
         prompt: MID_RUN_RECOVERY_CONTINUE_PROMPT,
         initialSnapshot: recovered.initialSnapshot,
         startedAt: currentRun.startedAt,
@@ -66676,11 +66687,12 @@ class SessionService {
     } catch (reopenError) {
       if (recoveryAttempt < MID_RUN_RECOVERY_MAX_ATTEMPTS && this.runnerSessions.canRecoverMidRun(reopenError)) {
         return await this.recoverLostMidRun(sessionKey, {
+          runId: params.runId,
           timingContext: params.timingContext,
           recoveryAttempt: recoveryAttempt + 1
         }, reopenError);
       }
-      const currentRun = this.activeRuns.get(sessionKey);
+      const currentRun = this.getRun(sessionKey, params.runId);
       if (!currentRun) {
         return true;
       }
@@ -66688,15 +66700,15 @@ class SessionService {
       try {
         await this.runnerSessions.startFreshSession(target, params.timingContext);
       } catch (freshError) {
-        await this.failActiveRun(sessionKey, await this.runnerSessions.mapRunError(freshError, currentRun.resolved.sessionName, currentRun.latestUpdate.fullSnapshot));
+        await this.failActiveRun(sessionKey, currentRun.runId, await this.runnerSessions.mapRunError(freshError, currentRun.resolved.sessionName, currentRun.latestUpdate.fullSnapshot));
         return true;
       }
-      await this.failActiveRun(sessionKey, new Error(buildRunRecoveryNote("fresh-required")));
+      await this.failActiveRun(sessionKey, currentRun.runId, new Error(buildRunRecoveryNote("fresh-required")));
       return true;
     }
   }
   startRunMonitor(sessionKey, params) {
-    const run = this.activeRuns.get(sessionKey);
+    const run = this.getRun(sessionKey, params.runId);
     if (!run) {
       return;
     }
@@ -66720,14 +66732,14 @@ class SessionService {
           detachedAlready: params.detachedAlready,
           timingContext: params.timingContext,
           onPromptSubmitted: async () => {
-            const currentRun = this.activeRuns.get(sessionKey);
+            const currentRun = this.getRun(sessionKey, params.runId);
             if (!currentRun) {
               return;
             }
             currentRun.steeringReady = true;
           },
           onRunning: async (update) => {
-            const currentRun = this.activeRuns.get(sessionKey);
+            const currentRun = this.getRun(sessionKey, params.runId);
             if (!currentRun) {
               return;
             }
@@ -66743,7 +66755,7 @@ class SessionService {
             }));
           },
           onDetached: async (update) => {
-            const currentRun = this.activeRuns.get(sessionKey);
+            const currentRun = this.getRun(sessionKey, params.runId);
             if (!currentRun) {
               return;
             }
@@ -66765,27 +66777,111 @@ class SessionService {
             currentRun.initialResult.resolve(detachedUpdate);
           },
           onCompleted: async (update) => {
+            const currentRun = this.getRun(sessionKey, params.runId);
+            if (!currentRun) {
+              return;
+            }
             const runUpdate = this.createRunUpdate({
-              resolved: run.resolved,
+              resolved: currentRun.resolved,
               status: "completed",
               snapshot: mergeRunSnapshot(params.snapshotPrefix ?? "", update.snapshot),
               fullSnapshot: update.fullSnapshot,
               initialSnapshot: update.initialSnapshot
             });
-            await this.finishActiveRun(sessionKey, runUpdate);
+            await this.finishActiveRun(sessionKey, params.runId, runUpdate);
           }
         });
       } catch (error) {
         if (await this.recoverLostMidRun(sessionKey, {
+          runId: params.runId,
           timingContext: params.timingContext,
           recoveryAttempt: (params.recoveryAttempt ?? 0) + 1
         }, error)) {
           return;
         }
-        await this.failActiveRun(sessionKey, await this.runnerSessions.mapRunError(error, run.resolved.sessionName, run.latestUpdate.fullSnapshot));
+        await this.failActiveRun(sessionKey, params.runId, await this.runnerSessions.mapRunError(error, run.resolved.sessionName, run.latestUpdate.fullSnapshot));
       }
     })();
   }
+  allocateRunId() {
+    return String(this.nextRunId++);
+  }
+  async reconcilePersistedActiveRun(target) {
+    const activeRun = this.activeRuns.get(target.sessionKey);
+    if (activeRun) {
+      return activeRun;
+    }
+    const entry = await this.sessionState.getEntry(target.sessionKey);
+    if (!entry?.runtime || entry.runtime.state === "idle") {
+      return null;
+    }
+    const resolved = this.resolveTarget(target);
+    if (!await this.tmux.hasSession(resolved.sessionName)) {
+      await this.sessionState.setSessionRuntime(resolved, {
+        state: "idle"
+      });
+      return null;
+    }
+    try {
+      return await this.rehydratePersistedActiveRun(resolved, {
+        runtimeState: entry.runtime.state,
+        startedAt: entry.runtime.startedAt
+      });
+    } catch (error) {
+      if (isMissingTmuxSessionError2(error) || isTmuxServerUnavailableError2(error) || isBootstrapSessionLostError2(error)) {
+        await this.sessionState.setSessionRuntime(resolved, {
+          state: "idle"
+        });
+        return null;
+      }
+      throw error;
+    }
+  }
+  async rehydratePersistedActiveRun(resolved, params) {
+    const existingRun = this.activeRuns.get(resolved.sessionKey);
+    if (existingRun) {
+      return existingRun;
+    }
+    const fullSnapshot = normalizePaneText(await this.tmux.capturePane(resolved.sessionName, resolved.stream.captureLines));
+    const startedAt = params.startedAt ?? Date.now();
+    const runId = this.allocateRunId();
+    const initialResult = createDeferred();
+    const update = this.createRunUpdate({
+      resolved,
+      status: params.runtimeState === "detached" ? "detached" : "running",
+      snapshot: deriveInteractionText("", fullSnapshot),
+      fullSnapshot,
+      initialSnapshot: "",
+      note: params.runtimeState === "detached" ? this.buildDetachedNote(resolved) : undefined
+    });
+    const run = {
+      runId,
+      resolved,
+      observers: new Map,
+      observerFailures: new Map,
+      initialResult,
+      latestUpdate: update,
+      steeringReady: true,
+      startedAt
+    };
+    this.activeRuns.set(resolved.sessionKey, run);
+    this.startRunMonitor(resolved.sessionKey, {
+      runId,
+      prompt: undefined,
+      initialSnapshot: fullSnapshot,
+      startedAt,
+      detachedAlready: params.runtimeState === "detached",
+      timingContext: undefined
+    });
+    return run;
+  }
+  getRun(sessionKey, runId) {
+    const run = this.activeRuns.get(sessionKey);
+    if (!run || run.runId !== runId) {
+      return null;
+    }
+    return run;
+  }
 }
 
 // src/agents/agent-service.ts
@@ -67133,7 +67229,8 @@ class AgentService {
       timingContext: callbacks.timingContext,
       onUpdate: callbacks.onUpdate
     }), {
-      text: prompt
+      text: prompt,
+      canStart: async () => !this.activeRuns.hasActiveRun(target)
     });
   }
   getMaxMessageChars(agentId) {
@@ -69465,6 +69562,7 @@ async function clearSlackAssistantThreadStatus(client, target) {
 }
 
 // src/channels/processing-indicator.ts
+var ACTIVE_RUN_WAIT_POLL_INTERVAL_MS = 250;
 function shouldResolveIndicatorWait(update) {
   return isTerminalRunStatus(update.status);
 }
@@ -69491,6 +69589,18 @@ async function waitForProcessingIndicatorLifecycle(params) {
         settled = true;
         resolve();
       };
+      (async () => {
+        while (!settled) {
+          await sleep(ACTIVE_RUN_WAIT_POLL_INTERVAL_MS);
+          if (settled) {
+            return;
+          }
+          if (!params.agentService.hasActiveRun(params.sessionTarget)) {
+            resolveOnce();
+            return;
+          }
+        }
+      })();
       try {
         const observation = await params.agentService.observeRun(params.sessionTarget, {
           id: params.observerId,
@@ -76277,6 +76387,216 @@ async function runMessageCli(args, dependencies = defaultMessageCliDependencies)
   dependencies.print(JSON.stringify(execution.result, null, 2));
 }
 
+// src/control/runtime-cli-shared.ts
+class CliCommandError extends Error {
+  exitCode;
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+}
+function printCommandOutcomeBanner(outcome) {
+  console.log("");
+  console.log("+---------+");
+  console.log(outcome === "success" ? "| SUCCESS |" : "| FAILED  |");
+  console.log("+---------+");
+  console.log("");
+}
+function printCommandOutcomeFooter(outcome) {
+  printCommandOutcomeBanner(outcome);
+}
+function assertSupportedPlatform(command) {
+  if (process.platform !== "win32") {
+    return;
+  }
+  if (command.name === "help" || command.name === "version") {
+    return;
+  }
+  throw new Error("Native Windows is not supported yet. Run clisbot from WSL2 or use Linux/macOS instead.");
+}
+function getCliErrorExitCode(error) {
+  return error instanceof CliCommandError ? error.exitCode : 1;
+}
+
+// src/control/runner-cli.ts
+var SMOKE_BACKENDS = ["codex", "claude", "gemini", "all"];
+var SMOKE_SCENARIOS = [
+  "startup_ready",
+  "first_prompt_roundtrip",
+  "session_id_roundtrip",
+  "interrupt_during_run",
+  "recover_after_runner_loss"
+];
+var SMOKE_SUITES = ["launch-trio"];
+function parseRepeatedOption4(args, name) {
+  const values = [];
+  for (let index = 0;index < args.length; index += 1) {
+    if (args[index] !== name) {
+      continue;
+    }
+    const value = args[index + 1]?.trim();
+    if (!value) {
+      throw new CliCommandError(`Missing value for ${name}`, 2);
+    }
+    values.push(value);
+  }
+  return values;
+}
+function parseSingleOption3(args, name) {
+  const values = parseRepeatedOption4(args, name);
+  if (values.length === 0) {
+    return;
+  }
+  return values[values.length - 1];
+}
+function hasFlag5(args, name) {
+  return args.includes(name);
+}
+function isOneOf(value, allowed) {
+  return allowed.includes(value);
+}
+function parseTimeoutMs(raw) {
+  if (!raw) {
+    return;
+  }
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new CliCommandError("Invalid value for --timeout-ms", 2);
+  }
+  return parsed;
+}
+function renderRunnerHelp() {
+  return [
+    "clisbot runner",
+    "",
+    "Usage:",
+    "  clisbot runner",
+    "  clisbot runner --help",
+    "  clisbot runner smoke --backend <codex|claude|gemini> --scenario <name> [--workspace <path>] [--agent <id>] [--artifact-dir <path>] [--timeout-ms <n>] [--keep-session] [--json]",
+    "  clisbot runner smoke --backend all --suite launch-trio [--workspace <path>] [--agent <id>] [--artifact-dir <path>] [--timeout-ms <n>] [--keep-session] [--json]",
+    "",
+    "Smoke scenarios:",
+    "  - startup_ready",
+    "  - first_prompt_roundtrip",
+    "  - session_id_roundtrip",
+    "  - interrupt_during_run",
+    "  - recover_after_runner_loss",
+    "",
+    "Smoke suites:",
+    "  - launch-trio",
+    "",
+    "Current status:",
+    "  - the `runner` CLI surface now validates the smoke command contract",
+    "  - real smoke execution is the next implementation batch"
+  ].join(`
+`);
+}
+function parseSmokeCommand(args) {
+  const backend = parseSingleOption3(args, "--backend");
+  if (!backend) {
+    throw new CliCommandError(`Usage: clisbot runner smoke --backend <codex|claude|gemini> --scenario <name> [--json]
+       clisbot runner smoke --backend all --suite launch-trio [--json]`, 2);
+  }
+  if (!isOneOf(backend, SMOKE_BACKENDS)) {
+    throw new CliCommandError(`Unsupported --backend value: ${backend}`, 2);
+  }
+  const rawScenario = parseSingleOption3(args, "--scenario");
+  const rawSuite = parseSingleOption3(args, "--suite");
+  if (rawScenario && rawSuite) {
+    throw new CliCommandError("--scenario and --suite are mutually exclusive", 2);
+  }
+  if (rawScenario && !isOneOf(rawScenario, SMOKE_SCENARIOS)) {
+    throw new CliCommandError(`Unsupported --scenario value: ${rawScenario}`, 2);
+  }
+  if (rawSuite && !isOneOf(rawSuite, SMOKE_SUITES)) {
+    throw new CliCommandError(`Unsupported --suite value: ${rawSuite}`, 2);
+  }
+  const scenario = rawScenario;
+  const suite = rawSuite;
+  if (backend === "all") {
+    if (scenario) {
+      throw new CliCommandError("--backend all is only valid with --suite", 2);
+    }
+    if (!suite) {
+      throw new CliCommandError("--backend all requires --suite launch-trio", 2);
+    }
+  } else {
+    if (suite) {
+      throw new CliCommandError(`--suite is only valid with --backend all`, 2);
+    }
+    if (!scenario) {
+      throw new CliCommandError(`--backend ${backend} requires --scenario`, 2);
+    }
+  }
+  return {
+    backend,
+    scenario,
+    suite,
+    workspace: parseSingleOption3(args, "--workspace"),
+    agent: parseSingleOption3(args, "--agent"),
+    artifactDir: parseSingleOption3(args, "--artifact-dir"),
+    timeoutMs: parseTimeoutMs(parseSingleOption3(args, "--timeout-ms")),
+    keepSession: hasFlag5(args, "--keep-session"),
+    json: hasFlag5(args, "--json")
+  };
+}
+function renderSmokeNotImplementedResult(options) {
+  return {
+    kind: "runner-smoke-framework-error",
+    version: "v0",
+    ok: false,
+    backendId: options.backend,
+    scenario: options.scenario ?? null,
+    suite: options.suite ?? null,
+    error: {
+      code: "NOT_IMPLEMENTED",
+      message: "clisbot runner smoke is not implemented yet. The command surface and contract validation are ready; the real execution batch is next."
+    },
+    options: {
+      workspace: options.workspace ?? null,
+      agent: options.agent ?? null,
+      artifactDir: options.artifactDir ?? null,
+      timeoutMs: options.timeoutMs ?? null,
+      keepSession: options.keepSession,
+      json: options.json
+    }
+  };
+}
+async function runSmokeCli(args) {
+  if (args.length === 0 || hasFlag5(args, "--help") || hasFlag5(args, "-h")) {
+    console.log(renderRunnerHelp());
+    return;
+  }
+  const options = parseSmokeCommand(args);
+  const result = renderSmokeNotImplementedResult(options);
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log([
+      "clisbot runner smoke",
+      "",
+      `backend: ${options.backend}`,
+      options.scenario ? `scenario: ${options.scenario}` : `suite: ${options.suite}`,
+      "status: not implemented yet",
+      "note: the smoke contract is validated, but real CLI execution is the next batch"
+    ].join(`
+`));
+  }
+  process.exitCode = 3;
+}
+async function runRunnerCli(args) {
+  const subcommand = args[0];
+  if (!subcommand || subcommand === "--help" || subcommand === "-h" || subcommand === "help") {
+    console.log(renderRunnerHelp());
+    return;
+  }
+  if (subcommand === "smoke") {
+    await runSmokeCli(args.slice(1));
+    return;
+  }
+  throw new CliCommandError(renderRunnerHelp(), 2);
+}
+
 // src/control/activity-store.ts
 import { dirname as dirname14 } from "node:path";
 class ActivityStore {
@@ -76812,27 +77132,6 @@ function renderOperatorErrorWithHelpLines(error) {
   ];
 }
 
-// src/control/runtime-cli-shared.ts
-function printCommandOutcomeBanner(outcome) {
-  console.log("");
-  console.log("+---------+");
-  console.log(outcome === "success" ? "| SUCCESS |" : "| FAILED  |");
-  console.log("+---------+");
-  console.log("");
-}
-function printCommandOutcomeFooter(outcome) {
-  printCommandOutcomeBanner(outcome);
-}
-function assertSupportedPlatform(command) {
-  if (process.platform !== "win32") {
-    return;
-  }
-  if (command.name === "help" || command.name === "version") {
-    return;
-  }
-  throw new Error("Native Windows is not supported yet. Run clisbot from WSL2 or use Linux/macOS instead.");
-}
-
 // src/control/runtime-bootstrap-cli.ts
 function hasHelpFlag(args) {
   return args.includes("--help") || args.includes("-h") || args.includes("help");
@@ -77922,6 +78221,10 @@ async function runControlCommand(command) {
     await runAuthCli(command.args);
     return true;
   }
+  if (command.name === "runner") {
+    await runRunnerCli(command.args);
+    return true;
+  }
   if (command.name === "pairing") {
     await runPairingCli(command.args);
     return true;
@@ -77943,5 +78246,5 @@ try {
     printCommandOutcomeBanner("failure");
   }
   await printCliError(error);
-  process.exit(1);
+  process.exit(getCliErrorExitCode(error));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clisbot",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "private": false,
   "description": "Chat surfaces for durable AI coding agents running in tmux",
   "license": "MIT",