@generativereality/cctabs 0.1.1 → 0.1.3

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cctabs",
   "description": "Claude Code tab manager. Terminal tabs as the UI, no tmux. Claude can orchestrate its own sibling sessions.",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "author": {
     "name": "generativereality",
     "url": "https://cctabs.com"

package/dist/index.js

@@ -10,7 +10,7 @@ import { consola } from "consola";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
 //#region package.json
 var name = "@generativereality/cctabs";
-var version = "0.1.1";
+var version = "0.1.3";
 var description = "Claude Code tab manager. Terminal tabs as the UI, no tmux.";
 var package_default = {
 	name,
@@ -28,10 +28,10 @@ var package_default = {
 		"build": "tsdown",
 		"typecheck": "tsc --noEmit",
 		"lint": "eslint src/",
-		"check": "bun run typecheck && bun run build",
+		"check": "npm run typecheck && npm run build",
 		"release": "bumpp && npm publish",
 		"sync-plugin": "bash scripts/sync-plugin.sh",
-		"prepack": "bash scripts/sync-plugin.sh --check && bun run build"
+		"prepack": "bash scripts/sync-plugin.sh --check && npm run build"
 	},
 	keywords: [
 		"claude-code",
@@ -206,7 +206,9 @@ var WaveAdapter = class {
 			const out = execFileSync("wsh", [
 				"blocks",
 				"list",
-				"--json"
+				"--json",
+				"--timeout",
+				"15000"
 			], { encoding: "utf-8" });
 			return JSON.parse(out);
 		} catch {
@@ -222,6 +224,16 @@ var WaveAdapter = class {
 			`-${lastN}`
 		], { encoding: "utf-8" }).stdout ?? "";
 	}
+	/** Poll scrollback to confirm it really is empty (block has no live shell).
+	* A freshly-opened tab may briefly have empty scrollback before the prompt
+	* renders, so poll a few times before declaring the block dead. */
+	async confirmScrollbackEmpty(blockId, attempts = 3, intervalMs = 500) {
+		for (let i = 0; i < attempts; i++) {
+			if (this.scrollback(blockId, 10).trim()) return false;
+			if (i < attempts - 1) await sleep(intervalMs);
+		}
+		return true;
+	}
 	/** Detect whether a Claude session is running in a terminal block */
 	detectSessionStatus(blockId) {
 		const tail = this.scrollback(blockId, 10);
@@ -261,7 +273,7 @@ var WaveAdapter = class {
 		}
 		return true;
 	}
-	async waitForNewBlock(beforeIds, timeoutMs = 5e3) {
+	async waitForNewBlock(beforeIds, timeoutMs = 15e3) {
 		const deadline = Date.now() + timeoutMs;
 		while (Date.now() < deadline) {
 			await sleep(250);
@@ -343,9 +355,12 @@ var WaveAdapter = class {
 	}
 	resolveTab(query, tabsById, tabNames) {
 		const q = query.toLowerCase();
-		return [...tabsById.keys()].filter((tid) => {
+		const ids = [...tabsById.keys()];
+		const exact = ids.filter((tid) => (tabNames.get(tid) ?? "").toLowerCase() === q);
+		if (exact.length > 0) return exact;
+		return ids.filter((tid) => {
 			const name = tabNames.get(tid) ?? "";
-			return name.toLowerCase() === q || tid.startsWith(query) || name.toLowerCase().startsWith(q);
+			return tid.startsWith(query) || name.toLowerCase().startsWith(q);
 		});
 	}
 	resolveBlock(query, blocks) {
@@ -353,10 +368,11 @@ var WaveAdapter = class {
 	}
 	resolveWorkspace(workspaces, query) {
 		const q = query.toLowerCase();
-		return workspaces.filter(({ workspacedata: wd }) => {
+		const exact = workspaces.filter(({ workspacedata: wd }) => (wd.name ?? "").toLowerCase() === q);
+		return (exact.length > 0 ? exact : workspaces.filter(({ workspacedata: wd }) => {
 			const name = wd.name ?? "";
-			return name.toLowerCase() === q || wd.oid.startsWith(query) || name.toLowerCase().startsWith(q);
-		}).map((w) => ({
+			return wd.oid.startsWith(query) || name.toLowerCase().startsWith(q);
+		})).map((w) => ({
 			data: w.workspacedata,
 			windowId: w.windowid
 		}));
@@ -649,9 +665,11 @@ const newCommand = define({
 });
 //#endregion
 //#region src/core/session.ts
-/** Convert an absolute path to Claude's project slug (/ and . → -) */
+/** Convert an absolute path to Claude Code's project slug.
+* Claude Code replaces any non-alphanumeric character (spaces, /, ., etc.) with '-'.
+* Hyphens are preserved. Example: "/Users/me/Remember This" → "-Users-me-Remember-This". */
 function pathToProjectSlug(dir) {
-	return resolve(dir).replace(/[/.]/g, "-");
+	return resolve(dir).replace(/[^A-Za-z0-9-]/g, "-");
 }
 /** Find the most recent .jsonl session file in a Claude project directory */
 function latestJsonlIn(projectDir) {
@@ -745,6 +763,72 @@ function findSessionsByName(dir, name) {
 	return matches.sort((a, b) => b.mtime - a.mtime);
 }
 /**
+* Like findSessionsByName, but searches every project directory under
+* ~/.claude/projects. Each match carries the cwd recorded in the session.
+* Used by `cctabs restore` so callers don't have to guess the right dir.
+*/
+function findSessionsByNameGlobally(name) {
+	const projectsRoot = join(homedir(), ".claude", "projects");
+	if (!existsSync(projectsRoot)) return [];
+	const matches = [];
+	for (const slug of readdirSync(projectsRoot)) {
+		const projectDir = join(projectsRoot, slug);
+		let isDir = false;
+		try {
+			isDir = statSync(projectDir).isDirectory();
+		} catch {
+			continue;
+		}
+		if (!isDir) continue;
+		const files = readdirSync(projectDir).filter((f) => extname(f) === ".jsonl");
+		for (const f of files) {
+			const fullPath = join(projectDir, f);
+			try {
+				const lines = readFileSync(fullPath, "utf-8").split("\n");
+				let currentTitle = "";
+				let cwd = "";
+				let firstPrompt = "";
+				let lastActivity = "";
+				for (const line of lines) {
+					if (!line.trim()) continue;
+					try {
+						const entry = JSON.parse(line);
+						if (entry.customTitle !== void 0) currentTitle = entry.customTitle;
+						if (!cwd && typeof entry.cwd === "string") cwd = entry.cwd;
+						if (!firstPrompt && entry.type === "user" && entry.message?.content) {
+							const text = typeof entry.message.content === "string" ? entry.message.content : entry.message.content.find((c) => c.type === "text")?.text ?? "";
+							if (text.startsWith("<")) continue;
+							firstPrompt = text.slice(0, 120).replace(/\n/g, " ").trim();
+							if (text.length > 120) firstPrompt += "…";
+						}
+						if (entry.message?.role === "assistant" && entry.message?.content) {
+							const parts = Array.isArray(entry.message.content) ? entry.message.content : [{
+								type: "text",
+								text: entry.message.content
+							}];
+							for (const p of parts) if (p.type === "text" && p.text?.trim()) {
+								lastActivity = p.text.slice(0, 120).replace(/\n/g, " ").trim();
+								if (p.text.length > 120) lastActivity += "…";
+							}
+						}
+					} catch {}
+				}
+				if (currentTitle !== name || !cwd) continue;
+				const stat = statSync(fullPath);
+				matches.push({
+					id: basename(f, ".jsonl"),
+					mtime: stat.mtimeMs,
+					size: stat.size,
+					firstPrompt,
+					lastActivity,
+					dir: cwd
+				});
+			} catch {}
+		}
+	}
+	return matches.sort((a, b) => b.mtime - a.mtime);
+}
+/**
 * List all unique session names (customTitle) in a project directory.
 * Used to show available names when a resume lookup fails.
 */
@@ -849,7 +933,8 @@ const resumeCommand = define({
 				process.exit(1);
 			}
 			const tabId = matchingTabs[0];
-			const termBlock = (tabsById.get(tabId) ?? []).find((b) => b.view === "term");
+			const blocks = tabsById.get(tabId) ?? [];
+			const termBlock = blocks.find((b) => b.view === "term");
 			if (!termBlock) {
 				consola.error(`No terminal block found in tab '${name}'`);
 				process.exit(1);
@@ -860,7 +945,20 @@ const resumeCommand = define({
 				consola.warn(`Claude is already running in tab "${name}" (${status}) — skipping resume`);
 				process.exit(0);
 			}
-			if (status === "unknown") consola.warn(`Scrollback unavailable for tab "${name}" — cannot confirm shell is ready. Proceeding anyway.`);
+			if (status === "unknown") {
+				if (await adapter.confirmScrollbackEmpty(termBlock.blockid)) {
+					consola.info(`Tab "${name}" has no live shell (empty scrollback) — recreating`);
+					for (const b of blocks) adapter.deleteBlock(b.blockid);
+					adapter.closeSocket();
+					const newTabId = await openSession({
+						tabName: name,
+						dir,
+						claudeCmd: `claude --resume ${sessionId} --name ${JSON.stringify(name)}`
+					});
+					consola.success(`Tab "${name}" [${newTabId.slice(0, 8)}] → claude --resume ${sessionId.slice(0, 8)}… at ${dir} (recreated)`);
+					return;
+				}
+			}
 			const extraFlags = loadConfig().claude.flags.join(" ");
 			const cmd = `cd ${JSON.stringify(dir)} && claude${extraFlags ? " " + extraFlags : ""} --resume ${sessionId} --name ${JSON.stringify(name)}\r`;
 			await adapter.sendInput(termBlock.blockid, cmd);
@@ -1200,20 +1298,15 @@ const configCommand = define({
 //#region src/commands/restore.ts
 const restoreCommand = define({
 	name: "restore",
-	description: "Resume Claude sessions in all terminal-state tabs (e.g. after a reboot)",
-	args: {
-		dir: {
-			type: "positional",
-			description: "Working directory (default: cwd)"
-		},
-		dry: {
-			type: "boolean",
-			short: "n",
-			description: "Show what would be resumed without actually doing it"
-		}
-	},
+	description: "Resume Claude sessions in all terminal-state tabs (e.g. after a reboot). Searches every Claude project dir by default; pass an explicit dir to scope the search.",
+	args: { dry: {
+		type: "boolean",
+		short: "n",
+		description: "Show what would be resumed without actually doing it"
+	} },
 	async run(ctx) {
-		const dir = resolve((ctx.positionals[1] ?? process.cwd()).replace(/^~/, homedir()));
+		const rawDir = ctx.positionals[1];
+		const scopedDir = rawDir ? resolve(rawDir.replace(/^~/, homedir())) : null;
 		const dryRun = ctx.values.dry;
 		const adapter = requireWaveAdapter();
 		const { tabsById, workspaces, tabNames } = await adapter.getAllData();
@@ -1243,35 +1336,72 @@ const restoreCommand = define({
 		consola.info(`Found ${toResume.length} tab(s) to restore:`);
 		const extraFlags = loadConfig().claude.flags.join(" ");
 		const results = [];
+		const toRecreate = [];
 		for (const tab of toResume) {
-			const sessions = findSessionsByName(dir, tab.name);
-			if (sessions.length === 0) {
-				consola.log(`  ${tab.name} — no session named "${tab.name}" found, skipping`);
-				results.push({
-					name: tab.name,
-					result: "no matching session"
-				});
-				continue;
-			}
-			if (sessions.length > 1) {
-				consola.log(`  ${tab.name} — multiple sessions found, skipping (use cctabs resume --session to pick one)`);
-				results.push({
-					name: tab.name,
-					result: "ambiguous (multiple sessions)"
-				});
-				continue;
+			let sessionId = null;
+			let sessionDir = null;
+			if (scopedDir) {
+				const sessions = findSessionsByName(scopedDir, tab.name);
+				if (sessions.length === 0) {
+					consola.log(`  ${tab.name} — no session named "${tab.name}" found in ${scopedDir}, skipping`);
+					results.push({
+						name: tab.name,
+						result: "no matching session"
+					});
+					continue;
+				}
+				if (sessions.length > 1) {
+					consola.log(`  ${tab.name} — multiple sessions found, skipping (use cctabs resume --session to pick one)`);
+					results.push({
+						name: tab.name,
+						result: "ambiguous (multiple sessions)"
+					});
+					continue;
+				}
+				sessionId = sessions[0].id;
+				sessionDir = scopedDir;
+			} else {
+				const sessions = findSessionsByNameGlobally(tab.name);
+				if (sessions.length === 0) {
+					consola.log(`  ${tab.name} — no session named "${tab.name}" found in any project, skipping`);
+					results.push({
+						name: tab.name,
+						result: "no matching session"
+					});
+					continue;
+				}
+				if (sessions.length > 1) consola.log(`  ${tab.name} — multiple sessions found across projects, picking newest (${sessions[0].dir})`);
+				sessionId = sessions[0].id;
+				sessionDir = sessions[0].dir;
 			}
-			const sessionId = sessions[0].id;
 			if (dryRun) {
-				consola.log(`  ${tab.name} → would resume session ${sessionId.slice(0, 8)}…`);
+				const mode = tab.status === "unknown" ? "recreate" : "send";
+				consola.log(`  ${tab.name} → would ${mode} session ${sessionId.slice(0, 8)}… in ${sessionDir}`);
 				results.push({
 					name: tab.name,
 					result: `dry run: ${sessionId.slice(0, 8)}…`
 				});
 				continue;
 			}
-			consola.log(`  ${tab.name} → resuming session ${sessionId.slice(0, 8)}…`);
-			const cmd = `cd ${JSON.stringify(dir)} && claude${extraFlags ? " " + extraFlags : ""} --resume ${sessionId} --name ${JSON.stringify(tab.name)}\r`;
+			if (tab.status === "unknown") {
+				if (await adapter.confirmScrollbackEmpty(tab.blockId)) {
+					const blockIds = (tabsById.get(tab.tabId) ?? []).map((b) => b.blockid);
+					toRecreate.push({
+						name: tab.name,
+						sessionId,
+						sessionDir,
+						blockIds,
+						tabId: tab.tabId
+					});
+					results.push({
+						name: tab.name,
+						result: "queued for recreate"
+					});
+					continue;
+				}
+			}
+			consola.log(`  ${tab.name} → resuming session ${sessionId.slice(0, 8)}… in ${sessionDir} (send)`);
+			const cmd = `cd ${JSON.stringify(sessionDir)} && claude${extraFlags ? " " + extraFlags : ""} --resume ${sessionId} --name ${JSON.stringify(tab.name)}\r`;
 			await adapter.sendInput(tab.blockId, cmd);
 			await new Promise((r) => setTimeout(r, 500));
 			results.push({
@@ -1293,7 +1423,23 @@ const restoreCommand = define({
 				}
 			}
 		}
-		adapter.closeSocket();
+		if (!dryRun && toRecreate.length) {
+			for (const t of toRecreate) for (const bid of t.blockIds) adapter.deleteBlock(bid);
+			adapter.closeSocket();
+			consola.info(`Recreating ${toRecreate.length} dead tab(s)…`);
+			for (const t of toRecreate) try {
+				const newTabId = await openSession({
+					tabName: t.name,
+					dir: t.sessionDir,
+					claudeCmd: `claude --resume ${t.sessionId} --name ${JSON.stringify(t.name)}`
+				});
+				const r = results.find((x) => x.name === t.name);
+				r.result = `✔ recreated [${newTabId.slice(0, 8)}]`;
+			} catch (err) {
+				const r = results.find((x) => x.name === t.name);
+				r.result = `✘ recreate failed: ${err.message}`;
+			}
+		} else adapter.closeSocket();
 		console.log("\nRestore summary:");
 		for (const r of results) console.log(`  ${r.name}: ${r.result}`);
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@generativereality/cctabs",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Claude Code tab manager. Terminal tabs as the UI, no tmux.",
   "type": "module",
   "bin": {
@@ -16,10 +16,10 @@
     "build": "tsdown",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src/",
-    "check": "bun run typecheck && bun run build",
+    "check": "npm run typecheck && npm run build",
     "release": "bumpp && npm publish",
     "sync-plugin": "bash scripts/sync-plugin.sh",
-    "prepack": "bash scripts/sync-plugin.sh --check && bun run build"
+    "prepack": "bash scripts/sync-plugin.sh --check && npm run build"
   },
   "keywords": [
     "claude-code",

package/skills/cctabs/SKILL.md

@@ -7,6 +7,20 @@ You are managing Claude Code sessions using the `cctabs` CLI.
 
 **Important:** "tabs" here means **terminal tabs** (e.g. Wave Terminal tabs), NOT browser tabs. Each terminal tab runs its own Claude Code session. This skill is for managing those terminal-based Claude Code sessions — not for browser automation.
 
+## Before you spawn anything: is cctabs the right tool?
+
+cctabs is excellent for:
+- **Multiple human-driven sessions** on unrelated projects (check on a deploy here, draft a blog post there, monitor a long-running task somewhere else).
+- **Genuinely orthogonal parallel work** where each tab touches a disjoint file set (e.g. each tab writes to its own new directory, or each tab works on a different repo).
+- **Long-running background sessions** that the user wants to check on later (builds, scrapes, benchmarks).
+
+cctabs is the WRONG tool for:
+- **Interconnected parallel work within one session.** If you're orchestrating and farming out subtasks that all modify the same evolving codebase, tabs hide each other's commits from each other. By the time they're done, you have three diverged branches that need manual merge, and any intervening change on `main`/`next` can make the merge structurally painful. **Use the Agent tool instead** — subagents share your filesystem and git state, commit in place, and surface their result back to you.
+- **Sequential dependencies.** If B depends on A's commits landing, don't parallelize — run A to completion first, then B.
+- **Work that touches the same files as the current orchestrator session.** Commits race, branches diverge, conflicts multiply.
+
+A good test: *"If both tabs finish successfully, will merging their output be trivial?"* If yes, cctabs is fine. If no (or you can't tell), do it sequentially or use subagents.
+
 ## First: Ensure cctabs is available
 
 ```bash
@@ -27,6 +41,29 @@ Do not modify PATH or npm configuration beyond this.
 
 Each Claude Code session runs in its own **terminal tab**. `cctabs` lets you — and other Claude Code sessions — introspect and orchestrate the full session fleet.
 
+## When to Use Worktrees
+
+**Use `--worktree` whenever a tab will edit code on a branch that differs from the main working tree.** This includes:
+- Fixing CI on a PR (`cctabs new fix-1789 ~/Dev/myapp --worktree`)
+- Working on a feature branch while the main checkout runs a dev server
+- Any task where multiple tabs might checkout different branches
+
+Without `--worktree`, all tabs share the same working directory. If two tabs checkout different branches, they stomp on each other's files — causing silent conflicts, lost changes, and broken dev servers.
+
+**Rule of thumb:**
+- **Read-only / docs / coordination** → no worktree needed (stays on current branch)
+- **Editing code on a different branch** → always `--worktree`
+
+```bash
+# ❌ WRONG — two tabs checking out different branches in the same directory
+cctabs new fix-auth ~/Dev/myapp --prompt "checkout PR #101 and fix lint"
+cctabs new fix-api ~/Dev/myapp --prompt "checkout PR #102 and fix tests"
+
+# ✅ RIGHT — each gets its own isolated copy
+cctabs new fix-auth ~/Dev/myapp --worktree --prompt "checkout PR #101 and fix lint"
+cctabs new fix-api ~/Dev/myapp --worktree --prompt "checkout PR #102 and fix tests"
+```
+
 ## Quick Reference
 
 ```bash
@@ -34,6 +71,7 @@ cctabs sessions                          # list all tabs with session status
 cctabs list                              # list all workspaces, tabs, and blocks
 cctabs new <name> [dir] [-w workspace] [-p "prompt"] [-f file]  # new tab + claude
 cctabs resume <name> [dir]               # resume last session (reuses tab or creates one)
+cctabs restore [dir] [--dry]             # resume every dead tab (e.g. after a reboot)
 cctabs fork <tab-name> [-n new-name]     # fork session into new tab (--resume <id> --fork-session)
 cctabs close <name-or-id>                # close a tab
 cctabs rename <name-or-id> <new-name>    # rename a tab
@@ -89,6 +127,18 @@ cctabs resume api ~/Dev/myapp
 **Use `cctabs resume` instead of `cctabs new` when you want to continue a previous conversation.**
 `cctabs new` always starts a fresh Claude session. `cctabs resume` picks up where the last session left off.
 
+## Workflow: Restoring tabs after a reboot
+
+After a Wave/computer restart, every tab loses its Claude session and shows up with `terminal` or `unknown` status. `cctabs restore` walks every such tab, looks up its session by name across **all** Claude project directories, and re-attaches in place.
+
+```bash
+cctabs restore                    # search all projects (default)
+cctabs restore --dry              # preview what would be resumed without doing it
+cctabs restore ~/Dev/myapp        # restrict the search to one project dir
+```
+
+If a session was started in a different `cwd` than the tab's current directory (common after `cd`-ing inside the tab), the global search still finds it via the recorded session metadata — no need to guess the right dir.
+
 ## Workflow: Forking a Session
 
 Use `fork` when you want to explore an alternative approach without disrupting the original.
@@ -104,7 +154,9 @@ The forked session shares full conversation history up to the fork point, then d
 
 ## Workflow: Spawning a Parallel Agent
 
-As a Claude Code session, you can spawn a sibling session to work on a parallel task:
+**Before spawning, re-read "is cctabs the right tool?" above.** If the task is interconnected with your current work, use the Agent tool (subagents) instead — they share your filesystem and commits.
+
+As a Claude Code session, you can spawn a sibling session for a **genuinely independent** parallel task:
 
 **Preferred: pass the initial task directly to `cctabs new`** using `--prompt` or `--file`. This polls internally until Claude's `❯` prompt appears before sending — no race condition:
 
@@ -125,6 +177,25 @@ cctabs send payments "yes\n"   # quick replies
 
 **Do NOT call `cctabs send` immediately after `cctabs new`** — Claude is still starting up and the text will land as raw shell commands.
 
+### Spawning gotchas (hard-won)
+
+1. **Verify the worktree base immediately after spawn.** `--worktree` does not always branch from your current HEAD — if you have local un-pushed commits, the child session may branch from an older commit (whatever the remote tracking branch points at). Always check:
+   ```bash
+   cctabs new kid ~/Dev/myapp --worktree -p "..."
+   # Then in the ORCHESTRATOR tab:
+   git -C ~/Dev/myapp/.claude/worktrees/kid log --oneline -1
+   ```
+   If the base is not what you expected, abort and fix: either push your commits to the tracking branch first, or spawn without `--worktree` and let the subagent work on your branch directly.
+
+2. **Never instruct a subagent to "rebase your branch on main/next."** Subagents interpret this liberally. A common failure mode: the subagent does `git reset --hard <remote>` and throws away its own completed commits, trying to redo the work from scratch. Instead:
+   - Have the orchestrator handle rebases after the subagent is done.
+   - Or send a precise patch/diff rather than a verbal rebase instruction.
+   - Or tell the subagent explicitly: *"do not rebase, do not reset; make fixup commits on top of your existing branch."*
+
+3. **Subagents won't see each other's commits.** Each tab has its own working tree. If ws-A commits a schema, ws-B cannot consume it until you merge A → main → rebase B. This is a fundamental property, not a bug. Only parallelize when this limitation doesn't matter.
+
+4. **Don't delegate rebases or merges to subagents.** Those are orchestrator work. Subagents produce content; orchestrator integrates.
+
 ## Workflow: Monitoring Another Session
 
 ```bash
@@ -176,10 +247,36 @@ cctabs new feature ~/Dev/myapp --worktree
 
 **Why:** Manually created worktree dirs placed outside the repo confuse Claude Code's session tracking, project memory lookup (`.claude/` is in the main repo), and CLAUDE.md resolution. Claude Code's built-in worktree support keeps everything co-located under `.claude/worktrees/` and handles cleanup on session exit.
 
+**Worktree base-commit caveat:** after spawning with `--worktree`, verify the branch base matches your expectation (see "Spawning gotchas" above). If your orchestrator has local commits that haven't been pushed, the worktree may branch from the stale remote tip instead of HEAD. This bites hardest when parallel tabs need to share schema/types your orchestrator has been working on — they won't see those changes if they branched before the commits landed upstream.
+
+## Handling `cctabs new` Timeout Errors
+
+`cctabs new` may occasionally fail with "Timed out waiting for new terminal block". This does **NOT** mean you have too many tabs or that Wave Terminal has hit a limit.
+
+**Possible causes** (root cause not yet confirmed):
+- Wave Terminal may need to be in focus / foreground for tab creation to register
+- The internal timeout may be slightly too short for the current system load
+- Transient IPC timing issue between cctabs and Wave
+
+**What to do:**
+1. **Retry the same command** — it often works on the second attempt
+2. If it fails again, wait a few seconds and retry once more
+3. If it keeps failing, ask the user to bring Wave Terminal to the foreground and try again
+
+**What NOT to do:**
+- ❌ Do NOT assume there is a "tab limit" — there isn't one
+- ❌ Do NOT close other tabs to "make room" — this destroys the user's sessions
+- ❌ Do NOT suggest the user has too many tabs open
+
 ## Workflow: Cleanup
 
+**⚠️ NEVER close tabs without explicit user approval.** Each tab may contain an active session with important context, uncommitted work, or in-progress tasks. Closing a tab is destructive and irreversible.
+
+**Always ask first:**
+> "These tabs look idle: `old-feature`, `fix-1234`. Want me to close any of them?"
+
+Only after the user confirms:
 ```bash
-cctabs sessions                        # find idle/terminal tabs
 cctabs close old-feature               # close by name (prefix match)
 cctabs close e5f6a7b8                  # close by block ID prefix
 ```
@@ -200,3 +297,14 @@ Name tabs after the **project or task**:
 - `cctabs new` and `cctabs resume` automatically pass `--name <tab-name>` to claude, syncing the session display name with the tab title
 - Configured `claude.flags` in `~/.config/cctabs/config.toml` are applied to every session
 - `cctabs send` resolves tab names to their terminal block automatically
+
+## Lesson: the common failure mode
+
+A pattern that wastes the most tokens: an orchestrator spawns three tabs for "parallel workstreams" on the same feature, each tab diverges from the base and from each other, the orchestrator loses visibility into what each is doing, one tab misinterprets a course-correct and resets its own work, and finally the orchestrator spends hours hand-merging commits that don't apply cleanly against an intervening refactor.
+
+The fix is upstream: before spawning, ask *"are these workstreams actually independent?"* If the answer is "mostly, but they share a common data model / schema / utility module" — they are **not** independent for cctabs purposes. Either:
+- Do them sequentially in one tab (cheapest).
+- Use the Agent tool for subtasks that share orchestrator state.
+- Land the shared pieces first on `main`/`next`, push, then spawn tabs (each branches cleanly off the new tip and work is truly orthogonal from there).
+
+Parallel tabs earn their keep when the work is genuinely orthogonal (separate repos, separate brand-new directories, independent features) and when you'd otherwise be idle waiting for one long-running task to finish.