gsd-pi 2.5.1 → 2.6.0

package/README.md

@@ -224,6 +224,7 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `Ctrl+Alt+V` | Toggle voice transcription |
 | `Ctrl+Alt+B` | Show background shell processes |
 | `gsd config` | Re-run the setup wizard (LLM provider + tool keys) |
+| `gsd --continue` (`-c`) | Resume the most recent session for the current directory |
 
 ---
 

package/dist/cli.js

@@ -20,6 +20,9 @@ function parseCliArgs(argv) {
         else if (arg === '--print' || arg === '-p') {
             flags.print = true;
         }
+        else if (arg === '--continue' || arg === '-c') {
+            flags.continue = true;
+        }
         else if (arg === '--no-session') {
             flags.noSession = true;
         }
@@ -45,6 +48,7 @@ function parseCliArgs(argv) {
             process.stdout.write('Options:\n');
             process.stdout.write('  --mode <text|json|rpc>   Output mode (default: interactive)\n');
             process.stdout.write('  --print, -p              Single-shot print mode\n');
+            process.stdout.write('  --continue, -c           Resume the most recent session\n');
             process.stdout.write('  --model <id>             Override model (e.g. claude-opus-4-6)\n');
             process.stdout.write('  --no-session             Disable session persistence\n');
             process.stdout.write('  --extension <path>       Load additional extension\n');
@@ -200,7 +204,9 @@ if (existsSync(sessionsDir)) {
         // Non-fatal — don't block startup if migration fails
     }
 }
-const sessionManager = SessionManager.create(cwd, projectSessionsDir);
+const sessionManager = cliFlags.continue
+    ? SessionManager.continueRecent(cwd, projectSessionsDir)
+    : SessionManager.create(cwd, projectSessionsDir);
 initResources(agentDir);
 const resourceLoader = buildResourceLoader(agentDir);
 await resourceLoader.reload();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-pi",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "GSD — Get Shit Done coding agent",
   "license": "MIT",
   "repository": {

package/src/resources/extensions/get-secrets-from-user.ts

@@ -10,9 +10,13 @@ import { readFile, writeFile } from "node:fs/promises";
 import { existsSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { CURSOR_MARKER, Editor, type EditorTheme, Key, matchesKey, Text, truncateToWidth } from "@mariozechner/pi-tui";
+import type { ExtensionAPI, Theme } from "@mariozechner/pi-coding-agent";
+import { CURSOR_MARKER, Editor, type EditorTheme, Key, matchesKey, Text, truncateToWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
+import { makeUI, type ProgressStatus } from "./shared/ui.js";
+import { parseSecretsManifest, formatSecretsManifest } from "./gsd/files.js";
+import { resolveMilestoneFile } from "./gsd/paths.js";
+import type { SecretsManifestEntry } from "./gsd/types.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -152,6 +156,7 @@ async function collectOneSecret(
 	totalPages: number,
 	keyName: string,
 	hint: string | undefined,
+	guidance?: string[],
 ): Promise<string | null> {
 	if (!ctx.hasUI) return null;
 
@@ -209,6 +214,21 @@ async function collectOneSecret(
 			if (hint) {
 				add(theme.fg("muted", `  ${hint}`));
 			}
+
+			// Guidance steps (numbered, dim, wrapped for long URLs)
+			if (guidance && guidance.length > 0) {
+				lines.push("");
+				for (let g = 0; g < guidance.length; g++) {
+					const prefix = `  ${g + 1}. `;
+					const step = guidance[g] as string;
+					const wrappedLines = wrapTextWithAnsi(step, width - 4);
+					for (let w = 0; w < wrappedLines.length; w++) {
+						const indent = w === 0 ? prefix : " ".repeat(prefix.length);
+						lines.push(theme.fg("dim", `${indent}${wrappedLines[w]}`));
+					}
+				}
+			}
+
 			lines.push("");
 
 			// Masked preview
@@ -239,6 +259,248 @@ async function collectOneSecret(
 	});
 }
 
+/**
+ * Exported wrapper around collectOneSecret for testing.
+ * Exposes the same interface with guidance parameter for test verification.
+ */
+export const collectOneSecretWithGuidance = collectOneSecret;
+
+// ─── Summary Screen ───────────────────────────────────────────────────────────
+
+/**
+ * Read-only summary screen showing all manifest entries with status indicators.
+ * Follows the confirm-ui.ts pattern: render → any key → done.
+ *
+ * Status mapping:
+ * - collected → done
+ * - pending   → pending
+ * - skipped   → skipped
+ * - existing keys (in existingKeys) → done with "already set" annotation
+ */
+export async function showSecretsSummary(
+	ctx: { ui: any; hasUI: boolean },
+	entries: SecretsManifestEntry[],
+	existingKeys: string[],
+): Promise<void> {
+	if (!ctx.hasUI) return;
+
+	const existingSet = new Set(existingKeys);
+
+	await ctx.ui.custom<void>((tui: any, theme: Theme, _kb: any, done: () => void) => {
+		let cachedLines: string[] | undefined;
+
+		function handleInput(_data: string) {
+			// Any key dismisses
+			done();
+		}
+
+		function render(width: number): string[] {
+			if (cachedLines) return cachedLines;
+
+			const ui = makeUI(theme, width);
+			const lines: string[] = [];
+			const push = (...rows: string[][]) => { for (const r of rows) lines.push(...r); };
+
+			push(ui.bar());
+			push(ui.blank());
+			push(ui.header("  Secrets Summary"));
+			push(ui.blank());
+
+			for (const entry of entries) {
+				let status: ProgressStatus;
+				let detail: string | undefined;
+
+				if (existingSet.has(entry.key)) {
+					status = "done";
+					detail = "already set";
+				} else if (entry.status === "collected") {
+					status = "done";
+				} else if (entry.status === "skipped") {
+					status = "skipped";
+				} else {
+					status = "pending";
+				}
+
+				push(ui.progressItem(entry.key, status, { detail }));
+			}
+
+			push(ui.blank());
+			push(ui.hints(["any key to continue"]));
+			push(ui.bar());
+
+			cachedLines = lines;
+			return lines;
+		}
+
+		return {
+			render,
+			invalidate: () => { cachedLines = undefined; },
+			handleInput,
+		};
+	});
+}
+
+// ─── Destination Write Helper ─────────────────────────────────────────────────
+
+/**
+ * Apply collected secrets to the target destination.
+ * Dotenv writes are handled directly; vercel/convex require pi.exec.
+ */
+async function applySecrets(
+	provided: Array<{ key: string; value: string }>,
+	destination: "dotenv" | "vercel" | "convex",
+	opts: {
+		envFilePath: string;
+		environment?: string;
+		exec?: (cmd: string, args: string[]) => Promise<{ code: number; stderr: string }>;
+	},
+): Promise<{ applied: string[]; errors: string[] }> {
+	const applied: string[] = [];
+	const errors: string[] = [];
+
+	if (destination === "dotenv") {
+		for (const { key, value } of provided) {
+			try {
+				await writeEnvKey(opts.envFilePath, key, value);
+				applied.push(key);
+			} catch (err: any) {
+				errors.push(`${key}: ${err.message}`);
+			}
+		}
+	}
+
+	if (destination === "vercel" && opts.exec) {
+		const env = opts.environment ?? "development";
+		for (const { key, value } of provided) {
+			try {
+				const result = await opts.exec("sh", [
+					"-c",
+					`printf %s ${shellEscapeSingle(value)} | vercel env add ${key} ${env}`,
+				]);
+				if (result.code !== 0) {
+					errors.push(`${key}: ${result.stderr.slice(0, 200)}`);
+				} else {
+					applied.push(key);
+				}
+			} catch (err: any) {
+				errors.push(`${key}: ${err.message}`);
+			}
+		}
+	}
+
+	if (destination === "convex" && opts.exec) {
+		for (const { key, value } of provided) {
+			try {
+				const result = await opts.exec("sh", [
+					"-c",
+					`npx convex env set ${key} ${shellEscapeSingle(value)}`,
+				]);
+				if (result.code !== 0) {
+					errors.push(`${key}: ${result.stderr.slice(0, 200)}`);
+				} else {
+					applied.push(key);
+				}
+			} catch (err: any) {
+				errors.push(`${key}: ${err.message}`);
+			}
+		}
+	}
+
+	return { applied, errors };
+}
+
+// ─── Manifest Orchestrator ────────────────────────────────────────────────────
+
+/**
+ * Full orchestrator: reads manifest, checks env, shows summary, collects
+ * only pending keys (with guidance + hint), updates manifest statuses,
+ * writes back, and applies collected values to the destination.
+ *
+ * Returns a structured result matching the tool result shape.
+ */
+export async function collectSecretsFromManifest(
+	base: string,
+	milestoneId: string,
+	ctx: { ui: any; hasUI: boolean; cwd: string },
+): Promise<{ applied: string[]; skipped: string[]; existingSkipped: string[] }> {
+	// (a) Resolve manifest path
+	const manifestPath = resolveMilestoneFile(base, milestoneId, "SECRETS");
+	if (!manifestPath) {
+		throw new Error(`Secrets manifest not found for milestone ${milestoneId} in ${base}`);
+	}
+
+	// (b) Read and parse manifest
+	const content = await readFile(manifestPath, "utf8");
+	const manifest = parseSecretsManifest(content);
+
+	// (c) Check existing keys
+	const envPath = resolve(base, ".env");
+	const allKeys = manifest.entries.map((e) => e.key);
+	const existingKeys = await checkExistingEnvKeys(allKeys, envPath);
+	const existingSet = new Set(existingKeys);
+
+	// (d) Build categorization
+	const existingSkipped: string[] = [];
+	const alreadySkipped: string[] = [];
+	const pendingEntries: SecretsManifestEntry[] = [];
+
+	for (const entry of manifest.entries) {
+		if (existingSet.has(entry.key)) {
+			existingSkipped.push(entry.key);
+		} else if (entry.status === "skipped") {
+			alreadySkipped.push(entry.key);
+		} else if (entry.status === "pending") {
+			pendingEntries.push(entry);
+		}
+		// collected entries that are not in env are left as-is
+	}
+
+	// (e) Show summary screen
+	await showSecretsSummary(ctx, manifest.entries, existingKeys);
+
+	// (f) Detect destination
+	const destination = detectDestination(ctx.cwd);
+
+	// (g) Collect only pending keys that are not already existing
+	const collected: CollectedSecret[] = [];
+	for (let i = 0; i < pendingEntries.length; i++) {
+		const entry = pendingEntries[i] as SecretsManifestEntry;
+		const value = await collectOneSecret(
+			ctx,
+			i,
+			pendingEntries.length,
+			entry.key,
+			entry.formatHint || undefined,
+			entry.guidance.length > 0 ? entry.guidance : undefined,
+		);
+		collected.push({ key: entry.key, value });
+	}
+
+	// (h) Update manifest entry statuses
+	for (const { key, value } of collected) {
+		const entry = manifest.entries.find((e) => e.key === key);
+		if (entry) {
+			entry.status = value !== null ? "collected" : "skipped";
+		}
+	}
+
+	// (i) Write manifest back to disk
+	await writeFile(manifestPath, formatSecretsManifest(manifest), "utf8");
+
+	// (j) Apply collected values to destination
+	const provided = collected.filter((c) => c.value !== null) as Array<{ key: string; value: string }>;
+	const { applied } = await applySecrets(provided, destination, {
+		envFilePath: resolve(ctx.cwd, ".env"),
+	});
+
+	const skipped = [
+		...alreadySkipped,
+		...collected.filter((c) => c.value === null).map((c) => c.key),
+	];
+
+	return { applied, skipped, existingSkipped };
+}
+
 // ─── Extension ────────────────────────────────────────────────────────────────
 
 export default function secureEnv(pi: ExtensionAPI) {
@@ -299,64 +561,19 @@ export default function secureEnv(pi: ExtensionAPI) {
 			// Collect one key per page
 			for (let i = 0; i < params.keys.length; i++) {
 				const item = params.keys[i];
-				const value = await collectOneSecret(ctx, i, params.keys.length, item.key, item.hint);
+				const value = await collectOneSecret(ctx, i, params.keys.length, item.key, item.hint, item.guidance);
 				collected.push({ key: item.key, value });
 			}
 
 			const provided = collected.filter((c) => c.value !== null) as Array<{ key: string; value: string }>;
 			const skipped = collected.filter((c) => c.value === null).map((c) => c.key);
-			const applied: string[] = [];
-			const errors: string[] = [];
-
-			// Apply to destination
-			if (destination === "dotenv") {
-				const filePath = resolve(ctx.cwd, params.envFilePath ?? ".env");
-				for (const { key, value } of provided) {
-					try {
-						await writeEnvKey(filePath, key, value);
-						applied.push(key);
-					} catch (err: any) {
-						errors.push(`${key}: ${err.message}`);
-					}
-				}
-			}
 
-			if (destination === "vercel") {
-				const env = params.environment ?? "development";
-				for (const { key, value } of provided) {
-					try {
-						const result = await pi.exec("sh", [
-							"-c",
-							`printf %s ${shellEscapeSingle(value)} | vercel env add ${key} ${env}`,
-						]);
-						if (result.code !== 0) {
-							errors.push(`${key}: ${result.stderr.slice(0, 200)}`);
-						} else {
-							applied.push(key);
-						}
-					} catch (err: any) {
-						errors.push(`${key}: ${err.message}`);
-					}
-				}
-			}
-
-			if (destination === "convex") {
-				for (const { key, value } of provided) {
-					try {
-						const result = await pi.exec("sh", [
-							"-c",
-							`npx convex env set ${key} ${shellEscapeSingle(value)}`,
-						]);
-						if (result.code !== 0) {
-							errors.push(`${key}: ${result.stderr.slice(0, 200)}`);
-						} else {
-							applied.push(key);
-						}
-					} catch (err: any) {
-						errors.push(`${key}: ${err.message}`);
-					}
-				}
-			}
+			// Apply to destination via shared helper
+			const { applied, errors } = await applySecrets(provided, destination, {
+				envFilePath: resolve(ctx.cwd, params.envFilePath ?? ".env"),
+				environment: params.environment,
+				exec: (cmd, args) => pi.exec(cmd, args),
+			});
 
 			const details: ToolResultDetails = {
 				destination,

package/src/resources/extensions/gsd/auto.ts

@@ -18,9 +18,10 @@ import type {
 
 import { deriveState } from "./state.js";
 import type { GSDState } from "./types.js";
-import { loadFile, parseContinue, parsePlan, parseRoadmap, parseSummary, extractUatType, inlinePriorMilestoneSummary } from "./files.js";
+import { loadFile, parseContinue, parsePlan, parseRoadmap, parseSummary, extractUatType, inlinePriorMilestoneSummary, getManifestStatus } from "./files.js";
 export { inlinePriorMilestoneSummary };
 import type { UatType } from "./files.js";
+import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
 import { loadPrompt } from "./prompt-loader.js";
 import {
   gsdRoot, resolveMilestoneFile, resolveSliceFile, resolveSlicePath,
@@ -474,6 +475,24 @@ export async function startAuto(
     : "Will loop until milestone complete.";
   ctx.ui.notify(`${modeLabel} started. ${scopeMsg}`, "info");
 
+  // Secrets collection gate — collect pending secrets before first dispatch
+  const mid = state.activeMilestone.id;
+  try {
+    const manifestStatus = await getManifestStatus(base, mid);
+    if (manifestStatus && manifestStatus.pending.length > 0) {
+      const result = await collectSecretsFromManifest(base, mid, ctx);
+      ctx.ui.notify(
+        `Secrets collected: ${result.applied.length} applied, ${result.skipped.length} skipped, ${result.existingSkipped.length} already set.`,
+        "info",
+      );
+    }
+  } catch (err) {
+    ctx.ui.notify(
+      `Secrets collection error: ${err instanceof Error ? err.message : String(err)}`,
+      "warning",
+    );
+  }
+
   // Self-heal: clear stale runtime records where artifacts already exist
   await selfHealRuntimeRecords(base, ctx);
 
@@ -507,14 +526,15 @@ export async function handleAgentEnd(
     }
 
     // Post-hook: fix mechanical bookkeeping the LLM may have skipped.
-    // 1. Doctor handles: checkbox marking, stub summaries/UATs.
+    // 1. Doctor handles: checkbox marking (task-level bookkeeping).
     // 2. STATE.md is always rebuilt from disk state (purely derived, no LLM needed).
-    // This is more reliable than prompt instructions for mechanical tasks.
-    // Scope to slice level (M001/S01) so doctor checks all tasks within the slice.
+    // fixLevel:"task" ensures doctor only fixes task-level issues (e.g. marking
+    // checkboxes). Slice/milestone completion transitions (summary stubs,
+    // roadmap [x] marking) are left for the complete-slice dispatch unit.
     try {
       const scopeParts = currentUnit.id.split("/").slice(0, 2);
       const doctorScope = scopeParts.join("/");
-      const report = await runGSDDoctor(basePath, { fix: true, scope: doctorScope });
+      const report = await runGSDDoctor(basePath, { fix: true, scope: doctorScope, fixLevel: "task" });
       if (report.fixesApplied.length > 0) {
         ctx.ui.notify(`Post-hook: applied ${report.fixesApplied.length} fix(es).`, "info");
       }
@@ -1355,14 +1375,22 @@ async function dispatchNextUnit(
 
   // On crash recovery, prepend the full recovery briefing
   // On retry (stuck detection), prepend deep diagnostic from last attempt
+  // Cap injected content to prevent unbounded prompt growth → OOM
+  const MAX_RECOVERY_CHARS = 50_000;
   let finalPrompt = prompt;
   if (pendingCrashRecovery) {
-    finalPrompt = `${pendingCrashRecovery}\n\n---\n\n${finalPrompt}`;
+    const capped = pendingCrashRecovery.length > MAX_RECOVERY_CHARS
+      ? pendingCrashRecovery.slice(0, MAX_RECOVERY_CHARS) + "\n\n[...recovery briefing truncated to prevent memory exhaustion]"
+      : pendingCrashRecovery;
+    finalPrompt = `${capped}\n\n---\n\n${finalPrompt}`;
     pendingCrashRecovery = null;
   } else if ((unitDispatchCount.get(`${unitType}/${unitId}`) ?? 0) > 1) {
     const diagnostic = getDeepDiagnostic(basePath);
     if (diagnostic) {
-      finalPrompt = `**RETRY — your previous attempt did not produce the required artifact.**\n\nDiagnostic from previous attempt:\n${diagnostic}\n\nFix whatever went wrong and make sure you write the required file this time.\n\n---\n\n${finalPrompt}`;
+      const cappedDiag = diagnostic.length > MAX_RECOVERY_CHARS
+        ? diagnostic.slice(0, MAX_RECOVERY_CHARS) + "\n\n[...diagnostic truncated to prevent memory exhaustion]"
+        : diagnostic;
+      finalPrompt = `**RETRY — your previous attempt did not produce the required artifact.**\n\nDiagnostic from previous attempt:\n${cappedDiag}\n\nFix whatever went wrong and make sure you write the required file this time.\n\n---\n\n${finalPrompt}`;
     }
   }
 

package/src/resources/extensions/gsd/doctor.ts

@@ -422,10 +422,29 @@ export function formatDoctorIssuesForPrompt(issues: DoctorIssue[]): string {
   }).join("\n");
 }
 
-export async function runGSDDoctor(basePath: string, options?: { fix?: boolean; scope?: string }): Promise<DoctorReport> {
+export async function runGSDDoctor(basePath: string, options?: { fix?: boolean; scope?: string; fixLevel?: "task" | "all" }): Promise<DoctorReport> {
   const issues: DoctorIssue[] = [];
   const fixesApplied: string[] = [];
   const fix = options?.fix === true;
+  const fixLevel = options?.fixLevel ?? "all";
+
+  // Issue codes that represent completion state transitions — creating summary
+  // stubs, marking slices/milestones done in the roadmap. These belong to the
+  // dispatch lifecycle (complete-slice, complete-milestone units), not to
+  // mechanical post-hook bookkeeping. When fixLevel is "task", these are
+  // detected and reported but never auto-fixed.
+  const completionTransitionCodes = new Set<DoctorIssueCode>([
+    "all_tasks_done_missing_slice_summary",
+    "all_tasks_done_missing_slice_uat",
+    "all_tasks_done_roadmap_not_checked",
+  ]);
+
+  /** Whether a given issue code should be auto-fixed at the current fixLevel. */
+  const shouldFix = (code: DoctorIssueCode): boolean => {
+    if (!fix) return false;
+    if (fixLevel === "task" && completionTransitionCodes.has(code)) return false;
+    return true;
+  };
 
   const prefs = loadEffectiveGSDPreferences();
   if (prefs) {
@@ -606,7 +625,7 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
           file: relSliceFile(basePath, milestoneId, slice.id, "SUMMARY"),
           fixable: true,
         });
-        if (fix) await ensureSliceSummaryStub(basePath, milestoneId, slice.id, fixesApplied);
+        if (shouldFix("all_tasks_done_missing_slice_summary")) await ensureSliceSummaryStub(basePath, milestoneId, slice.id, fixesApplied);
       }
 
       if (allTasksDone && !hasSliceUat) {
@@ -619,7 +638,7 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
           file: `${relSlicePath(basePath, milestoneId, slice.id)}/${slice.id}-UAT.md`,
           fixable: true,
         });
-        if (fix) await ensureSliceUatStub(basePath, milestoneId, slice.id, fixesApplied);
+        if (shouldFix("all_tasks_done_missing_slice_uat")) await ensureSliceUatStub(basePath, milestoneId, slice.id, fixesApplied);
       }
 
       if (allTasksDone && !slice.done) {
@@ -632,7 +651,7 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
           file: relMilestoneFile(basePath, milestoneId, "ROADMAP"),
           fixable: true,
         });
-        if (fix && (hasSliceSummary || issues.some(issue => issue.code === "all_tasks_done_missing_slice_summary" && issue.unitId === unitId))) {
+        if (shouldFix("all_tasks_done_roadmap_not_checked") && (hasSliceSummary || issues.some(issue => issue.code === "all_tasks_done_missing_slice_summary" && issue.unitId === unitId))) {
           await markSliceDoneInRoadmap(basePath, milestoneId, slice.id, fixesApplied);
         }
       }

package/src/resources/extensions/gsd/files.ts

@@ -4,7 +4,7 @@
 // Pure functions, zero Pi dependencies — uses only Node built-ins.
 
 import { promises as fs, readdirSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { dirname, resolve } from 'node:path';
 import { milestonesDir, resolveMilestoneFile, relMilestoneFile } from './paths.js';
 
 import type {
@@ -14,8 +14,11 @@ import type {
   Continue, ContinueFrontmatter, ContinueStatus,
   RequirementCounts,
   SecretsManifest, SecretsManifestEntry, SecretsManifestEntryStatus,
+  ManifestStatus,
 } from './types.ts';
 
+import { checkExistingEnvKeys } from '../get-secrets-from-user.ts';
+
 // ─── Helpers ───────────────────────────────────────────────────────────────
 
 /**
@@ -800,3 +803,44 @@ export async function inlinePriorMilestoneSummary(mid: string, base: string): Pr
   if (!content) return null;
   return `### Prior Milestone Summary\nSource: \`${relPath}\`\n\n${content.trim()}`;
 }
+
+// ─── Manifest Status ──────────────────────────────────────────────────────
+
+/**
+ * Read a secrets manifest from disk and cross-reference each entry's status
+ * with the current environment (.env + process.env).
+ *
+ * Returns `null` when no manifest file exists (path resolution failure or
+ * file not on disk) — callers can distinguish "no manifest" from "empty manifest".
+ */
+export async function getManifestStatus(
+  base: string, milestoneId: string,
+): Promise<ManifestStatus | null> {
+  const resolvedPath = resolveMilestoneFile(base, milestoneId, 'SECRETS');
+  if (!resolvedPath) return null;
+
+  const content = await loadFile(resolvedPath);
+  if (!content) return null;
+
+  const manifest = parseSecretsManifest(content);
+  const keys = manifest.entries.map(e => e.key);
+  const existingKeys = await checkExistingEnvKeys(keys, resolve(base, '.env'));
+  const existingSet = new Set(existingKeys);
+
+  const result: ManifestStatus = {
+    pending: [],
+    collected: [],
+    skipped: [],
+    existing: [],
+  };
+
+  for (const entry of manifest.entries) {
+    if (existingSet.has(entry.key)) {
+      result.existing.push(entry.key);
+    } else {
+      result[entry.status].push(entry.key);
+    }
+  }
+
+  return result;
+}