march-cli 0.1.40 → 0.1.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "march-cli",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "description": "March CLI — terminal-native coding agent with context reconstruction",
   "type": "module",
   "main": "./src/main.mjs",

package/src/agent/runner.mjs

@@ -18,7 +18,7 @@ import { resolveRunnerSessionOptions } from "./session/session-options.mjs";
 import { createSessionBinding } from "./session/session-binding.mjs";
 import { maybeAutoNameSession } from "./session/session-auto-name.mjs";
 import { MARCH_BASE_TOOL_NAMES } from "./tool-names.mjs";
-import { runRunnerTurn } from "./turn/turn-runner.mjs";
+import { MODEL_STREAM_IDLE_TIMEOUT_CODE, runRunnerTurn } from "./turn/turn-runner.mjs";
 import { beginLoggedTurn } from "./turn/turn-logging.mjs";
 import { appendFastVariants, createFastModelEntry, fromFastEntryModel, isFastProvider } from "./runner/fast-model.mjs";
 import { registerSuperGrokProvider } from "../supergrok/provider.mjs";
@@ -142,6 +142,7 @@ export async function createRunner({ cwd, modelId = null, provider = null, provi
         turnLog.endSuccess(result);
         return result;
       } catch (err) {
+        if (err?.code === MODEL_STREAM_IDLE_TIMEOUT_CODE) nextTurnContextMode = "continueExistingPiTranscript";
         notifyTurnEndDetached(turnNotifier, {
           status: "error",
           sessionName: engine.sessionName,

package/src/agent/turn/turn-events.mjs

@@ -12,6 +12,8 @@ export function createTurnEventState() {
     assistantContextParts: [],
     activeToolContextPart: null,
     toolCalls: [],
+    lastAssistantStopReason: null,
+    lastAssistantErrorMessage: null,
   };
 }
 
@@ -19,6 +21,10 @@ export function handleRunnerSessionEvent(event, { ui, engine, state }) {
   if (event.type === "message_update" && event.assistantMessageEvent) {
     handleAssistantMessageEvent(event.assistantMessageEvent, { ui, state });
   }
+  if (event.type === "message_end" && event.message?.role === "assistant") {
+    state.lastAssistantStopReason = event.message.stopReason ?? null;
+    state.lastAssistantErrorMessage = event.message.errorMessage ?? null;
+  }
   if (event.type === "tool_execution_start") {
     closeAssistantReply({ ui, state });
     appendToolStartContext(state, event.toolName, event.args);

package/src/agent/turn/turn-runner.mjs

@@ -2,6 +2,8 @@ import { formatRecallHints } from "../../memory/markdown-store.mjs";
 import { resolveImageAttachmentReferences } from "../../session/attachment-references.mjs";
 import { closeAssistantReply, compactAssistantContext, createTurnEventState, handleRunnerSessionEvent } from "./turn-events.mjs";
 
+export const MODEL_STREAM_IDLE_TIMEOUT_CODE = "MODEL_STREAM_IDLE_TIMEOUT";
+
 export async function runRunnerTurn({
   prompt,
   userMessage,
@@ -26,17 +28,33 @@ export async function runRunnerTurn({
   const activeSession = sessionBinding.get();
   const turnState = createTurnEventState();
   const midTurnRecallHints = [];
+  const idleWatchdog = createModelStreamIdleWatchdog({ session: activeSession, logger, setPhase });
   ui.turnStart();
   setPhase?.("subscribed");
   logger?.event("turn.ui.start");
 
   const unsubscribe = activeSession.subscribe((event) => {
     logSessionEvent(logger, event);
-    if (event.type === "tool_execution_start") setPhase?.(`tool_running:${event.toolName ?? "unknown"}`);
-    if (event.type === "tool_execution_end") setPhase?.("model_streaming");
-    if (event.type === "auto_retry_start") setPhase?.("retry_wait");
-    if (event.type === "auto_retry_end") setPhase?.("model_streaming");
-    if (event.type === "message_update") setPhase?.("model_streaming");
+    if (event.type === "tool_execution_start") {
+      idleWatchdog.pause();
+      setPhase?.(`tool_running:${event.toolName ?? "unknown"}`);
+    }
+    if (event.type === "tool_execution_end") {
+      setPhase?.("model_streaming");
+      idleWatchdog.arm("tool_execution_end");
+    }
+    if (event.type === "auto_retry_start") {
+      idleWatchdog.pause();
+      setPhase?.("retry_wait");
+    }
+    if (event.type === "auto_retry_end") {
+      setPhase?.("model_streaming");
+      idleWatchdog.arm("auto_retry_end");
+    }
+    if (event.type === "message_update") {
+      setPhase?.("model_streaming");
+      idleWatchdog.arm("message_update");
+    }
     handleRunnerSessionEvent(event, { ui, engine, state: turnState });
     if (event.type === "tool_execution_start") {
       const hints = flushAssistantRecall({ memoryStore, engine, turnState, currentProject });
@@ -59,11 +77,14 @@ export async function runRunnerTurn({
     logger?.event("model.prompt.start", { contextMode });
     try {
       if (contextMode === "rebuild") resetPiMessageHistory(activeSession);
-      await activeSession.prompt(
+      idleWatchdog.arm("model_request");
+      await idleWatchdog.watch(activeSession.prompt(
         contextMode === "continueExistingPiTranscript" ? (userMessage ?? prompt) : prompt,
         attachmentReferences.images.length > 0 ? { images: attachmentReferences.images } : undefined,
-      );
+      ));
+      throwIfAssistantEndedWithError(turnState);
     } finally {
+      idleWatchdog.clear();
       setModelCallKind("model");
       logger?.event("model.prompt.end");
     }
@@ -86,11 +107,70 @@ export async function runRunnerTurn({
     return { draft: turnState.draft };
   } finally {
     logger?.event("turn.ui.end");
+    idleWatchdog.clear();
     ui.turnEnd();
     unsubscribe();
   }
 }
 
+function createModelStreamIdleWatchdog({ session, logger, setPhase }) {
+  const timeoutMs = getModelStreamIdleTimeoutMs();
+  let timer = null;
+  let timedOut = false;
+  let rejectIdle = null;
+  const idlePromise = new Promise((_, reject) => {
+    rejectIdle = reject;
+  });
+
+  return {
+    arm(reason) {
+      if (timeoutMs <= 0 || timedOut) return;
+      clearTimer();
+      timer = setTimeout(() => {
+        timedOut = true;
+        setPhase?.("model_idle_timeout");
+        logger?.event("model.stream.idle_timeout", { timeoutMs, reason });
+        try { session.abortRetry?.(); } catch {}
+        try { session.abort?.(); } catch {}
+        rejectIdle(createModelStreamIdleTimeoutError(timeoutMs, reason));
+      }, timeoutMs);
+    },
+    pause: clearTimer,
+    clear: clearTimer,
+    async watch(promise) {
+      const guarded = Promise.resolve(promise);
+      guarded.catch(() => {});
+      return await Promise.race([guarded, idlePromise]);
+    },
+  };
+
+  function clearTimer() {
+    if (!timer) return;
+    clearTimeout(timer);
+    timer = null;
+  }
+}
+
+function createModelStreamIdleTimeoutError(timeoutMs, reason) {
+  const error = new Error(`Model stream idle timeout after ${timeoutMs}ms (${reason}); aborted the current turn`);
+  error.code = MODEL_STREAM_IDLE_TIMEOUT_CODE;
+  return error;
+}
+
+function getModelStreamIdleTimeoutMs() {
+  const raw = process.env.MARCH_MODEL_STREAM_IDLE_TIMEOUT_MS;
+  if (raw === "0" || raw === "false" || raw === "no") return 0;
+  const parsed = raw ? Number.parseInt(raw, 10) : 18000;
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 18000;
+}
+
+function throwIfAssistantEndedWithError(turnState) {
+  if (turnState.lastAssistantStopReason !== "error") return;
+  const error = new Error(turnState.lastAssistantErrorMessage || "Model provider returned an error");
+  error.code = "MODEL_PROVIDER_ERROR";
+  throw error;
+}
+
 function queueMidTurnRecallHints(session, hints, logger) {
   const content = formatRecallHints("assistant", hints);
   if (!content) return;

package/src/cli/args.mjs

@@ -69,6 +69,7 @@ Usage:
   march [options]            (starts REPL)
   march login [provider]     Login to an OAuth provider
   march provider --config    Configure provider credentials
+  march provider remove      Remove a configured provider interactively
   march provider share [id]  Share a provider profile
   march provider accept <token>
   march web [path]       Start the local Web UI session manager

package/src/cli/repl-loop.mjs

@@ -104,6 +104,10 @@ export async function runInteractiveRepl({
       trimmed = templateResult.prompt;
     }
 
+    if (turnActive.viewOnly) {
+      ui.writeln("This session is view-only. Use /session and Take over control before sending prompts.");
+      continue;
+    }
     if (turnActive.turnTask) {
       ui.writeln("This session is still running. Use /session to start or inspect another session.");
       continue;

package/src/cli/startup/app-runtime.mjs

@@ -176,7 +176,10 @@ export async function createCliAppRuntime({ args, config, cwd, argv, stateRoot }
         onNotificationActivation,
       });
     },
-    onActivate: ({ projectId, sessionId }) => outputRouter.setActiveSession(projectId, sessionId, { renderTimeline: loadStoredRenderTimeline(projectMarchDirs.get(projectId), sessionId) }),
+    onActivate: ({ projectId, sessionId, runtime }) => {
+      if (runtime?.projectMarchDir) projectMarchDirs.set(projectId, runtime.projectMarchDir);
+      outputRouter.setActiveSession(projectId, sessionId, { renderTimeline: loadStoredRenderTimeline(projectMarchDirs.get(projectId), sessionId) });
+    },
   });
   runner = workspaceSupervisor.runner;
 

package/src/cli/workspace/command.mjs

@@ -3,6 +3,7 @@ import { resolve } from "node:path";
 import { brightBlack } from "../tui/ui-theme.mjs";
 import { registerProject, listRegisteredProjects } from "../../workspace/project-registry.mjs";
 import { buildWorkspaceSessionSelectItems, listWorkspaceSessions, workspaceSessionSearchText } from "../../workspace/session-index.mjs";
+import { SessionControllerLeaseConflictError } from "../../session/control/controller-lease.mjs";
 
 export const WORKSPACE_SLASH_COMMANDS = [
   {
@@ -93,6 +94,9 @@ export async function handleSessionCommand({ stateRoot, currentProjectId, runner
       ctxRenderActiveSession({ workspaceOutputRouter, projectId: item.project.projectId, sessionId: item.session.id });
       return { handled: true, refreshContextTokens: true, activeChanged: true };
     } catch (err) {
+      if (err instanceof SessionControllerLeaseConflictError) {
+        return await handleSessionControllerConflict({ err, item, workspaceSupervisor, workspaceOutputRouter, ui });
+      }
       ui.writeln(`Error: ${err.message}`);
       return { handled: true };
     }
@@ -101,6 +105,46 @@ export async function handleSessionCommand({ stateRoot, currentProjectId, runner
   return { handled: true };
 }
 
+async function handleSessionControllerConflict({ err, item, workspaceSupervisor, workspaceOutputRouter, ui }) {
+  ui.writeln(err.message);
+  if (!ui.selectList) return { handled: true };
+  const choice = await ui.selectList({
+    items: [
+      { value: "view-only", label: "View only", description: "inspect this session without taking control" },
+      { value: "take-over", label: "Take over control", description: "steal the controller lease for this session" },
+      { value: "cancel", label: "Cancel", description: "leave current controller unchanged" },
+    ],
+    selectedIndex: 0,
+    width: 70,
+    suppressInitialConfirm: true,
+  });
+  if (choice?.value === "view-only") {
+    try {
+      await workspaceSupervisor.viewWorkspaceSession({ project: item.project, session: item.session });
+      ctxRenderActiveSession({ workspaceOutputRouter, projectId: item.project.projectId, sessionId: item.session.id });
+      ui.writeln(`Viewing session: ${item.project.displayName} / ${item.session.name || item.session.id}`);
+      ui.writeln("View-only mode: prompts are disabled until you take over control.");
+      return { handled: true, refreshContextTokens: true, activeChanged: true };
+    } catch (viewErr) {
+      ui.writeln(`Error: ${viewErr.message}`);
+      return { handled: true };
+    }
+  }
+  if (choice?.value !== "take-over") {
+    ui.writeln("Session unchanged.");
+    return { handled: true };
+  }
+  try {
+    await workspaceSupervisor.activateWorkspaceSession({ project: item.project, session: item.session, force: true });
+    ctxRenderActiveSession({ workspaceOutputRouter, projectId: item.project.projectId, sessionId: item.session.id });
+    ui.writeln(`Took over session: ${item.project.displayName} / ${item.session.name || item.session.id}`);
+    return { handled: true, refreshContextTokens: true, activeChanged: true };
+  } catch (takeoverErr) {
+    ui.writeln(`Error: ${takeoverErr.message}`);
+    return { handled: true };
+  }
+}
+
 function annotateWorkspaceItems(items, runtimeSummaries) {
   if (!runtimeSummaries.length) return items;
   const running = new Set(runtimeSummaries.filter((runtime) => runtime.running).map((runtime) => `${runtime.projectId}:${runtime.sessionId}`));

package/src/config/config-json.mjs

@@ -38,6 +38,26 @@ export function upsertProviderProfile({ path = globalConfigJsonPath(), id, type,
   return config;
 }
 
+export function removeProviderProfile({ path = globalConfigJsonPath(), id }) {
+  const config = readConfigJson(path);
+  const providers = config.providers && typeof config.providers === "object" && !Array.isArray(config.providers)
+    ? config.providers
+    : {};
+  const hadProviderProfile = Object.prototype.hasOwnProperty.call(providers, id);
+  const wasSelectedProvider = config.provider === id;
+  if (hadProviderProfile) delete providers[id];
+  if (Object.keys(providers).length) config.providers = providers;
+  else delete config.providers;
+  if (wasSelectedProvider) {
+    delete config.provider;
+    delete config.model;
+    delete config.serviceTier;
+  }
+  if (!hadProviderProfile && !wasSelectedProvider) return false;
+  writeConfigJson(path, config);
+  return true;
+}
+
 export function upsertSharedProviderProfile({ path = globalConfigJsonPath(), id, provider }) {
   const config = readConfigJson(path);
   const providers = config.providers && typeof config.providers === "object" && !Array.isArray(config.providers)

package/src/provider/command.mjs

@@ -2,6 +2,7 @@ import { homedir } from "node:os";
 import { runProviderConfigCommand } from "./config-command.mjs";
 import { runProviderShareCommand } from "./share-command.mjs";
 import { runProviderAcceptCommand } from "./accept-command.mjs";
+import { runProviderRemoveCommand } from "./remove-command.mjs";
 
 export async function runProviderCommand(args, { homeDir = homedir(), stderr = process.stderr } = {}) {
   if (args.providerConfig) return await runProviderConfigCommand({ homeDir });
@@ -16,6 +17,9 @@ export async function runProviderCommand(args, { homeDir = homedir(), stderr = p
   if (args.command.args[0] === "accept") {
     return await runProviderAcceptCommand({ homeDir, token: args.command.args[1] });
   }
-  stderr.write("Usage: march provider --config | march provider share [id] | march provider accept <token>\n");
+  if (args.command.args[0] === "remove" || args.command.args[0] === "uninstall") {
+    return await runProviderRemoveCommand({ homeDir, providerId: args.command.args[1] });
+  }
+  stderr.write("Usage: march provider --config | march provider share [id] | march provider accept <token> | march provider remove\n");
   return 1;
 }

package/src/provider/remove-command.mjs

@@ -0,0 +1,129 @@
+import { createInterface } from "node:readline";
+import { AuthStorage } from "@earendil-works/pi-coding-agent";
+import { globalConfigJsonPath, readConfigJson, removeProviderProfile } from "../config/config-json.mjs";
+import { getMarchAuthPath } from "../auth/storage.mjs";
+import { selectWithKeyboard } from "../cli/input/select-with-keyboard.mjs";
+import { getProviderLabel } from "./presets.mjs";
+
+export async function runProviderRemoveCommand({
+  homeDir,
+  providerId,
+  input = process.stdin,
+  output = process.stdout,
+  select = selectWithKeyboard,
+  confirm = confirmRemoval,
+  authStorage = AuthStorage.create(getMarchAuthPath(homeDir)),
+} = {}) {
+  const removableProviders = listRemovableProviders({ homeDir, authStorage });
+  const selectedProviderId = providerId ?? await selectProviderToRemove({ removableProviders, input, output, select });
+  if (!selectedProviderId) {
+    if (!removableProviders.length) {
+      output.write("No configured providers to remove.\nRun `march provider --config` to add one.\n");
+    } else {
+      output.write("Provider removal cancelled.\n");
+    }
+    return 1;
+  }
+
+  const provider = removableProviders.find((item) => item.id === selectedProviderId) ?? {
+    id: selectedProviderId,
+    label: getProviderLabel(selectedProviderId),
+    sources: [],
+  };
+  const confirmed = await confirm({ input, output, provider });
+  if (!confirmed) {
+    output.write("Provider removal cancelled.\n");
+    return 1;
+  }
+
+  const configRemoved = removeProviderProfile({ path: globalConfigJsonPath(homeDir), id: selectedProviderId });
+  const credentialRemoved = removeProviderCredential({ authStorage, id: selectedProviderId });
+  if (!configRemoved && !credentialRemoved) {
+    output.write(`Provider not found: ${selectedProviderId}\n`);
+    return 1;
+  }
+
+  output.write(`Removed provider: ${provider.label} (${selectedProviderId})\n`);
+  return 0;
+}
+
+export function listRemovableProviders({ homeDir, authStorage }) {
+  const config = readConfigJson(globalConfigJsonPath(homeDir));
+  const providers = config.providers && typeof config.providers === "object" && !Array.isArray(config.providers)
+    ? config.providers
+    : {};
+  const ids = new Set(Object.keys(providers));
+  for (const id of safeListAuthProviders(authStorage)) ids.add(id);
+  return [...ids].sort((a, b) => getProviderLabel(a).localeCompare(getProviderLabel(b))).map((id) => {
+    const sources = [];
+    if (Object.prototype.hasOwnProperty.call(providers, id)) sources.push("config");
+    if (safeHasAuthProvider(authStorage, id)) sources.push("credential");
+    return {
+      id,
+      label: getProviderLabel(id),
+      sources,
+    };
+  });
+}
+
+async function selectProviderToRemove({ removableProviders, input, output, select }) {
+  if (!removableProviders.length) return null;
+  return await select({
+    input,
+    output,
+    message: "Select provider to remove",
+    items: removableProviders.map((provider) => ({
+      label: `${provider.label} (${provider.id})${formatSources(provider.sources)}`,
+      value: provider.id,
+    })),
+  });
+}
+
+function removeProviderCredential({ authStorage, id }) {
+  const existed = safeHasAuthProvider(authStorage, id);
+  if (typeof authStorage.remove === "function") authStorage.remove(id);
+  return existed;
+}
+
+function safeListAuthProviders(authStorage) {
+  if (typeof authStorage.list !== "function") return [];
+  try {
+    const providers = authStorage.list();
+    return Array.isArray(providers) ? providers.filter((id) => typeof id === "string" && id) : [];
+  } catch {
+    return [];
+  }
+}
+
+function safeHasAuthProvider(authStorage, id) {
+  if (typeof authStorage.get === "function") {
+    try {
+      return authStorage.get(id) != null;
+    } catch {
+      return false;
+    }
+  }
+  return safeListAuthProviders(authStorage).includes(id);
+}
+
+function formatSources(sources) {
+  if (!sources.length) return "";
+  return ` — ${sources.join(" + ")}`;
+}
+
+async function confirmRemoval({ input, output, provider }) {
+  const answer = String(await readLine({
+    input,
+    output,
+    prompt: `Remove provider "${provider.label}" (${provider.id})? This deletes local config and credentials. [y/N] `,
+  }) ?? "").trim().toLowerCase();
+  return answer === "y" || answer === "yes";
+}
+
+function readLine({ input = process.stdin, output = process.stdout, prompt }) {
+  const rl = createInterface({ input, output });
+  return new Promise((resolve) => rl.question(prompt, (answer) => {
+    rl.close();
+    resolve(answer);
+  }));
+}

package/src/session/control/controller-lease.mjs

@@ -0,0 +1,149 @@
+import { existsSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync, closeSync } from "node:fs";
+import { randomUUID, createHash } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
+import { getMarchSessionStateDir, normalizeSessionId } from "../state/march-session-state.mjs";
+
+export const DEFAULT_SESSION_CONTROLLER_LEASE_TTL_MS = 30_000;
+export const DEFAULT_SESSION_CONTROLLER_HEARTBEAT_MS = 5_000;
+
+export class SessionControllerLeaseConflictError extends Error {
+  constructor({ sessionId, owner }) {
+    super(formatControllerLeaseConflict({ sessionId, owner }));
+    this.name = "SessionControllerLeaseConflictError";
+    this.code = "SESSION_CONTROLLER_LEASE_CONFLICT";
+    this.sessionId = sessionId;
+    this.owner = owner;
+  }
+}
+
+export function createSessionControllerLeaseManager({
+  instanceId = randomUUID(),
+  pid = process.pid,
+  cwd = process.cwd(),
+  now = () => Date.now(),
+  ttlMs = DEFAULT_SESSION_CONTROLLER_LEASE_TTL_MS,
+  heartbeatMs = DEFAULT_SESSION_CONTROLLER_HEARTBEAT_MS,
+} = {}) {
+  const ownerBase = { instanceId, pid, cwd: resolve(cwd) };
+
+  return {
+    instanceId,
+    acquire(session, options = {}) {
+      const target = resolveControllerLeaseTarget(session);
+      const path = getSessionControllerLeasePath(target);
+      const lease = writeLease({ path, target, ownerBase, now, ttlMs, force: Boolean(options.force) });
+      const heartbeat = heartbeatMs > 0 ? setInterval(() => {
+        try { refreshLease({ path, lease, now, ttlMs }); } catch {}
+      }, heartbeatMs) : null;
+      heartbeat?.unref?.();
+      return {
+        ...lease,
+        path,
+        target,
+        assertOwned() {
+          const current = readLease(path);
+          if (!current || current.owner?.instanceId !== lease.owner.instanceId || current.token !== lease.token || isExpired(current, now())) {
+            throw new SessionControllerLeaseConflictError({ sessionId: target.sessionId, owner: current?.owner ?? null });
+          }
+        },
+        release() {
+          if (heartbeat) clearInterval(heartbeat);
+          releaseLease({ path, lease });
+        },
+      };
+    },
+  };
+}
+
+export function getSessionControllerLeasePath({ sessionId, sessionPath = null, projectMarchDir = null }) {
+  if (sessionPath) {
+    const identity = resolve(sessionPath);
+    const key = createHash("sha256").update(identity).digest("hex").slice(0, 32);
+    return join(dirname(identity), ".march-controller-leases", `${key}.json`);
+  }
+  if (!projectMarchDir || !sessionId) throw new Error("session controller lease requires a session path or project March dir plus session id");
+  return join(getMarchSessionStateDir(projectMarchDir, sessionId), "controller-lease.json");
+}
+
+export function resolveControllerLeaseTarget({ sessionId, sessionPath = null, projectMarchDir = null }) {
+  const id = normalizeSessionId(sessionId);
+  return {
+    sessionId: id,
+    sessionPath: sessionPath ? resolve(sessionPath) : null,
+    projectMarchDir: projectMarchDir ? resolve(projectMarchDir) : null,
+  };
+}
+
+function writeLease({ path, target, ownerBase, now, ttlMs, force }) {
+  mkdirSync(dirname(path), { recursive: true });
+  const current = readLease(path);
+  if (current && !force && !isExpired(current, now()) && current.owner?.instanceId !== ownerBase.instanceId) {
+    throw new SessionControllerLeaseConflictError({ sessionId: target.sessionId, owner: current.owner });
+  }
+  const lease = createLease({ target, ownerBase, now, ttlMs });
+  if (force || current) {
+    writeFileSync(path, JSON.stringify(lease, null, 2), "utf8");
+    return lease;
+  }
+  let fd = null;
+  try {
+    fd = openSync(path, "wx");
+    writeFileSync(fd, JSON.stringify(lease, null, 2), "utf8");
+    return lease;
+  } catch {
+    const raced = readLease(path);
+    if (raced && !isExpired(raced, now())) throw new SessionControllerLeaseConflictError({ sessionId: target.sessionId, owner: raced.owner });
+    try { unlinkSync(path); } catch {}
+    writeFileSync(path, JSON.stringify(lease, null, 2), "utf8");
+    return lease;
+  } finally {
+    if (fd !== null) closeSync(fd);
+  }
+}
+
+function createLease({ target, ownerBase, now, ttlMs }) {
+  const acquiredAtMs = now();
+  return {
+    version: 1,
+    token: randomUUID(),
+    sessionId: target.sessionId,
+    sessionPath: target.sessionPath,
+    owner: ownerBase,
+    acquiredAt: new Date(acquiredAtMs).toISOString(),
+    heartbeatAt: new Date(acquiredAtMs).toISOString(),
+    expiresAt: new Date(acquiredAtMs + ttlMs).toISOString(),
+  };
+}
+
+function refreshLease({ path, lease, now, ttlMs }) {
+  const current = readLease(path);
+  if (!current || current.token !== lease.token || current.owner?.instanceId !== lease.owner.instanceId) return;
+  const heartbeatAtMs = now();
+  writeFileSync(path, JSON.stringify({
+    ...current,
+    heartbeatAt: new Date(heartbeatAtMs).toISOString(),
+    expiresAt: new Date(heartbeatAtMs + ttlMs).toISOString(),
+  }, null, 2), "utf8");
+}
+
+function releaseLease({ path, lease }) {
+  const current = readLease(path);
+  if (!current || current.token !== lease.token || current.owner?.instanceId !== lease.owner.instanceId) return;
+  try { unlinkSync(path); } catch {}
+}
+
+function readLease(path) {
+  if (!existsSync(path)) return null;
+  try { return JSON.parse(readFileSync(path, "utf8")); } catch { return null; }
+}
+
+function isExpired(lease, nowMs) {
+  return Date.parse(lease.expiresAt ?? 0) <= nowMs;
+}
+
+function formatControllerLeaseConflict({ sessionId, owner }) {
+  const parts = [`Session "${sessionId}" is already controlled by another March instance.`];
+  if (owner?.cwd) parts.push(`cwd: ${owner.cwd}`);
+  if (owner?.pid) parts.push(`pid: ${owner.pid}`);
+  return parts.join(" ");
+}

package/src/workspace/session-restore.mjs

@@ -0,0 +1,22 @@
+import { loadMarchSessionStateForPiBackend } from "../session/state/march-session-state.mjs";
+
+export function loadOptionalWorkspaceMarchSessionState({ runtime, session }) {
+  try {
+    return loadWorkspaceMarchSessionState({ runtime, session });
+  } catch {
+    return null;
+  }
+}
+
+export function loadWorkspaceMarchSessionState({ runtime, session }) {
+  const stored = loadMarchSessionStateForPiBackend({
+    projectMarchDir: runtime.projectMarchDir,
+    sessionId: session.id,
+    sessionRef: session.path,
+  });
+  if (!stored) throw new Error(`March session state not found for ${session.id}; refusing partial resume`);
+  if (stored.state.cwd && stored.state.cwd !== runtime.runner.engine.cwd) {
+    throw new Error(`March session state cwd mismatch for ${session.id}: ${stored.state.cwd}`);
+  }
+  return stored.state;
+}

package/src/workspace/supervisor.mjs

@@ -1,12 +1,15 @@
-import { join } from "node:path";
-import { loadMarchSessionStateForPiBackend } from "../session/state/march-session-state.mjs";
+import { basename, join } from "node:path";
+import { createSessionControllerLeaseManager } from "../session/control/controller-lease.mjs";
+import { loadOptionalWorkspaceMarchSessionState, loadWorkspaceMarchSessionState } from "./session-restore.mjs";
+import { createViewOnlyRuntime } from "./view-runtime.mjs";
 
-export function createWorkspaceSessionSupervisor({ initialRuntime, createProjectRuntime, viewSessionState = initialRuntime?.sessionState, onActivate = null }) {
+export function createWorkspaceSessionSupervisor({ initialRuntime, createProjectRuntime, viewSessionState = initialRuntime?.sessionState, onActivate = null, controllerLeases = createSessionControllerLeaseManager({ cwd: initialRuntime?.cwd }) }) {
   if (!initialRuntime?.project?.projectId) throw new Error("initial workspace runtime is missing project metadata");
   if (typeof createProjectRuntime !== "function") throw new Error("createProjectRuntime is required");
 
   const runtimes = new Map();
   let active = initialRuntime;
+  let activeView = null;
   let disposed = false;
   rememberRuntime(initialRuntime);
 
@@ -18,15 +21,21 @@ export function createWorkspaceSessionSupervisor({ initialRuntime, createProject
       if (prop === "activateWorkspaceSessionById") return activateWorkspaceSessionById;
       if (prop === "startNewWorkspaceSession") return startNewWorkspaceSession;
       if (prop === "refreshActiveRuntime") return refreshActiveRuntime;
-      const value = active.runner[prop];
-      return typeof value === "function" ? value.bind(active.runner) : value;
+      if (prop === "viewWorkspaceSession") return viewWorkspaceSession;
+      if (prop === "runTurn") return runActiveTurn;
+      if (prop === "abort") return abortActiveTurn;
+      if (prop === "startNewSession") return startActiveNewSession;
+      if (prop === "switchPiSession") return switchActivePiSession;
+      const current = getActive();
+      const value = current.runner[prop];
+      return typeof value === "function" ? value.bind(current.runner) : value;
     },
     set(_target, prop, value) {
-      active.runner[prop] = value;
+      getActive().runner[prop] = value;
       return true;
     },
     has(_target, prop) {
-      return prop === "dispose" || prop === "getActiveWorkspaceRuntime" || prop === "activateWorkspaceSession" || prop === "activateWorkspaceSessionById" || prop === "startNewWorkspaceSession" || prop === "refreshActiveRuntime" || prop in active.runner;
+      return prop === "dispose" || prop === "getActiveWorkspaceRuntime" || prop === "activateWorkspaceSession" || prop === "activateWorkspaceSessionById" || prop === "startNewWorkspaceSession" || prop === "refreshActiveRuntime" || prop === "viewWorkspaceSession" || prop === "runTurn" || prop === "abort" || prop === "startNewSession" || prop === "switchPiSession" || prop in getActive().runner;
     },
   });
 
@@ -37,6 +46,7 @@ export function createWorkspaceSessionSupervisor({ initialRuntime, createProject
     getRunningTurns,
     getRuntimeSummaries,
     refreshActiveRuntime,
+    viewWorkspaceSession,
     activateWorkspaceSession,
     activateWorkspaceSessionById,
     startNewWorkspaceSession,
@@ -44,7 +54,7 @@ export function createWorkspaceSessionSupervisor({ initialRuntime, createProject
   };
 
   function getActive() {
-    return active;
+    return activeView ?? active;
   }
 
   function hasRunningTurn() {
@@ -65,9 +75,10 @@ export function createWorkspaceSessionSupervisor({ initialRuntime, createProject
   }
 
   function refreshActiveRuntime() {
-    rememberRuntime(active);
-    mirrorSessionState(viewSessionState, active.sessionState);
-    onActivate?.({ projectId: active.project.projectId, sessionId: getRuntimeSessionId(active), runtime: active });
+    const current = getActive();
+    if (!current.viewOnly) rememberRuntime(current);
+    mirrorSessionState(viewSessionState, current.sessionState);
+    onActivate?.({ projectId: current.project.projectId, sessionId: getRuntimeSessionId(current), runtime: current });
   }
 
   async function activateWorkspaceSessionById({ projects = [], projectId, sessionId }) {
@@ -79,17 +90,23 @@ export function createWorkspaceSessionSupervisor({ initialRuntime, createProject
   }
 
   async function startNewWorkspaceSession(project) {
+    activeView = null;
+    const previous = active;
     const runtime = await getIdleRuntimeForProject(project);
     active = runtime;
     const result = await active.runner.startNewSession();
-    if (!result?.cancelled && result?.sessionId) syncSessionState(active, result.sessionId);
+    if (!result?.cancelled && result?.sessionId) {
+      syncSessionState(active, result.sessionId);
+      replaceRuntimeLease(active, acquireRuntimeLease(active, { sessionId: result.sessionId, sessionPath: result.sessionFile ?? null }));
+      releaseIdleRuntimeLease(previous, active);
+    }
     rememberRuntime(active);
     mirrorSessionState(viewSessionState, active.sessionState);
     onActivate?.({ projectId: active.project.projectId, sessionId: getRuntimeSessionId(active), runtime: active, restoreState: null });
     return { runtime: active, result };
   }
 
-  async function activateWorkspaceSession({ project, session = null }) {
+  async function activateWorkspaceSession({ project, session = null, force = false }) {
     if (disposed) throw new Error("workspace supervisor is already disposed");
     if (!project?.projectId) throw new Error("workspace project is required");
 
@@ -97,18 +114,40 @@ export function createWorkspaceSessionSupervisor({ initialRuntime, createProject
     if (!runtime) runtime = await createProjectRuntime(project);
 
     const targetSessionId = session?.id ?? null;
-    let restoreState = null;
-    if (session?.path && getRuntimeSessionId(runtime) !== targetSessionId) {
-      restoreState = loadWorkspaceMarchSessionState({ runtime, session });
-      await runtime.runner.switchPiSession(session.path, restoreState);
+    const lease = targetSessionId ? acquireRuntimeLease(runtime, { sessionId: targetSessionId, sessionPath: session?.path ?? null }, { force }) : null;
+    const previous = active;
+    try {
+      let restoreState = null;
+      if (session?.path && getRuntimeSessionId(runtime) !== targetSessionId) {
+        restoreState = loadWorkspaceMarchSessionState({ runtime, session });
+        await runtime.runner.switchPiSession(session.path, restoreState);
+      }
+      if (targetSessionId) syncSessionState(runtime, targetSessionId);
+
+      replaceRuntimeLease(runtime, lease);
+      releaseIdleRuntimeLease(previous, runtime);
+      activeView = null;
+      active = runtime;
+      rememberRuntime(runtime);
+      mirrorSessionState(viewSessionState, runtime.sessionState);
+      onActivate?.({ projectId: runtime.project.projectId, sessionId: getRuntimeSessionId(runtime), runtime, restoreState });
+      return active;
+    } catch (err) {
+      lease?.release?.();
+      throw err;
     }
-    if (targetSessionId) syncSessionState(runtime, targetSessionId);
+  }
 
-    active = runtime;
-    rememberRuntime(runtime);
-    mirrorSessionState(viewSessionState, runtime.sessionState);
-    onActivate?.({ projectId: runtime.project.projectId, sessionId: getRuntimeSessionId(runtime), runtime, restoreState });
-    return active;
+  function viewWorkspaceSession({ project, session }) {
+    if (disposed) throw new Error("workspace supervisor is already disposed");
+    if (!project?.projectId || !session?.id) throw new Error("workspace session is required");
+    const baseRuntime = findIdleRuntime(project.projectId, { allowSessionRuntime: false }) ?? active;
+    const restoreState = session.path ? loadOptionalWorkspaceMarchSessionState({ runtime: { ...baseRuntime, project, projectMarchDir: join(project.rootPath, ".march") }, session }) : null;
+    const view = createViewOnlyRuntime({ project, session, baseRuntime, restoreState });
+    activeView = view;
+    mirrorSessionState(viewSessionState, view.sessionState);
+    onActivate?.({ projectId: project.projectId, sessionId: session.id, runtime: view, restoreState, viewOnly: true });
+    return view;
   }
 
   async function getIdleRuntimeForProject(project) {
@@ -138,29 +177,100 @@ export function createWorkspaceSessionSupervisor({ initialRuntime, createProject
     disposed = true;
     const uniqueRuntimes = new Set(runtimes.values());
     await Promise.all(Array.from(uniqueRuntimes, async (runtime) => {
+      releaseRuntimeLease(runtime);
       await runtime.runner.dispose?.();
       runtime.memoryStore?.close?.();
     }));
   }
-}
 
-function loadWorkspaceMarchSessionState({ runtime, session }) {
-  const stored = loadMarchSessionStateForPiBackend({
-    projectMarchDir: runtime.projectMarchDir,
-    sessionId: session.id,
-    sessionRef: session.path,
-  });
-  if (!stored) throw new Error(`March session state not found for ${session.id}; refusing partial resume`);
-  if (stored.state.cwd && stored.state.cwd !== runtime.runner.engine.cwd) {
-    throw new Error(`March session state cwd mismatch for ${session.id}: ${stored.state.cwd}`);
+  async function runActiveTurn(...args) {
+    if (activeView) throw new Error("This session is view-only. Use /session and Take over control before sending prompts.");
+    ensureRuntimeLease(active);
+    return await active.runner.runTurn(...args);
+  }
+
+  function abortActiveTurn(...args) {
+    if (activeView) throw new Error("This session is view-only; there is no local turn to abort.");
+    ensureRuntimeLease(active);
+    return active.runner.abort(...args);
+  }
+
+  async function startActiveNewSession(...args) {
+    activeView = null;
+    const result = await active.runner.startNewSession(...args);
+    if (!result?.cancelled && result?.sessionId) {
+      syncSessionState(active, result.sessionId);
+      replaceRuntimeLease(active, acquireRuntimeLease(active, { sessionId: result.sessionId, sessionPath: result.sessionFile ?? null }));
+      rememberRuntime(active);
+      mirrorSessionState(viewSessionState, active.sessionState);
+    }
+    return result;
+  }
+
+  async function switchActivePiSession(sessionPath, restoreState = null, ...args) {
+    activeView = null;
+    const sessionId = sessionIdFromSessionPath(sessionPath);
+    const lease = acquireRuntimeLease(active, { sessionId, sessionPath });
+    try {
+      const result = await active.runner.switchPiSession(sessionPath, restoreState, ...args);
+      if (result?.cancelled) {
+        lease.release?.();
+        return result;
+      }
+      const stats = active.runner.getSessionStats?.() ?? {};
+      syncSessionState(active, stats.sessionId ?? sessionId);
+      replaceRuntimeLease(active, lease);
+      rememberRuntime(active);
+      mirrorSessionState(viewSessionState, active.sessionState);
+      return result;
+    } catch (err) {
+      lease.release?.();
+      throw err;
+    }
+  }
+
+  function acquireRuntimeLease(runtime, session, options = {}) {
+    if (!session?.sessionId) return null;
+    return controllerLeases.acquire({
+      sessionId: session.sessionId,
+      sessionPath: session.sessionPath ?? getRuntimeSessionFile(runtime),
+      projectMarchDir: runtime.projectMarchDir,
+    }, options);
+  }
+
+  function ensureRuntimeLease(runtime) {
+    const sessionId = getRuntimeSessionId(runtime);
+    if (!sessionId) return null;
+    if (!runtime.controllerLease) replaceRuntimeLease(runtime, acquireRuntimeLease(runtime, { sessionId }));
+    runtime.controllerLease.assertOwned();
+    return runtime.controllerLease;
+  }
+
+  function replaceRuntimeLease(runtime, lease) {
+    if (runtime.controllerLease === lease) return;
+    runtime.controllerLease?.release?.();
+    runtime.controllerLease = lease;
+  }
+
+  function releaseRuntimeLease(runtime) {
+    runtime.controllerLease?.release?.();
+    runtime.controllerLease = null;
+  }
+
+  function releaseIdleRuntimeLease(runtime, nextRuntime) {
+    if (!runtime || runtime === nextRuntime || runtime.turnTask) return;
+    releaseRuntimeLease(runtime);
   }
-  return stored.state;
 }
 
 function getRuntimeSessionId(runtime) {
   return runtime.sessionState?.sessionId ?? runtime.runner.getSessionStats?.()?.sessionId ?? null;
 }
 
+function getRuntimeSessionFile(runtime) {
+  return runtime.runner.getSessionStats?.()?.sessionFile ?? null;
+}
+
 function syncSessionState(runtime, sessionId) {
   if (!runtime.sessionState || !sessionId) return;
   runtime.sessionState.sessionId = sessionId;
@@ -176,3 +286,7 @@ function mirrorSessionState(target, source) {
 function runtimeKey(projectId, sessionId = null) {
   return `${projectId}:${sessionId ?? ""}`;
 }
+
+function sessionIdFromSessionPath(sessionPath) {
+  return basename(String(sessionPath)).replace(/\.jsonl?$/i, "");
+}

package/src/workspace/view-runtime.mjs

@@ -0,0 +1,40 @@
+import { join, resolve } from "node:path";
+
+export function createViewOnlyRuntime({ project, session, baseRuntime, restoreState }) {
+  const projectRoot = resolveProjectRoot(project, baseRuntime);
+  const sessionState = {
+    sessionId: session.id,
+    sessionDir: join(projectRoot, ".march", "sessions", session.id),
+  };
+  const runner = {
+    engine: { cwd: projectRoot, turns: restoreState?.turns ?? [] },
+    runtimeState: { engine: { cwd: projectRoot } },
+    getSessionStats: () => ({ sessionId: session.id, sessionFile: session.path ?? null }),
+    estimateContextTokens: () => null,
+    canSwitchPiSession: () => false,
+    runTurn: rejectViewOnlyControl,
+    abort: rejectViewOnlyControl,
+    startNewSession: rejectViewOnlyControl,
+    switchPiSession: rejectViewOnlyControl,
+  };
+  return {
+    ...baseRuntime,
+    project,
+    cwd: projectRoot,
+    currentProject: project.displayName,
+    projectMarchDir: join(projectRoot, ".march"),
+    sessionsRoot: join(projectRoot, ".march", "sessions"),
+    sessionState,
+    runner,
+    turnTask: null,
+    viewOnly: true,
+  };
+}
+
+function rejectViewOnlyControl() {
+  throw new Error("This session is view-only. Use /session and Take over control before sending prompts.");
+}
+
+function resolveProjectRoot(project, fallbackRuntime) {
+  return project?.rootPath ? resolve(project.rootPath) : fallbackRuntime.cwd;
+}