@os-eco/overstory-cli 0.7.7 → 0.7.8

package/README.md

@@ -80,7 +80,7 @@ Every command supports `--json` where noted. Global flags: `-q`/`--quiet`, `--ti
 | Command | Description |
 |---------|-------------|
 | `ov init` | Initialize `.overstory/` and bootstrap os-eco tools (`--yes`, `--name`, `--tools`, `--skip-mulch`, `--skip-seeds`, `--skip-canopy`, `--skip-onboard`, `--json`) |
-| `ov sling <task-id>` | Spawn a worker agent (`--capability`, `--name`, `--spec`, `--files`, `--parent`, `--depth`, `--skip-scout`, `--skip-review`, `--max-agents`, `--dispatch-max-agents`, `--skip-task-check`, `--no-scout-check`, `--runtime`, `--json`) |
+| `ov sling <task-id>` | Spawn a worker agent (`--capability`, `--name`, `--spec`, `--files`, `--parent`, `--depth`, `--skip-scout`, `--skip-review`, `--max-agents`, `--dispatch-max-agents`, `--skip-task-check`, `--no-scout-check`, `--runtime`, `--base-branch`, `--json`) |
 | `ov stop <agent-name>` | Terminate a running agent (`--clean-worktree`, `--json`) |
 | `ov prime` | Load context for orchestrator/agent (`--agent`, `--compact`) |
 | `ov spec write <task-id>` | Write a task specification (`--body`) |
@@ -279,6 +279,106 @@ overstory/
   templates/                      Templates for overlays and hooks
 ```
 
+## Configuration
+
+### Gateway Providers
+
+Route agent API calls through custom gateway endpoints (z.ai, OpenRouter, self-hosted proxies). Configure providers in `.overstory/config.yaml`:
+
+```yaml
+providers:
+  anthropic:
+    type: native
+  zai:
+    type: gateway
+    baseUrl: https://api.z.ai/v1
+    authTokenEnv: ZAI_API_KEY
+  openrouter:
+    type: gateway
+    baseUrl: https://openrouter.ai/api/v1
+    authTokenEnv: OPENROUTER_API_KEY
+models:
+  builder: zai/claude-sonnet-4-6
+  scout: openrouter/openai/gpt-4o
+```
+
+**How it works:** Model refs use `provider/model-id` format. Overstory sets `ANTHROPIC_BASE_URL` to the gateway `baseUrl`, `ANTHROPIC_AUTH_TOKEN` from the env var named in `authTokenEnv`, and `ANTHROPIC_API_KEY=""` to prevent direct Anthropic calls. The agent receives `"sonnet"` as a model alias and Claude Code routes via env vars.
+
+**Environment variable notes:**
+- `ANTHROPIC_AUTH_TOKEN` and `ANTHROPIC_API_KEY` are mutually exclusive per-agent
+- Gateway agents get `ANTHROPIC_API_KEY=""` and `ANTHROPIC_AUTH_TOKEN` from provider config
+- Direct Anthropic API calls (merge resolver, watchdog triage) still need `ANTHROPIC_API_KEY` in the orchestrator env
+
+**Validation:** `ov doctor --category providers` checks reachability, auth tokens, model-provider refs, and tool-use compatibility.
+
+**`ProviderConfig` fields:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | `native` or `gateway` | Yes | Provider type |
+| `baseUrl` | string | Gateway only | API endpoint URL |
+| `authTokenEnv` | string | Gateway only | Env var name holding auth token |
+
+## Troubleshooting
+
+### Coordinator died during startup
+
+This error means the coordinator tmux session exited before the TUI became ready. The most common cause is slow shell initialization.
+
+**Step 1: Measure shell startup time**
+
+```bash
+time zsh -i -c exit   # For zsh
+time bash -i -c exit  # For bash
+```
+
+If startup takes more than 1 second, slow shell init is likely the cause.
+
+**Step 2: Common slow-startup causes**
+
+| Cause | Typical delay | Fix |
+|-------|---------------|-----|
+| oh-my-zsh with many plugins | 1-5s | Reduce plugins, switch to lighter framework (zinit with lazy loading) |
+| nvm (Node Version Manager) | 1-3s | Use `--no-use` + lazy-load nvm, or switch to fnm/volta |
+| pyenv init | 0.5-2s | Lazy-load pyenv |
+| rbenv init | 0.5-1s | Lazy-load rbenv |
+| starship prompt | 0.5-1s | Check starship timings |
+| conda auto-activate | 1-3s | `auto_activate_base: false` in `.condarc` |
+| Homebrew shellenv | 0.5-1s | Cache output instead of evaluating every shell start |
+
+**Step 3: Configure `shellInitDelayMs`** in `.overstory/config.yaml`:
+
+```yaml
+runtime:
+  shellInitDelayMs: 3000
+```
+
+- Default: `0` (no delay)
+- Typical values: `1000`–`5000` depending on shell startup time
+- Values above `30000` (30s) trigger a warning
+- Inserts a delay between tmux session creation and TUI readiness polling
+
+**Step 4: Optimization examples**
+
+Lazy-load nvm (add to `~/.zshrc` or `~/.bashrc`):
+
+```bash
+# Lazy-load nvm — only activates when you first call nvm/node/npm
+export NVM_DIR="$HOME/.nvm"
+nvm() { unset -f nvm node npm npx; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; nvm "$@"; }
+node() { unset -f nvm node npm npx; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; node "$@"; }
+npm()  { unset -f nvm node npm npx; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; npm  "$@"; }
+npx()  { unset -f nvm node npm npx; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; npx  "$@"; }
+```
+
+Reduce oh-my-zsh plugins (edit `~/.zshrc`):
+
+```bash
+# Before: plugins=(git zsh-autosuggestions zsh-syntax-highlighting node npm python ruby rbenv pyenv ...)
+# After: keep only what you use regularly
+plugins=(git)
+```
+
 ## Part of os-eco
 
 Overstory is part of the [os-eco](https://github.com/jayminwest/os-eco) AI agent tooling ecosystem.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.7.7",
+	"version": "0.7.8",
 	"description": "Multi-agent orchestration for AI coding agents — spawn workers in git worktrees via tmux, coordinate through SQLite mail, merge with tiered conflict resolution. Pluggable runtime adapters for Claude Code, Pi, and more.",
 	"author": "Jaymin West",
 	"license": "MIT",

package/src/commands/coordinator.test.ts

@@ -38,6 +38,7 @@ interface TmuxCallTracker {
 		env?: Record<string, string>;
 	}>;
 	isSessionAlive: Array<{ name: string; result: boolean }>;
+	checkSessionState: Array<{ name: string; result: "alive" | "dead" | "no_server" }>;
 	killSession: Array<{ name: string }>;
 	sendKeys: Array<{ name: string; keys: string }>;
 	waitForTuiReady: Array<{ name: string }>;
@@ -68,6 +69,7 @@ function makeFakeTmux(
 	options: {
 		waitForTuiReadyResult?: boolean;
 		ensureTmuxAvailableError?: Error;
+		checkSessionStateMap?: Record<string, "alive" | "dead" | "no_server">;
 	} = {},
 ): {
 	tmux: NonNullable<CoordinatorDeps["_tmux"]>;
@@ -76,6 +78,7 @@ function makeFakeTmux(
 	const calls: TmuxCallTracker = {
 		createSession: [],
 		isSessionAlive: [],
+		checkSessionState: [],
 		killSession: [],
 		sendKeys: [],
 		waitForTuiReady: [],
@@ -97,6 +100,13 @@ function makeFakeTmux(
 			calls.isSessionAlive.push({ name, result: alive });
 			return alive;
 		},
+		checkSessionState: async (name: string): Promise<"alive" | "dead" | "no_server"> => {
+			const stateMap = options.checkSessionStateMap ?? {};
+			// Default: derive from sessionAliveMap for backwards compat
+			const state = stateMap[name] ?? (sessionAliveMap[name] ? "alive" : "dead");
+			calls.checkSessionState.push({ name, result: state });
+			return state;
+		},
 		killSession: async (name: string): Promise<void> => {
 			calls.killSession.push({ name });
 		},
@@ -325,7 +335,11 @@ function makeDeps(
 	sessionAliveMap: Record<string, boolean> = {},
 	watchdogConfig?: { running?: boolean; startSuccess?: boolean; stopSuccess?: boolean },
 	monitorConfig?: { running?: boolean; startSuccess?: boolean; stopSuccess?: boolean },
-	tmuxOptions?: { waitForTuiReadyResult?: boolean; ensureTmuxAvailableError?: Error },
+	tmuxOptions?: {
+		waitForTuiReadyResult?: boolean;
+		ensureTmuxAvailableError?: Error;
+		checkSessionStateMap?: Record<string, "alive" | "dead" | "no_server">;
+	},
 ): {
 	deps: CoordinatorDeps;
 	calls: TmuxCallTracker;
@@ -606,7 +620,7 @@ describe("startCoordinator", () => {
 
 	test("rejects duplicate when coordinator is already running", async () => {
 		// Write an existing active coordinator session
-		const existing = makeCoordinatorSession({ state: "working" });
+		const existing = makeCoordinatorSession({ state: "working", pid: process.pid });
 		saveSessionsToDb([existing]);
 
 		// Mock tmux as alive for the existing session
@@ -623,6 +637,29 @@ describe("startCoordinator", () => {
 		}
 	});
 
+	test("rejects duplicate when pid is null but tmux session is alive", async () => {
+		// Session has null pid (e.g. migrated from older schema) but tmux is alive.
+		// Cannot prove it's a zombie without a pid, so treat as active.
+		const existing = makeCoordinatorSession({ state: "working", pid: null });
+		saveSessionsToDb([existing]);
+
+		const { deps } = makeDeps(
+			{ "overstory-test-project-coordinator": true },
+			undefined,
+			undefined,
+			{ checkSessionStateMap: { "overstory-test-project-coordinator": "alive" } },
+		);
+
+		try {
+			await coordinatorCommand(["start"], deps);
+			expect(true).toBe(false); // Should have thrown
+		} catch (err) {
+			expect(err).toBeInstanceOf(AgentError);
+			const ae = err as AgentError;
+			expect(ae.message).toContain("already running");
+		}
+	});
+
 	test("cleans up dead session and starts new one", async () => {
 		// Write an existing session that claims to be working
 		const deadSession = makeCoordinatorSession({
@@ -656,6 +693,98 @@ describe("startCoordinator", () => {
 		expect(newSession?.id).not.toBe("session-dead-coordinator");
 	});
 
+	test("cleans up zombie session when tmux alive but PID dead", async () => {
+		// Session is "working" in DB, tmux session exists, but the PID is dead
+		const zombieSession = makeCoordinatorSession({
+			id: "session-zombie-coordinator",
+			state: "working",
+			pid: 999999, // Non-existent PID
+		});
+		saveSessionsToDb([zombieSession]);
+
+		// Tmux session is alive (pane exists) but PID 999999 is not running
+		const { deps } = makeDeps(
+			{ "overstory-test-project-coordinator": true },
+			undefined,
+			undefined,
+			{ checkSessionStateMap: { "overstory-test-project-coordinator": "alive" } },
+		);
+
+		const originalSleep = Bun.sleep;
+		Bun.sleep = (() => Promise.resolve()) as typeof Bun.sleep;
+
+		try {
+			await captureStdout(() => coordinatorCommand(["start"], deps));
+		} finally {
+			Bun.sleep = originalSleep;
+		}
+
+		// Zombie session should be cleaned up and new one created
+		const sessions = loadSessionsFromDb();
+		expect(sessions).toHaveLength(1);
+		const newSession = sessions[0];
+		expect(newSession?.state).toBe("booting");
+		expect(newSession?.id).not.toBe("session-zombie-coordinator");
+	});
+
+	test("cleans up stale session when tmux server is not running", async () => {
+		// Session is "booting" in DB but tmux server crashed
+		const staleSession = makeCoordinatorSession({
+			id: "session-stale-coordinator",
+			state: "booting",
+		});
+		saveSessionsToDb([staleSession]);
+
+		// checkSessionState returns no_server
+		const { deps } = makeDeps(
+			{ "overstory-test-project-coordinator": false },
+			undefined,
+			undefined,
+			{ checkSessionStateMap: { "overstory-test-project-coordinator": "no_server" } },
+		);
+
+		const originalSleep = Bun.sleep;
+		Bun.sleep = (() => Promise.resolve()) as typeof Bun.sleep;
+
+		try {
+			await captureStdout(() => coordinatorCommand(["start"], deps));
+		} finally {
+			Bun.sleep = originalSleep;
+		}
+
+		// Stale session cleaned up, new one created
+		const sessions = loadSessionsFromDb();
+		expect(sessions).toHaveLength(1);
+		const newSession = sessions[0];
+		expect(newSession?.state).toBe("booting");
+		expect(newSession?.id).not.toBe("session-stale-coordinator");
+	});
+
+	test("respects shellInitDelayMs config before polling TUI readiness", async () => {
+		// Append shellInitDelayMs to existing config (preserve tier2Enabled etc.)
+		const configPath = join(tempDir, ".overstory", "config.yaml");
+		const existing = await Bun.file(configPath).text();
+		await Bun.write(configPath, `${existing}\nruntime:\n  shellInitDelayMs: 500\n`);
+
+		const { deps } = makeDeps();
+
+		const sleepCalls: number[] = [];
+		const originalSleep = Bun.sleep;
+		Bun.sleep = ((ms: number | Date) => {
+			if (typeof ms === "number") sleepCalls.push(ms);
+			return Promise.resolve();
+		}) as typeof Bun.sleep;
+
+		try {
+			await captureStdout(() => coordinatorCommand(["start"], deps));
+		} finally {
+			Bun.sleep = originalSleep;
+		}
+
+		// The 500ms shell init delay should appear in the sleep calls
+		expect(sleepCalls).toContain(500);
+	});
+
 	test("throws AgentError when tmux is not available", async () => {
 		const { deps } = makeDeps({}, undefined, undefined, {
 			ensureTmuxAvailableError: new AgentError(

package/src/commands/coordinator.ts

@@ -27,7 +27,9 @@ import { createRunStore } from "../sessions/store.ts";
 import { resolveBackend, trackerCliName } from "../tracker/factory.ts";
 import type { AgentSession } from "../types.ts";
 import { isProcessRunning } from "../watchdog/health.ts";
+import type { SessionState } from "../worktree/tmux.ts";
 import {
+	checkSessionState,
 	createSession,
 	ensureTmuxAvailable,
 	isSessionAlive,
@@ -58,6 +60,7 @@ export interface CoordinatorDeps {
 			env?: Record<string, string>,
 		) => Promise<number>;
 		isSessionAlive: (name: string) => Promise<boolean>;
+		checkSessionState: (name: string) => Promise<SessionState>;
 		killSession: (name: string) => Promise<void>;
 		sendKeys: (name: string, keys: string) => Promise<void>;
 		waitForTuiReady: (
@@ -275,6 +278,7 @@ async function startCoordinator(
 	const tmux = deps._tmux ?? {
 		createSession,
 		isSessionAlive,
+		checkSessionState,
 		killSession,
 		sendKeys,
 		waitForTuiReady,
@@ -308,15 +312,29 @@ async function startCoordinator(
 			existing.state !== "completed" &&
 			existing.state !== "zombie"
 		) {
-			const alive = await tmux.isSessionAlive(existing.tmuxSession);
-			if (alive) {
-				throw new AgentError(
-					`Coordinator is already running (tmux: ${existing.tmuxSession}, since: ${existing.startedAt})`,
-					{ agentName: COORDINATOR_NAME },
-				);
+			const sessionState = await tmux.checkSessionState(existing.tmuxSession);
+
+			if (sessionState === "alive") {
+				// Tmux session exists -- but is the process inside still running?
+				// A crashed Claude Code leaves a zombie tmux pane that blocks retries.
+				if (existing.pid !== null && !isProcessRunning(existing.pid)) {
+					// Zombie: tmux pane exists but agent process has exited.
+					// Kill the empty session and reclaim the slot.
+					await tmux.killSession(existing.tmuxSession);
+					store.updateState(COORDINATOR_NAME, "completed");
+				} else {
+					// Either the process is genuinely running (pid alive), or pid is null
+					// (e.g. sessions migrated from an older schema). In both cases we
+					// cannot prove the session is a zombie, so treat it as active.
+					throw new AgentError(
+						`Coordinator is already running (tmux: ${existing.tmuxSession}, since: ${existing.startedAt})`,
+						{ agentName: COORDINATOR_NAME },
+					);
+				}
+			} else {
+				// Session is dead or tmux server is not running -- clean up stale DB entry.
+				store.updateState(COORDINATOR_NAME, "completed");
 			}
-			// Session recorded but tmux is dead — mark as completed and continue
-			store.updateState(COORDINATOR_NAME, "completed");
 		}
 
 		// Resolve model and runtime early (needed for deployConfig and spawn)
@@ -413,6 +431,12 @@ async function startCoordinator(
 
 		store.upsert(session);
 
+		// Give slow shells time to finish initializing before polling for TUI readiness.
+		const shellDelay = config.runtime?.shellInitDelayMs ?? 0;
+		if (shellDelay > 0) {
+			await Bun.sleep(shellDelay);
+		}
+
 		// Wait for Claude Code TUI to render before sending input
 		const tuiReady = await tmux.waitForTuiReady(tmuxSession, (content) =>
 			runtime.detectReady(content),
@@ -423,8 +447,13 @@ async function startCoordinator(
 			if (!alive) {
 				// Clean up the stale session record
 				store.updateState(COORDINATOR_NAME, "completed");
+				const sessionState = await tmux.checkSessionState(tmuxSession);
+				const detail =
+					sessionState === "no_server"
+						? "The tmux server is no longer running. It may have crashed or been killed externally."
+						: "The Claude Code process may have crashed or exited immediately. Check tmux logs or try running the claude command manually.";
 				throw new AgentError(
-					`Coordinator tmux session "${tmuxSession}" died during startup. The Claude Code process may have crashed or exited immediately. Check tmux logs or try running the claude command manually.`,
+					`Coordinator tmux session "${tmuxSession}" died during startup. ${detail}`,
 					{ agentName: COORDINATOR_NAME },
 				);
 			}
@@ -512,6 +541,7 @@ async function stopCoordinator(opts: { json: boolean }, deps: CoordinatorDeps =
 	const tmux = deps._tmux ?? {
 		createSession,
 		isSessionAlive,
+		checkSessionState,
 		killSession,
 		sendKeys,
 		waitForTuiReady,
@@ -626,6 +656,7 @@ async function statusCoordinator(
 	const tmux = deps._tmux ?? {
 		createSession,
 		isSessionAlive,
+		checkSessionState,
 		killSession,
 		sendKeys,
 		waitForTuiReady,

package/src/commands/costs.test.ts

@@ -796,6 +796,7 @@ describe("costsCommand", () => {
 				cacheCreationTokens: 100,
 				estimatedCostUsd: 0.15,
 				modelUsed: "claude-sonnet-4-5",
+				runId: null,
 				createdAt: new Date().toISOString(),
 			});
 			metricsStore.close();
@@ -853,6 +854,7 @@ describe("costsCommand", () => {
 				cacheCreationTokens: 100,
 				estimatedCostUsd: 0.15,
 				modelUsed: "claude-sonnet-4-5",
+				runId: null,
 				createdAt: new Date().toISOString(),
 			});
 			metricsStore.close();
@@ -937,6 +939,7 @@ describe("costsCommand", () => {
 				cacheCreationTokens: 0,
 				estimatedCostUsd: 0.15,
 				modelUsed: "claude-sonnet-4-5",
+				runId: null,
 				createdAt: new Date().toISOString(),
 			});
 			metricsStore.recordSnapshot({
@@ -947,6 +950,7 @@ describe("costsCommand", () => {
 				cacheCreationTokens: 0,
 				estimatedCostUsd: 0.25,
 				modelUsed: "claude-sonnet-4-5",
+				runId: null,
 				createdAt: new Date().toISOString(),
 			});
 			metricsStore.close();
@@ -997,6 +1001,7 @@ describe("costsCommand", () => {
 				cacheCreationTokens: 0,
 				estimatedCostUsd: 0.3,
 				modelUsed: "claude-sonnet-4-5",
+				runId: null,
 				createdAt: new Date().toISOString(),
 			});
 			metricsStore.close();

package/src/commands/costs.ts

@@ -367,7 +367,7 @@ async function executeCosts(opts: CostsOpts): Promise<void> {
 		const { store: sessionStore } = openSessionStore(overstoryDir);
 
 		try {
-			const snapshots = metricsStore.getLatestSnapshots();
+			const snapshots = metricsStore.getLatestSnapshots(runId ?? undefined);
 			if (snapshots.length === 0) {
 				if (json) {
 					jsonOutput("costs", {

package/src/commands/log.ts

@@ -583,6 +583,7 @@ async function runLog(opts: {
 							const cost = estimateCost(usage);
 							const metricsDbPath = join(config.project.root, ".overstory", "metrics.db");
 							const metricsStore = createMetricsStore(metricsDbPath);
+							const agentSession = getAgentSession(config.project.root, opts.agent);
 							metricsStore.recordSnapshot({
 								agentName: opts.agent,
 								inputTokens: usage.inputTokens,
@@ -591,6 +592,7 @@ async function runLog(opts: {
 								cacheCreationTokens: usage.cacheCreationTokens,
 								estimatedCostUsd: cost,
 								modelUsed: usage.modelUsed,
+								runId: agentSession?.runId ?? null,
 								createdAt: new Date().toISOString(),
 							});
 							metricsStore.close();

package/src/commands/sling.test.ts

@@ -1,8 +1,13 @@
-import { describe, expect, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { realpathSync } from "node:fs";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { resolveModel, resolveProviderEnv } from "../agents/manifest.ts";
 import { HierarchyError } from "../errors.ts";
 import { ClaudeRuntime } from "../runtimes/claude.ts";
 import { getRuntime } from "../runtimes/registry.ts";
+import { cleanupTempDir, createTempGitRepo } from "../test-helpers.ts";
 import type { AgentManifest, OverstoryConfig } from "../types.ts";
 import {
 	type AutoDispatchOptions,
@@ -15,6 +20,7 @@ import {
 	checkRunSessionLimit,
 	checkTaskLock,
 	extractMulchRecordIds,
+	getCurrentBranch,
 	inferDomainsFromFiles,
 	isRunningAsRoot,
 	parentHasScouts,
@@ -1274,3 +1280,59 @@ describe("extractMulchRecordIds", () => {
 		expect(result).toContainEqual({ id: "mx-2ce43d", domain: "typescript" });
 	});
 });
+
+describe("getCurrentBranch", () => {
+	let repoDir: string;
+
+	beforeEach(async () => {
+		repoDir = realpathSync(await createTempGitRepo());
+	});
+
+	afterEach(async () => {
+		await cleanupTempDir(repoDir);
+	});
+
+	test("returns the current branch name", async () => {
+		const branch = await getCurrentBranch(repoDir);
+		expect(branch).toMatch(/^(main|master)$/);
+	});
+
+	test("returns feature branch name after checkout", async () => {
+		const proc = Bun.spawn(["git", "checkout", "-b", "feature/test-branch"], {
+			cwd: repoDir,
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		await proc.exited;
+		const branch = await getCurrentBranch(repoDir);
+		expect(branch).toBe("feature/test-branch");
+	});
+
+	test("returns null for detached HEAD", async () => {
+		const hashProc = Bun.spawn(["git", "rev-parse", "HEAD"], {
+			cwd: repoDir,
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		const hash = (await new Response(hashProc.stdout).text()).trim();
+		await hashProc.exited;
+		const proc = Bun.spawn(["git", "checkout", hash], {
+			cwd: repoDir,
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		await proc.exited;
+		const branch = await getCurrentBranch(repoDir);
+		expect(branch).toBeNull();
+	});
+
+	test("returns null for non-git directory", async () => {
+		const tmpDir = realpathSync(await mkdtemp(join(tmpdir(), "overstory-notgit-")));
+		try {
+			const branch = await getCurrentBranch(tmpDir);
+			expect(branch).toBeNull();
+		} finally {
+			await cleanupTempDir(tmpDir);
+		}
+	});
+});

package/src/commands/sling.ts

@@ -124,6 +124,7 @@ export interface SlingOptions {
 	dispatchMaxAgents?: string;
 	runtime?: string;
 	noScoutCheck?: boolean;
+	baseBranch?: string;
 }
 
 export interface AutoDispatchOptions {
@@ -389,6 +390,28 @@ export function extractMulchRecordIds(primeText: string): Array<{ id: string; do
 	return results;
 }
 
+/**
+ * Get the current git branch name for the repo at the given path.
+ *
+ * Returns null if in detached HEAD state, the directory is not a git repo,
+ * or git exits non-zero.
+ *
+ * @param repoRoot - Absolute path to the git repository root
+ */
+export async function getCurrentBranch(repoRoot: string): Promise<string | null> {
+	const proc = Bun.spawn(["git", "rev-parse", "--abbrev-ref", "HEAD"], {
+		cwd: repoRoot,
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const [stdout, exitCode] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+	if (exitCode !== 0) return null;
+	const branch = stdout.trim();
+	// "HEAD" is returned when in detached HEAD state
+	if (branch === "HEAD" || branch === "") return null;
+	return branch;
+}
+
 /**
  * Entry point for `ov sling <task-id> [flags]`.
  *
@@ -658,11 +681,17 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 		const worktreeBaseDir = join(config.project.root, config.worktrees.baseDir);
 		await mkdir(worktreeBaseDir, { recursive: true });
 
+		// Resolve base branch: --base-branch flag > current HEAD > config.project.canonicalBranch
+		const baseBranch =
+			opts.baseBranch ??
+			(await getCurrentBranch(config.project.root)) ??
+			config.project.canonicalBranch;
+
 		const { path: worktreePath, branch: branchName } = await createWorktree({
 			repoRoot: config.project.root,
 			baseDir: worktreeBaseDir,
 			agentName: name,
-			baseBranch: config.project.canonicalBranch,
+			baseBranch,
 			taskId: taskId,
 		});
 
@@ -862,7 +891,13 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 			runStore.close();
 		}
 
-		// 13b. Wait for Claude Code TUI to render before sending input.
+		// 13b. Give slow shells time to finish initializing before polling for TUI readiness.
+		const shellDelay = config.runtime?.shellInitDelayMs ?? 0;
+		if (shellDelay > 0) {
+			await Bun.sleep(shellDelay);
+		}
+
+		// Wait for Claude Code TUI to render before sending input.
 		// Polling capture-pane is more reliable than a fixed sleep because
 		// TUI init time varies by machine load and model state.
 		await waitForTuiReady(tmuxSessionName, (content) => runtime.detectReady(content));