@oomfware/cgr 0.1.8 → 0.2.1

package/README.md

@@ -42,15 +42,15 @@ cgr clean --all
 ## commands
 
 ```
-cgr ask [-m opus|sonnet|haiku] [-s] [-w repo[#branch] ...] <repo>[#branch] <question>
+cgr ask [-m opus|sonnet|haiku] [-d] [-w repo[#branch] ...] <repo>[#branch] <question>
 cgr clean [--all | <repo>]
 ```
 
-| option          | description                                       |
-| --------------- | ------------------------------------------------- |
-| `-m, --model`   | model to use: opus, sonnet, haiku (default haiku) |
-| `-s, --shallow` | use shallow clone (depth 1) for faster cloning    |
-| `-w, --with`    | additional repository to include (repeatable)     |
+| option        | description                                       |
+| ------------- | ------------------------------------------------- |
+| `-m, --model` | model to use: opus, sonnet, haiku (default haiku) |
+| `-d, --deep`  | clone full history (enables git log/blame/show)   |
+| `-w, --with`  | additional repository to include (repeatable)     |
 
 | command | description                                                       |
 | ------- | ----------------------------------------------------------------- |
@@ -88,7 +88,7 @@ You can use `@oomfware/cgr` to ask questions about external repositories.
 
     options:
       -m, --model <model>   model to use: opus, sonnet, haiku (default: haiku)
-      -s, --shallow         use shallow clone (depth 1) for faster cloning
+      -d, --deep            clone full history (enables git log/blame/show)
       -w, --with <repo>     additional repository to include, supports #branch (repeatable)
 
 Useful repositories:

package/dist/assets/system-prompt.md

@@ -111,6 +111,10 @@ where they can look—so they can ask informed follow-ups.
 **Compare implementations**: When examining multiple repositories, highlight differences in
 approach. Tables work well for summarizing tradeoffs.
 
-**Use history**: When relevant, use git log/blame/show to understand how code evolved.
+**Use history**: When relevant, use git log/blame/show to understand how code evolved—why code
+exists, when behavior changed, who authored a component. If the repository is a shallow clone and
+the question would benefit from git history, suggest re-running with `--deep`.
 
 **Admit uncertainty**: If you're unsure about something, say so and explain what you did find.
+
+---

package/dist/index.mjs

@@ -5,9 +5,10 @@ import { spawn } from "node:child_process";
 import { basename, dirname, join, relative } from "node:path";
 import { multiple, optional, withDefault } from "@optique/core/modifiers";
 import { existsSync } from "node:fs";
-import { mkdir, readdir, rm, stat, symlink } from "node:fs/promises";
+import { mkdir, readFile, readdir, rm, stat, symlink, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
+import * as v from "valibot";
 import checkbox from "@inquirer/checkbox";
 import confirm from "@inquirer/confirm";
 
@@ -102,24 +103,24 @@ const gitOutput = (args, cwd) => new Promise((resolve, reject) => {
 	proc.on("error", reject);
 });
 /**
-* checks if a repository is a shallow clone.
+* checks if a repository has full history.
 * @param cachePath the local repository path
-* @returns true if the repository is shallow
+* @returns true if the repository has full history (not shallow)
 */
-const isShallowRepo = async (cachePath) => {
-	return await gitOutput(["rev-parse", "--is-shallow-repository"], cachePath) === "true";
+const isDeepRepo = async (cachePath) => {
+	return await gitOutput(["rev-parse", "--is-shallow-repository"], cachePath) !== "true";
 };
 /**
 * clones a repository to the cache path.
 * @param remote the remote URL
 * @param cachePath the local cache path
 * @param branch optional branch to checkout
-* @param shallow if true, performs a shallow clone with depth 1
+* @param deep if true, clones full history; otherwise shallow clone with depth 1
 */
-const cloneRepo = async (remote, cachePath, branch, shallow) => {
+const cloneRepo = async (remote, cachePath, branch, deep) => {
 	await mkdir(dirname(cachePath), { recursive: true });
 	const args = ["clone"];
-	if (shallow) args.push("--depth", "1");
+	if (!deep) args.push("--depth", "1");
 	if (branch) args.push("--branch", branch);
 	args.push(remote, cachePath);
 	await git(args);
@@ -129,23 +130,23 @@ const cloneRepo = async (remote, cachePath, branch, shallow) => {
 * discards any local modifications, staged changes, and untracked files.
 * @param cachePath the local cache path
 * @param branch optional branch to checkout (uses default branch if not specified)
-* @param shallow if true, keeps shallow clone; if false, unshallows if needed
+* @param deep if true, unshallows if needed; if false, keeps shallow clone
 */
-const updateRepo = async (cachePath, branch, shallow) => {
-	const currentlyShallow = await isShallowRepo(cachePath);
-	if (!shallow && currentlyShallow) await git([
+const updateRepo = async (cachePath, branch, deep) => {
+	const currentlyDeep = await isDeepRepo(cachePath);
+	if (deep && !currentlyDeep) await git([
 		"fetch",
 		"--unshallow",
 		"origin"
 	], cachePath);
-	else if (shallow && !currentlyShallow) console.error("  note: repository is already a full clone, use `cgr clean` to re-clone as shallow");
-	if (shallow && currentlyShallow) await git([
+	else if (!deep && currentlyDeep) console.error("  note: repository is already a full clone, use `cgr clean` to re-clone as shallow");
+	if (!deep && !currentlyDeep) await git([
 		"fetch",
 		"--depth",
 		"1",
 		"origin"
 	], cachePath);
-	else if (!currentlyShallow || !shallow) await git(["fetch", "origin"], cachePath);
+	else await git(["fetch", "origin"], cachePath);
 	let targetBranch = branch;
 	if (!targetBranch) targetBranch = (await gitOutput(["symbolic-ref", "refs/remotes/origin/HEAD"], cachePath)).replace("refs/remotes/origin/", "");
 	await git([
@@ -170,9 +171,9 @@ const updateRepo = async (cachePath, branch, shallow) => {
 * @param options repository options
 */
 const ensureRepo = async (options) => {
-	const { remote, cachePath, branch, shallow } = options;
-	if (existsSync(cachePath)) await updateRepo(cachePath, branch, shallow);
-	else await cloneRepo(remote, cachePath, branch, shallow);
+	const { remote, cachePath, branch, deep } = options;
+	if (existsSync(cachePath)) await updateRepo(cachePath, branch, deep);
+	else await cloneRepo(remote, cachePath, branch, deep);
 };
 
 //#endregion
@@ -278,13 +279,16 @@ const parseRemoteWithBranch = (input) => {
 * @returns the sessions directory path
 */
 const getSessionsDir = () => join(getCacheDir(), "sessions");
+const PID_FILE = ".pid";
+const PidSchema = v.pipe(v.string(), v.trim(), v.toNumber(), v.integer(), v.minValue(1));
 /**
-* creates a new session directory with a random UUID.
+* creates a new session directory with a random UUID and writes a PID lockfile.
 * @returns the path to the created session directory
 */
 const createSessionDir = async () => {
 	const sessionPath = join(getSessionsDir(), randomUUID());
 	await mkdir(sessionPath, { recursive: true });
+	await writeFile(join(sessionPath, PID_FILE), process.pid.toString());
 	return sessionPath;
 };
 /**
@@ -297,6 +301,51 @@ const cleanupSessionDir = async (sessionPath) => {
 		force: true
 	});
 };
+/**
+* checks if a process with the given PID is running.
+* @param pid the process ID to check
+* @returns true if the process is running
+*/
+const isProcessRunning = (pid) => {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+};
+/**
+* garbage collects orphaned session directories.
+* a session is orphaned if its PID file is missing or the process is no longer running.
+* this function is meant to be called fire-and-forget (errors are silently ignored).
+*/
+const gcSessions = async () => {
+	const sessionsDir = getSessionsDir();
+	let entries;
+	try {
+		entries = await readdir(sessionsDir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		const sessionPath = join(sessionsDir, entry.name);
+		const pidPath = join(sessionPath, PID_FILE);
+		try {
+			const pidContent = await readFile(pidPath, "utf-8");
+			const result$1 = v.safeParse(PidSchema, pidContent);
+			if (!result$1.success || !isProcessRunning(result$1.output)) await rm(sessionPath, {
+				recursive: true,
+				force: true
+			});
+		} catch {
+			await rm(sessionPath, {
+				recursive: true,
+				force: true
+			}).catch(() => {});
+		}
+	}
+};
 
 //#endregion
 //#region src/lib/symlink.ts
@@ -338,10 +387,9 @@ const schema$1 = object({
 		"sonnet",
 		"haiku"
 	]), { description: message`model to use for analysis` }), "haiku"),
-	shallow: flag("-s", "--shallow", { description: message`use shallow clone (depth 1) to save time and disk space` }),
-	branch: optional(option("-b", "--branch", string(), { description: message`branch to checkout (deprecated: use repo#branch instead)` })),
+	deep: withDefault(flag("-d", "--deep", { description: message`clone full history (enables git log/blame/show)` }), false),
 	with: withDefault(multiple(option("-w", "--with", string(), { description: message`additional repository to include` })), []),
-	remote: argument(string({ metavar: "REPO" }), { description: message`git remote URL (HTTP/HTTPS/SSH), optionally with #branch` }),
+	remote: argument(string({ metavar: "REPO" }), { description: message`git remote URL (http/https/ssh), optionally with #branch` }),
 	question: argument(string({ metavar: "QUESTION" }), { description: message`question to ask about the repository` })
 });
 /**
@@ -381,18 +429,20 @@ const parseRepoInput = (input) => {
 /**
 * builds a context prompt for a single repository.
 * @param repo the repo entry
+* @param deep whether the clone has full history
 * @returns context prompt string
 */
-const buildSingleRepoContext = (repo) => {
-	return `You are examining ${`${repo.parsed.host}/${repo.parsed.path}`} (checked out on ${repo.branch ?? "default branch"}).`;
+const buildSingleRepoContext = (repo, deep) => {
+	return `You are examining ${`${repo.parsed.host}/${repo.parsed.path}`} (checked out on ${repo.branch ?? "default branch"}, ${deep ? "full clone" : "shallow clone"}).`;
 };
 /**
 * builds a context prompt for multiple repositories.
 * @param dirMap map of directory name -> repo entry
+* @param deep whether the clones have full history
 * @returns context prompt string
 */
-const buildMultiRepoContext = (dirMap) => {
-	const lines = ["You are examining multiple repositories:", ""];
+const buildMultiRepoContext = (dirMap, deep) => {
+	const lines = [`You are examining multiple repositories (${deep ? "full clone" : "shallow clone"}):`, ""];
 	for (const [dirName, repo] of dirMap) {
 		const repoDisplay = `${repo.parsed.host}/${repo.parsed.path}`;
 		const branchDisplay = repo.branch ?? "default branch";
@@ -429,7 +479,7 @@ const spawnClaude = (cwd, contextPrompt, args) => new Promise((resolve, reject)
 		resolve(code ?? 0);
 	});
 	claude.on("error", (err) => {
-		reject(/* @__PURE__ */ new Error(`failed to spawn claude: ${err}`));
+		reject(/* @__PURE__ */ new Error(`failed to summon claude: ${err}`));
 	});
 });
 /**
@@ -438,8 +488,8 @@ const spawnClaude = (cwd, contextPrompt, args) => new Promise((resolve, reject)
 * @param args parsed command arguments
 */
 const handler$1 = async (args) => {
+	gcSessions();
 	const mainRepo = parseRepoInput(args.remote);
-	if (!mainRepo.branch && args.branch) mainRepo.branch = args.branch;
 	if (args.with.length === 0) {
 		const remoteUrl = normalizeRemote(mainRepo.remote);
 		console.error(`preparing repository: ${mainRepo.parsed.host}/${mainRepo.parsed.path}`);
@@ -448,13 +498,13 @@ const handler$1 = async (args) => {
 				remote: remoteUrl,
 				cachePath: mainRepo.cachePath,
 				branch: mainRepo.branch,
-				shallow: args.shallow
+				deep: args.deep
 			});
 		} catch (err) {
 			console.error(`error: failed to prepare repository: ${err}`);
 			process.exit(1);
 		}
-		const contextPrompt = buildSingleRepoContext(mainRepo);
+		const contextPrompt = buildSingleRepoContext(mainRepo, args.deep);
 		const exitCode$1 = await spawnClaude(mainRepo.cachePath, contextPrompt, args);
 		process.exit(exitCode$1);
 	}
@@ -468,7 +518,7 @@ const handler$1 = async (args) => {
 			remote: remoteUrl,
 			cachePath: repo.cachePath,
 			branch: repo.branch,
-			shallow: args.shallow
+			deep: args.deep
 		});
 		return repo;
 	}));
@@ -489,7 +539,7 @@ const handler$1 = async (args) => {
 	const sessionPath = await createSessionDir();
 	let exitCode = 1;
 	try {
-		exitCode = await spawnClaude(sessionPath, buildMultiRepoContext(await buildSymlinkDir(sessionPath, allRepos)), args);
+		exitCode = await spawnClaude(sessionPath, buildMultiRepoContext(await buildSymlinkDir(sessionPath, allRepos), args.deep), args);
 	} finally {
 		await cleanupSessionDir(sessionPath);
 	}
@@ -588,14 +638,14 @@ const handler = async (args) => {
 	const sessionsDir = getSessionsDir();
 	if (args.all) {
 		const reposExist = await exists(reposDir);
-		const sessionsExist$1 = await exists(sessionsDir);
-		if (!reposExist && !sessionsExist$1) {
+		const sessionsExist = await exists(sessionsDir);
+		if (!reposExist && !sessionsExist) {
 			console.log("no cached data found");
 			return;
 		}
 		let totalSize$1 = 0;
 		if (reposExist) totalSize$1 += await getDirSize(reposDir);
-		if (sessionsExist$1) totalSize$1 += await getDirSize(sessionsDir);
+		if (sessionsExist) totalSize$1 += await getDirSize(sessionsDir);
 		if (!args.yes) {
 			if (!await confirm({
 				message: `remove all cached data? (${formatSize(totalSize$1)})`,
@@ -603,7 +653,7 @@ const handler = async (args) => {
 			})) return;
 		}
 		if (reposExist) await rm(reposDir, { recursive: true });
-		if (sessionsExist$1) await rm(sessionsDir, { recursive: true });
+		if (sessionsExist) await rm(sessionsDir, { recursive: true });
 		console.log("done");
 		return;
 	}
@@ -629,30 +679,22 @@ const handler = async (args) => {
 		return;
 	}
 	const repos = await listCachedRepos();
-	const sessionsExist = await exists(sessionsDir);
-	const sessionsSize = sessionsExist ? await getDirSize(sessionsDir) : 0;
-	if (repos.length === 0 && !sessionsExist) {
-		console.log("no cached data found");
+	if (repos.length === 0) {
+		console.log("no cached repositories found");
 		return;
 	}
-	const maxNameLen = Math.max(...repos.map((r) => r.displayPath.length), sessionsExist ? 10 : 0);
-	const maxSizeLen = Math.max(...repos.map((r) => formatSize(r.size).length), sessionsExist ? formatSize(sessionsSize).length : 0);
+	const maxNameLen = Math.max(...repos.map((r) => r.displayPath.length));
+	const maxSizeLen = Math.max(...repos.map((r) => formatSize(r.size).length));
 	const termWidth = process.stdout.columns ?? 80;
 	const usePadding = maxNameLen + 2 + maxSizeLen + 6 <= termWidth;
 	const formatChoice = (name, size) => usePadding ? `${name.padEnd(maxNameLen)}  ${formatSize(size)}` : `${name} (${formatSize(size)})`;
-	const choices = repos.map((repo) => ({
-		name: formatChoice(repo.displayPath, repo.size),
-		value: repo.path,
-		short: repo.displayPath
-	}));
-	if (sessionsExist && sessionsSize > 0) choices.push({
-		name: formatChoice("(sessions)", sessionsSize),
-		value: sessionsDir,
-		short: "(sessions)"
-	});
 	const selected = await checkbox({
 		message: "select items to remove",
-		choices,
+		choices: repos.map((repo) => ({
+			name: formatChoice(repo.displayPath, repo.size),
+			value: repo.path,
+			short: repo.displayPath
+		})),
 		pageSize: 20
 	});
 	if (selected.length === 0) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oomfware/cgr",
-  "version": "0.1.8",
+  "version": "0.2.1",
   "description": "ask questions about git repositories using Claude Code",
   "license": "0BSD",
   "repository": {
@@ -24,7 +24,8 @@
     "@inquirer/checkbox": "5.0.4",
     "@inquirer/confirm": "6.0.4",
     "@optique/core": "^0.9.1",
-    "@optique/run": "^0.9.1"
+    "@optique/run": "^0.9.1",
+    "valibot": "^1.2.0"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",

package/src/assets/system-prompt.md

@@ -111,6 +111,10 @@ where they can look—so they can ask informed follow-ups.
 **Compare implementations**: When examining multiple repositories, highlight differences in
 approach. Tables work well for summarizing tradeoffs.
 
-**Use history**: When relevant, use git log/blame/show to understand how code evolved.
+**Use history**: When relevant, use git log/blame/show to understand how code evolved—why code
+exists, when behavior changed, who authored a component. If the repository is a shallow clone and
+the question would benefit from git history, suggest re-running with `--deep`.
 
 **Admit uncertainty**: If you're unsure about something, say so and explain what you did find.
+
+---

package/src/commands/ask.ts

@@ -1,13 +1,24 @@
 import { spawn } from 'node:child_process';
 import { join } from 'node:path';
 
-import { argument, choice, constant, flag, type InferValue, message, object, option, string } from '@optique/core';
-import { multiple, optional, withDefault } from '@optique/core/modifiers';
+import {
+	argument,
+	choice,
+	constant,
+	flag,
+	type InferValue,
+	message,
+	object,
+	option,
+	string,
+} from '@optique/core';
+import { multiple, withDefault } from '@optique/core/modifiers';
 
 import { ensureRepo } from '../lib/git.ts';
 import {
 	cleanupSessionDir,
 	createSessionDir,
+	gcSessions,
 	getRepoCachePath,
 	normalizeRemote,
 	parseRemote,
@@ -28,14 +39,11 @@ export const schema = object({
 		}),
 		'haiku',
 	),
-	shallow: flag('-s', '--shallow', {
-		description: message`use shallow clone (depth 1) to save time and disk space`,
-	}),
-	// TODO: deprecated in favor of #branch syntax, remove in future version
-	branch: optional(
-		option('-b', '--branch', string(), {
-			description: message`branch to checkout (deprecated: use repo#branch instead)`,
+	deep: withDefault(
+		flag('-d', '--deep', {
+			description: message`clone full history (enables git log/blame/show)`,
 		}),
+		false,
 	),
 	with: withDefault(
 		multiple(
@@ -46,7 +54,7 @@ export const schema = object({
 		[],
 	),
 	remote: argument(string({ metavar: 'REPO' }), {
-		description: message`git remote URL (HTTP/HTTPS/SSH), optionally with #branch`,
+		description: message`git remote URL (http/https/ssh), optionally with #branch`,
 	}),
 	question: argument(string({ metavar: 'QUESTION' }), {
 		description: message`question to ask about the repository`,
@@ -91,26 +99,33 @@ const parseRepoInput = (input: string): RepoEntry => {
 /**
  * builds a context prompt for a single repository.
  * @param repo the repo entry
+ * @param deep whether the clone has full history
  * @returns context prompt string
  */
-const buildSingleRepoContext = (repo: RepoEntry): string => {
+const buildSingleRepoContext = (repo: RepoEntry, deep: boolean): string => {
 	const repoDisplay = `${repo.parsed.host}/${repo.parsed.path}`;
 	const branchDisplay = repo.branch ?? 'default branch';
-	return `You are examining ${repoDisplay} (checked out on ${branchDisplay}).`;
+	const cloneType = deep ? 'full clone' : 'shallow clone';
+
+	return `You are examining ${repoDisplay} (checked out on ${branchDisplay}, ${cloneType}).`;
 };
 
 /**
  * builds a context prompt for multiple repositories.
  * @param dirMap map of directory name -> repo entry
+ * @param deep whether the clones have full history
  * @returns context prompt string
  */
-const buildMultiRepoContext = (dirMap: Map<string, RepoEntry>): string => {
-	const lines = ['You are examining multiple repositories:', ''];
+const buildMultiRepoContext = (dirMap: Map<string, RepoEntry>, deep: boolean): string => {
+	const cloneType = deep ? 'full clone' : 'shallow clone';
+	const lines = [`You are examining multiple repositories (${cloneType}):`, ''];
+
 	for (const [dirName, repo] of dirMap) {
 		const repoDisplay = `${repo.parsed.host}/${repo.parsed.path}`;
 		const branchDisplay = repo.branch ?? 'default branch';
 		lines.push(`- ${dirName}/ -> ${repoDisplay} (checked out on ${branchDisplay})`);
 	}
+
 	return lines.join('\n');
 };
 
@@ -147,7 +162,7 @@ const spawnClaude = (cwd: string, contextPrompt: string, args: Args): Promise<nu
 		});
 
 		claude.on('error', (err) => {
-			reject(new Error(`failed to spawn claude: ${err}`));
+			reject(new Error(`failed to summon claude: ${err}`));
 		});
 	});
 
@@ -157,14 +172,12 @@ const spawnClaude = (cwd: string, contextPrompt: string, args: Args): Promise<nu
  * @param args parsed command arguments
  */
 export const handler = async (args: Args): Promise<void> => {
+	// fire-and-forget cleanup of orphaned sessions
+	gcSessions();
+
 	// parse main remote (with optional #branch)
 	const mainRepo = parseRepoInput(args.remote);
 
-	// #branch takes precedence over -b flag
-	if (!mainRepo.branch && args.branch) {
-		mainRepo.branch = args.branch;
-	}
-
 	// #region single repo mode
 	if (args.with.length === 0) {
 		// clone or update repository
@@ -175,14 +188,14 @@ export const handler = async (args: Args): Promise<void> => {
 				remote: remoteUrl,
 				cachePath: mainRepo.cachePath,
 				branch: mainRepo.branch,
-				shallow: args.shallow,
+				deep: args.deep,
 			});
 		} catch (err) {
 			console.error(`error: failed to prepare repository: ${err}`);
 			process.exit(1);
 		}
 
-		const contextPrompt = buildSingleRepoContext(mainRepo);
+		const contextPrompt = buildSingleRepoContext(mainRepo, args.deep);
 		const exitCode = await spawnClaude(mainRepo.cachePath, contextPrompt, args);
 		process.exit(exitCode);
 	}
@@ -204,7 +217,7 @@ export const handler = async (args: Args): Promise<void> => {
 				remote: remoteUrl,
 				cachePath: repo.cachePath,
 				branch: repo.branch,
-				shallow: args.shallow,
+				deep: args.deep,
 			});
 			return repo;
 		}),
@@ -235,7 +248,7 @@ export const handler = async (args: Args): Promise<void> => {
 
 	try {
 		const dirMap = await buildSymlinkDir(sessionPath, allRepos);
-		const contextPrompt = buildMultiRepoContext(dirMap);
+		const contextPrompt = buildMultiRepoContext(dirMap, args.deep);
 		exitCode = await spawnClaude(sessionPath, contextPrompt, args);
 	} finally {
 		// always clean up session directory

package/src/commands/clean.ts

@@ -206,23 +206,15 @@ export const handler = async (args: Args): Promise<void> => {
 
 	// #region interactive selection
 	const repos = await listCachedRepos();
-	const sessionsExist = await exists(sessionsDir);
-	const sessionsSize = sessionsExist ? await getDirSize(sessionsDir) : 0;
 
-	if (repos.length === 0 && !sessionsExist) {
-		console.log('no cached data found');
+	if (repos.length === 0) {
+		console.log('no cached repositories found');
 		return;
 	}
 
 	// build choices for checkbox
-	const maxNameLen = Math.max(
-		...repos.map((r) => r.displayPath.length),
-		sessionsExist ? '(sessions)'.length : 0,
-	);
-	const maxSizeLen = Math.max(
-		...repos.map((r) => formatSize(r.size).length),
-		sessionsExist ? formatSize(sessionsSize).length : 0,
-	);
+	const maxNameLen = Math.max(...repos.map((r) => r.displayPath.length));
+	const maxSizeLen = Math.max(...repos.map((r) => formatSize(r.size).length));
 
 	// checkbox prefix is ~4 chars, leave some margin
 	const termWidth = process.stdout.columns ?? 80;
@@ -237,14 +229,6 @@ export const handler = async (args: Args): Promise<void> => {
 		short: repo.displayPath,
 	}));
 
-	if (sessionsExist && sessionsSize > 0) {
-		choices.push({
-			name: formatChoice('(sessions)', sessionsSize),
-			value: sessionsDir,
-			short: '(sessions)',
-		});
-	}
-
 	const selected = await checkbox({
 		message: 'select items to remove',
 		choices,

package/src/lib/git.ts

@@ -86,13 +86,13 @@ const gitOutput = (args: string[], cwd?: string): Promise<string> =>
 	});
 
 /**
- * checks if a repository is a shallow clone.
+ * checks if a repository has full history.
  * @param cachePath the local repository path
- * @returns true if the repository is shallow
+ * @returns true if the repository has full history (not shallow)
  */
-export const isShallowRepo = async (cachePath: string): Promise<boolean> => {
+const isDeepRepo = async (cachePath: string): Promise<boolean> => {
 	const result = await gitOutput(['rev-parse', '--is-shallow-repository'], cachePath);
-	return result === 'true';
+	return result !== 'true';
 };
 
 /**
@@ -100,17 +100,17 @@ export const isShallowRepo = async (cachePath: string): Promise<boolean> => {
  * @param remote the remote URL
  * @param cachePath the local cache path
  * @param branch optional branch to checkout
- * @param shallow if true, performs a shallow clone with depth 1
+ * @param deep if true, clones full history; otherwise shallow clone with depth 1
  */
-export const cloneRepo = async (
+const cloneRepo = async (
 	remote: string,
 	cachePath: string,
-	branch?: string,
-	shallow?: boolean,
+	branch: string | undefined,
+	deep: boolean,
 ): Promise<void> => {
 	await mkdir(dirname(cachePath), { recursive: true });
 	const args = ['clone'];
-	if (shallow) {
+	if (!deep) {
 		args.push('--depth', '1');
 	}
 	if (branch) {
@@ -125,24 +125,24 @@ export const cloneRepo = async (
  * discards any local modifications, staged changes, and untracked files.
  * @param cachePath the local cache path
  * @param branch optional branch to checkout (uses default branch if not specified)
- * @param shallow if true, keeps shallow clone; if false, unshallows if needed
+ * @param deep if true, unshallows if needed; if false, keeps shallow clone
  */
-export const updateRepo = async (cachePath: string, branch?: string, shallow?: boolean): Promise<void> => {
-	const currentlyShallow = await isShallowRepo(cachePath);
+const updateRepo = async (cachePath: string, branch: string | undefined, deep: boolean): Promise<void> => {
+	const currentlyDeep = await isDeepRepo(cachePath);
 
-	// handle shallow state transitions
-	if (!shallow && currentlyShallow) {
+	// handle depth state transitions
+	if (deep && !currentlyDeep) {
 		// want full history but have shallow - unshallow first
 		await git(['fetch', '--unshallow', 'origin'], cachePath);
-	} else if (shallow && !currentlyShallow) {
+	} else if (!deep && currentlyDeep) {
 		// want shallow but have full - just use the full clone as-is
 		console.error('  note: repository is already a full clone, use `cgr clean` to re-clone as shallow');
 	}
 
-	// fetch updates (use depth for shallow repos that stay shallow)
-	if (shallow && currentlyShallow) {
+	// fetch updates (use depth 1 for shallow repos that stay shallow)
+	if (!deep && !currentlyDeep) {
 		await git(['fetch', '--depth', '1', 'origin'], cachePath);
-	} else if (!currentlyShallow || !shallow) {
+	} else {
 		// either was unshallowed above, or is/was full
 		await git(['fetch', 'origin'], cachePath);
 	}
@@ -169,8 +169,8 @@ export interface EnsureRepoOptions {
 	cachePath: string;
 	/** branch to checkout */
 	branch: string | undefined;
-	/** if true, uses shallow clone with depth 1 */
-	shallow: boolean;
+	/** if true, clones full history; otherwise uses shallow clone with depth 1 */
+	deep: boolean;
 }
 
 /**
@@ -178,10 +178,10 @@ export interface EnsureRepoOptions {
  * @param options repository options
  */
 export const ensureRepo = async (options: EnsureRepoOptions): Promise<void> => {
-	const { remote, cachePath, branch, shallow } = options;
+	const { remote, cachePath, branch, deep } = options;
 	if (existsSync(cachePath)) {
-		await updateRepo(cachePath, branch, shallow);
+		await updateRepo(cachePath, branch, deep);
 	} else {
-		await cloneRepo(remote, cachePath, branch, shallow);
+		await cloneRepo(remote, cachePath, branch, deep);
 	}
 };

package/src/lib/paths.ts

@@ -1,8 +1,11 @@
 import { randomUUID } from 'node:crypto';
-import { mkdir, rm } from 'node:fs/promises';
+import type { Dirent } from 'node:fs';
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
+import * as v from 'valibot';
+
 /**
  * returns the cache directory for cgr.
  * uses `$XDG_CACHE_HOME/cgr` if set, otherwise falls back to:
@@ -157,13 +160,19 @@ export const parseRemoteWithBranch = (input: string): { remote: string; branch?:
  */
 export const getSessionsDir = (): string => join(getCacheDir(), 'sessions');
 
+const PID_FILE = '.pid';
+
+// linux PID limits: 1 to 2^22 (4194304) by default, configurable up to 2^22
+const PidSchema = v.pipe(v.string(), v.trim(), v.toNumber(), v.integer(), v.minValue(1));
+
 /**
- * creates a new session directory with a random UUID.
+ * creates a new session directory with a random UUID and writes a PID lockfile.
  * @returns the path to the created session directory
  */
 export const createSessionDir = async (): Promise<string> => {
 	const sessionPath = join(getSessionsDir(), randomUUID());
 	await mkdir(sessionPath, { recursive: true });
+	await writeFile(join(sessionPath, PID_FILE), process.pid.toString());
 	return sessionPath;
 };
 
@@ -174,3 +183,55 @@ export const createSessionDir = async (): Promise<string> => {
 export const cleanupSessionDir = async (sessionPath: string): Promise<void> => {
 	await rm(sessionPath, { recursive: true, force: true });
 };
+
+/**
+ * checks if a process with the given PID is running.
+ * @param pid the process ID to check
+ * @returns true if the process is running
+ */
+const isProcessRunning = (pid: number): boolean => {
+	try {
+		// signal 0 doesn't send a signal but checks if process exists
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+};
+
+/**
+ * garbage collects orphaned session directories.
+ * a session is orphaned if its PID file is missing or the process is no longer running.
+ * this function is meant to be called fire-and-forget (errors are silently ignored).
+ */
+export const gcSessions = async (): Promise<void> => {
+	const sessionsDir = getSessionsDir();
+
+	let entries: Dirent[];
+	try {
+		entries = await readdir(sessionsDir, { withFileTypes: true });
+	} catch {
+		// sessions dir doesn't exist or can't be read
+		return;
+	}
+
+	for (const entry of entries) {
+		if (!entry.isDirectory()) {
+			continue;
+		}
+		const sessionPath = join(sessionsDir, entry.name);
+		const pidPath = join(sessionPath, PID_FILE);
+
+		try {
+			const pidContent = await readFile(pidPath, 'utf-8');
+			const result = v.safeParse(PidSchema, pidContent);
+
+			if (!result.success || !isProcessRunning(result.output)) {
+				await rm(sessionPath, { recursive: true, force: true });
+			}
+		} catch {
+			// no PID file or can't read it - orphaned session
+			await rm(sessionPath, { recursive: true, force: true }).catch(() => {});
+		}
+	}
+};