magus-cli 7.5.1 → 7.5.3

package/src/__tests__/update-apply.test.ts

@@ -25,7 +25,7 @@ import type {
 	PluginUpdateItem,
 	UpdatePlan,
 } from "../services/update-plan.js";
-import type { ResolvedBin } from "../types/index.js";
+import type { InstalledPluginEntry, ResolvedBin } from "../types/index.js";
 import { noMoveReasons } from "../ui/adapters/pluginsAdapter.js";
 
 const PROJECT = "/tmp/project";
@@ -925,3 +925,199 @@ describe("B4: an install or update ends with the loader on the new version", ()
 		).rejects.toThrow("the loader still resolves v1.0.0 here, not v2.0.0");
 	});
 });
+
+// ── 7.5.2: Claude Code 2.1.281 updates ANOTHER project's row ─────────────────
+//
+// `claude plugin update P --scope project` under 2.1.281 moves the repository's
+// FIRST relevant registry row — the one its loader would pick — not this
+// project's. Measured 2026-09-24, same registry, cwd = the project:
+//   2.1.280  updated from 8.0.0 to 8.1.3 for scope project (<sandbox>/magus-src)
+//   2.1.281  updated from 8.0.0 to 8.1.3 for scope project (<sandbox>/magus-src/tools/claudeup)
+// This project's row stayed at 8.0.0, and `magus update` said "no change".
+
+describe("7.5.2: an update Claude Code applied to another project's row", () => {
+	const HERE = "/tmp/project";
+	const OTHER = "/tmp/project/tools/claudeup";
+	const UNRELATED = "/tmp/another-repository";
+
+	/**
+	 * A registry for dev@magus — another project's row of the same repository
+	 * first, this project's second — and a fake Claude CLI that updates either
+	 * the first relevant row (`"2.1.281"`) or this project's (`"2.1.280"`).
+	 */
+	function registry(
+		cli: "2.1.280" | "2.1.281" | "unrelated" | "other-version",
+		cached: string[] = ["8.1.3", "8.5.0"],
+	) {
+		const rows: InstalledPluginEntry[] = [
+			{
+				scope: "project",
+				projectPath: OTHER,
+				version: "8.0.0",
+			} as InstalledPluginEntry,
+			{
+				scope: "project",
+				projectPath: HERE,
+				version: "8.0.0",
+			} as InstalledPluginEntry,
+			{
+				scope: "project",
+				projectPath: UNRELATED,
+				version: "8.0.0",
+			} as InstalledPluginEntry,
+		];
+		const repaired: string[] = [];
+		const saved: string[] = [];
+		const row = (projectPath: string) =>
+			rows.find((r) => r.projectPath === projectPath) as InstalledPluginEntry;
+		const deps: PluginApplyDeps = {
+			install: async () => {},
+			update: async () => {
+				if (cli === "2.1.280") row(HERE).version = "8.1.3";
+				if (cli === "2.1.281") row(OTHER).version = "8.1.3";
+				// Another repository's row moving while the CLI runs.
+				if (cli === "unrelated") row(UNRELATED).version = "8.1.3";
+				// This repository's row, but not to the version this update targets.
+				if (cli === "other-version") row(OTHER).version = "8.5.0";
+			},
+			repair: async () => {},
+			readInstalled: async (_id, scope, projectPath) =>
+				scope === "project" ? (row(projectPath)?.version ?? null) : null,
+			saveInstalled: async (_id, version) => {
+				saved.push(version);
+			},
+			registryRows: async () => rows.map((r) => ({ ...r })),
+			// Same repository = this project's tree, as git would answer.
+			inThisRepository: (r, projectPath) =>
+				(r.projectPath ?? "").startsWith(projectPath),
+			// What repairStaleLoad does: refuse an uncached target, else move every
+			// row of this repository that is behind it.
+			repairStaleLoad: async (pluginId, target) => {
+				repaired.push(target);
+				if (!cached.includes(target)) {
+					return {
+						pluginId,
+						target,
+						rewritten: 0,
+						backup: null,
+						loaded: null,
+						ok: false,
+						error: `no cache directory for v${target}`,
+					};
+				}
+				let rewritten = 0;
+				for (const r of rows) {
+					if (r.projectPath?.startsWith(HERE) && r.version !== target) {
+						r.version = target;
+						rewritten++;
+					}
+				}
+				return {
+					pluginId,
+					target,
+					rewritten,
+					backup: null,
+					loaded: target,
+					ok: true,
+				};
+			},
+			// The loader: the first relevant row.
+			loadedVersion: async () => rows[0]?.version ?? null,
+		};
+		return { rows, deps, repaired, saved, row };
+	}
+
+	const update = () =>
+		item({
+			installed: "8.0.0",
+			available: "8.1.3",
+			target: "8.1.3",
+			beforeVersions: { project: "8.0.0" },
+		});
+
+	test("7.5.2: under 2.1.281 this project's row follows to the fetched version, reported as updated", async () => {
+		const { deps, row, repaired, saved } = registry("2.1.281");
+		const { reporter, rows } = recordingReporter();
+
+		const result = await applyPlugins([update()], HERE, deps, reporter);
+
+		expect(row(HERE).version).toBe("8.1.3");
+		expect(row(OTHER).version).toBe("8.1.3"); // the CLI's change stands
+		expect(repaired).toEqual(["8.1.3"]);
+		expect(saved).toEqual(["8.1.3"]);
+		expect(result.ok).toBe(1);
+		expect(result.unchanged).toEqual([]);
+		expect(rows).toEqual([
+			{
+				ok: true,
+				name: "dev@magus",
+				detail: `project → 8.1.3 · Claude Code updated ${OTHER} instead of this project — moved this project's record to v8.1.3 too`,
+			},
+		]);
+	});
+
+	test("7.5.2: under 2.1.280 the CLI updates this project's row and nothing extra happens", async () => {
+		const { deps, row, repaired } = registry("2.1.280");
+		const { reporter, rows } = recordingReporter();
+
+		const result = await applyPlugins([update()], HERE, deps, reporter);
+
+		expect(row(HERE).version).toBe("8.1.3");
+		expect(result.ok).toBe(1);
+		// Exactly 7.5.1's outcome: the older row ahead of this one is brought
+		// forward by the loader check (B4), and no misdirection is reported.
+		expect(repaired).toEqual(["8.1.3"]);
+		expect(rows[0]?.detail).toBe(
+			"project → 8.1.3 · Claude Code now loads v8.1.3 here (1 older record moved forward)",
+		);
+	});
+
+	test("7.5.2: a version the CLI did not cache is not followed — still an honest no change", async () => {
+		const { deps, row } = registry("2.1.281", []);
+		const { reporter, rows } = recordingReporter();
+
+		const result = await applyPlugins([update()], HERE, deps, reporter);
+
+		expect(row(HERE).version).toBe("8.0.0");
+		expect(result.unchanged).toEqual(["dev@magus"]);
+		expect(rows[0]?.detail).toBe(
+			`no change — the installer exited 0 but dev@magus is still 8.0.0 (Claude Code updated ${OTHER} instead of this project, and this project's record could not follow: no cache directory for v8.1.3)`,
+		);
+	});
+
+	test("7.5.2 review: a row of ANOTHER repository moving to the target is not followed", async () => {
+		const { deps, row, repaired } = registry("unrelated");
+		const { reporter, rows } = recordingReporter();
+
+		const result = await applyPlugins([update()], HERE, deps, reporter);
+
+		expect(row(HERE).version).toBe("8.0.0");
+		expect(repaired).toEqual([]);
+		expect(result.unchanged).toEqual(["dev@magus"]);
+		expect(rows[0]?.detail).toBe(
+			"no change — the installer exited 0 but dev@magus is still 8.0.0",
+		);
+	});
+
+	test("7.5.2 review: this repository's row moving to a version other than the target is not followed", async () => {
+		const { deps, row, repaired } = registry("other-version");
+		const { reporter, rows } = recordingReporter();
+
+		const result = await applyPlugins([update()], HERE, deps, reporter);
+
+		expect(row(HERE).version).toBe("8.0.0");
+		expect(repaired).toEqual([]);
+		expect(result.unchanged).toEqual(["dev@magus"]);
+		expect(rows[0]?.detail).toBe(
+			`no change — the installer exited 0 but dev@magus is still 8.0.0 (Claude Code updated ${OTHER} instead of this project, and this project's record could not follow: it went to v8.5.0, not the v8.1.3 this update asked for)`,
+		);
+	});
+
+	test("7.5.2: the TUI's per-scope update key follows it too", async () => {
+		const { deps, row } = registry("2.1.281");
+		expect(await updatePluginInScope("dev@magus", "project", HERE, deps)).toBe(
+			"8.1.3",
+		);
+		expect(row(HERE).version).toBe("8.1.3");
+	});
+});

package/src/cli/bootstrap.ts

@@ -18,7 +18,6 @@ import {
 	type ActivationResult,
 	activateProfile,
 	activationNotes,
-	assertNoTrackedWriteTargets,
 	reportDisplaced,
 } from "../services/profile-activate.js";
 import {
@@ -84,9 +83,6 @@ async function writeAndActivate(
 	// their hand-written files went.
 	const rel = (p: string) => path.relative(projectPath, p);
 
-	// Before the manifest is written: adopting activates, and activating a
-	// project whose settings.json git tracks would take that file over.
-	await assertNoTrackedWriteTargets(projectPath);
 	await writeManifest(result.manifest, projectPath);
 	console.log(`✓ Wrote ${rel(getManifestPath(projectPath))}`);
 

package/src/cli/doctor.ts

@@ -46,7 +46,7 @@ import {
 	type RepoRootCache,
 	pickLoadedEntry,
 } from "../services/plugin-resolution.js";
-import { trackedGeneratedFiles } from "../services/profile-activate.js";
+import { trackedGeneratedWarnings } from "../services/profile-activate.js";
 import {
 	LIVE_FILE_KEYS,
 	liveKind,
@@ -67,10 +67,6 @@ import {
 	switchHint,
 } from "../services/profile-state.js";
 import { resolveAllProfiles } from "../services/resolver.js";
-import {
-	GitCheckError,
-	untrackCommand,
-} from "../services/tracked-live-files.js";
 import type {
 	ClaudeSettings,
 	InstalledPluginsRegistry,
@@ -556,21 +552,11 @@ export async function reportProfileState(
 		}
 	}
 
-	// A .gitignore entry does not untrack a file committed before it. Report
-	// only: magus never runs git rm.
-	let tracked: string[] = [];
-	try {
-		tracked = await trackedGeneratedFiles(projectPath);
-	} catch (error) {
-		if (!(error instanceof GitCheckError)) throw error;
-		console.log(`✗ ${error.message}`);
-		unfixable++;
-	}
-	for (const rel of tracked) {
-		console.log(
-			`✗ ${rel} is generated from profiles.json but tracked by git. Fix: \`${untrackCommand(rel)}\`, then commit.`,
-		);
-		unfixable++;
+	// A .gitignore entry does not untrack a file committed before it. A note
+	// with the fix, not a failure: magus writes the file all the same, and
+	// never runs git rm itself.
+	for (const line of await trackedGeneratedWarnings(projectPath)) {
+		console.log(`• ${line}`);
 	}
 	return { fixable, unfixable };
 }

package/src/cli/router.ts

@@ -8,7 +8,7 @@
 
 import type { ThemeMode } from "@opentui/core";
 import { SettingsParseError } from "../services/settings-file.js";
-import { LiveFileRefusal } from "../services/tracked-live-files.js";
+import { GitCheckError } from "../services/tracked-live-files.js";
 import { checkForUpdates } from "../services/version-check.js";
 import { type ThemeEnv, parseThemeWord } from "../ui/theme-resolve.js";
 import { profileGate, reportUnparseable } from "./bootstrap.js";
@@ -224,9 +224,10 @@ export async function route(
 			reportUnparseable(error);
 			return HANDLED(1);
 		}
-		// A live file git tracks (or git could not say): nothing was written,
-		// and the message says what to do. A refusal, not a crash.
-		if (error instanceof LiveFileRefusal) {
+		// git could not say what it tracks, and converting an older layout needs
+		// to know which skill folders the team committed. git's own message, not
+		// a stack trace.
+		if (error instanceof GitCheckError) {
 			console.error(error.message);
 			return HANDLED(1);
 		}

package/src/cli/update.ts

@@ -51,6 +51,7 @@ import {
 import {
 	recordRefetchedSkills,
 	trackFetchedSkills,
+	trackedGeneratedWarnings,
 	updatableSkills,
 } from "../services/profile-activate.js";
 import { activeProfile } from "../services/profile-live.js";
@@ -202,6 +203,12 @@ export async function runUpdateCommand(
 		return 1;
 	}
 
+	// A generated file git tracks is written like any other; say so once, with
+	// the fix. magus never runs git itself.
+	for (const line of await trackedGeneratedWarnings(projectPath)) {
+		console.log(warnLine(line));
+	}
+
 	// No active profile, no update: that is where plugin state is read from and
 	// where changes are written. Asked before the profile is resolved, so what
 	// the user activates here is what this run uses.

package/src/services/claude-cli.ts

@@ -10,7 +10,6 @@
  */
 
 import { execFile } from "node:child_process";
-import path from "node:path";
 import { promisify } from "node:util";
 import { defaultMarketplaces } from "../data/marketplaces.js";
 import { which } from "../utils/command-utils.js";
@@ -20,7 +19,6 @@ import {
 	removeLocalInstalledPluginVersion,
 } from "./claude-settings.js";
 import { removeInstalledPluginVersion } from "./plugin-manager.js";
-import { refuseTrackedLiveFiles } from "./tracked-live-files.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -140,23 +138,6 @@ async function execPluginCommand(
 	}
 }
 
-/**
- * Every `claude plugin … --scope project` command writes the project's
- * `.claude/settings.json` (its enabledPlugins entry). In a project with
- * profiles that file is generated; where git tracks it, refuse — before the
- * CLI runs — rather than let the CLI write it (see `tracked-live-files.ts`).
- * The CLI works on the current directory.
- */
-async function refuseProjectSettingsWrite(
-	scope: PluginScope,
-	projectPath: string = process.cwd(),
-): Promise<void> {
-	if (scope !== "project") return;
-	await refuseTrackedLiveFiles(projectPath, [
-		path.join(".claude", "settings.json"),
-	]);
-}
-
 /**
  * Install a plugin using claude CLI
  * Handles enabling + version tracking + cache copy in one shot.
@@ -173,7 +154,6 @@ export async function installPlugin(
 	pluginId: string,
 	scope: PluginScope = "user",
 ): Promise<void> {
-	await refuseProjectSettingsWrite(scope);
 	// 60s, matching update and repair. Before the install/update split this path
 	// ran through `updatePlugin`'s 60s budget; leaving it on the 30s default
 	// would have quietly halved the time a fresh install — the SLOWEST of the
@@ -192,7 +172,6 @@ export async function uninstallPlugin(
 	scope: PluginScope = "user",
 	projectPath?: string,
 ): Promise<void> {
-	await refuseProjectSettingsWrite(scope, projectPath);
 	try {
 		await execClaude(["plugin", "uninstall", pluginId, "--scope", scope]);
 	} catch {
@@ -245,7 +224,6 @@ export async function enablePlugin(
 	pluginId: string,
 	scope: PluginScope = "user",
 ): Promise<void> {
-	await refuseProjectSettingsWrite(scope);
 	await execClaude(["plugin", "enable", pluginId, "--scope", scope]);
 }
 
@@ -256,7 +234,6 @@ export async function disablePlugin(
 	pluginId: string,
 	scope: PluginScope = "user",
 ): Promise<void> {
-	await refuseProjectSettingsWrite(scope);
 	await execClaude(["plugin", "disable", pluginId, "--scope", scope]);
 }
 
@@ -299,7 +276,6 @@ export async function updatePlugin(
 	pluginId: string,
 	scope: PluginScope = "user",
 ): Promise<void> {
-	await refuseProjectSettingsWrite(scope);
 	await execPluginCommand("update", pluginId, scope, 60000);
 }
 

package/src/services/claude-settings.ts

@@ -37,7 +37,6 @@ import {
 	writableList,
 	writableMap,
 } from "./settings-file.js";
-import { refuseTrackedLiveFiles } from "./tracked-live-files.js";
 
 /**
  * What every reader below throws for a file that exists but does not parse.
@@ -149,11 +148,6 @@ export async function writeSettings(
 	settings: ClaudeSettings,
 	projectPath?: string,
 ): Promise<void> {
-	// In a project with profiles this file is generated: never written where
-	// git tracks it (see `tracked-live-files.ts`).
-	await refuseTrackedLiveFiles(projectPath ?? process.cwd(), [
-		getSettingsPath(projectPath),
-	]);
 	await refuseUnwritableFile(getSettingsPath(projectPath));
 	const claudeDir = await ensureClaudeDir(projectPath);
 	const settingsPath = path.join(claudeDir, SETTINGS_FILE);
@@ -197,7 +191,6 @@ export async function writeMcpConfig(
 	projectPath?: string,
 ): Promise<void> {
 	const mcpPath = getMcpConfigPath(projectPath);
-	await refuseTrackedLiveFiles(projectPath ?? process.cwd(), [mcpPath]);
 	await refuseUnwritableFile(mcpPath);
 	await fs.writeJson(mcpPath, config, { spaces: 2 });
 }
@@ -1991,6 +1984,24 @@ function belongsToThisRepository(
 	return repoRootForPath(entry.projectPath, cache) === cwdRoot;
 }
 
+/**
+ * Is `entry` a row of the repository `projectPath` is in — one
+ * {@link repairStaleLoad} may rewrite? The same predicate, for callers that
+ * judge one row at a time.
+ */
+export function rowBelongsToRepository(
+	entry: InstalledPluginEntry,
+	projectPath: string,
+): boolean {
+	const cache: RepoRootCache = new Map();
+	return belongsToThisRepository(
+		entry,
+		projectPath,
+		repoRootForPath(projectPath, cache),
+		cache,
+	);
+}
+
 /** A plugin whose loader-resolved version is behind a row this repair can rewrite. */
 export interface StaleLoad {
 	pluginId: string;

package/src/services/gitignore-check.ts

@@ -1,63 +1,51 @@
 /**
- * Read-only gitignore check for the gitignore manager.
+ * The TUI's startup gitignore question.
  *
- * Called from the TUI on startup and from `doctor`. Resolves the manifest, runs
- * detection, and returns a concise warning when violations exist. Does NOT
- * auto-apply fixes — the user must open the Git State tab and confirm. This
- * mirrors the plugin-version-mismatch flow, where the check only *reports* and
- * the TUI provides the interactive fix dialog.
+ * Asked on every open (and again after a first adoption). Resolves the
+ * manifest — including, in a project with profiles, the files magus generates
+ * from `.claude/profiles.json` — runs detection, and reports. Nothing here
+ * applies a fix: the startup question applies the in-place fix only when the
+ * user picks it (`applyStartupFixes`), and every other destructive fix is
+ * confirmed per item in the Git State tab.
  */
 
 import type { Violation } from "../types/gitignore.js";
-import { detectViolations } from "./gitignore-detector.js";
-import { formatViolationSummary } from "./gitignore-fixer.js";
-import { resolveGitignore } from "./gitignore-resolver.js";
+import { loadGitignoreState } from "./gitignore-service.js";
 
-export interface GitignoreCheckResult {
+/** What the TUI's startup gitignore question needs to show. */
+export interface StartupGitignoreNeed {
 	violationCount: number;
-	warnings: string[];
-}
-
-export async function checkGitignore(
-	cwd: string,
-): Promise<GitignoreCheckResult> {
-	const warnings: string[] = [];
-	try {
-		const resolved = await resolveGitignore(cwd, {
-			logger: (m) => warnings.push(m),
-		});
-		const violations = await detectViolations(cwd, resolved);
-		return {
-			violationCount: violations.length,
-			warnings,
-		};
-	} catch (err) {
-		warnings.push(
-			`[gitignore] check failed: ${err instanceof Error ? err.message : String(err)}`,
-		);
-		return { violationCount: 0, warnings };
-	}
+	/** Missing `.gitignore` entries — the additive fix. */
+	safeCount: number;
+	/**
+	 * Files magus generates from `.claude/profiles.json` that git tracks — the
+	 * ones the startup fix untracks in place.
+	 */
+	generated: string[];
 }
 
 /**
- * One-line summary suitable for stderr. Returns null when there's
- * nothing to warn about.
+ * The startup gitignore question, or null when there is nothing to ask.
+ *
+ * Asked fresh on every call — the TUI calls it on every open, and again after
+ * a first adoption — and nothing remembers an earlier answer: a tracked
+ * generated file is asked about until it is fixed.
  */
-export function formatGitignoreWarning(
-	result: GitignoreCheckResult,
-): string | null {
-	if (result.violationCount === 0) return null;
-	return `⚠ ${result.violationCount} git state issue(s) detected. Run: magus → Git State tab to review and fix`;
+export async function startupGitignoreNeed(
+	cwd: string,
+): Promise<StartupGitignoreNeed | null> {
+	const { violations } = await loadGitignoreState(cwd);
+	if (violations.length === 0) return null;
+	return {
+		violationCount: violations.length,
+		safeCount: violations.filter((v) => v.severity === "safe").length,
+		generated: generatedTracked(violations).map((v) => v.path),
+	};
 }
 
-/**
- * Verbose multi-line summary, used by the Git State tab when the user wants
- * to know what's wrong before deciding what to do.
- */
-export async function describeViolations(
-	cwd: string,
-	violations: Violation[],
-): Promise<string> {
-	void cwd;
-	return formatViolationSummary(violations);
+/** The violations the startup fix handles in place: tracked generated files. */
+export function generatedTracked(violations: Violation[]): Violation[] {
+	return violations.filter(
+		(v) => v.kind === "tracked-but-should-ignore" && v.source === "profile",
+	);
 }

package/src/services/gitignore-resolver.ts

@@ -5,6 +5,10 @@
  *   1. Built-in defaults (shipped with magus)
  *   2. Global manifest at ~/.claude/gitignore.json (team-level, manually shared)
  *   3. Project manifest at <cwd>/.claude/gitignore.json
+ *   4. Profile: in a project with profiles, the files magus generates from
+ *      `.claude/profiles.json` (passed in as `opts.profile`). Highest, because
+ *      those files are rewritten per developer — tracking one cannot be right
+ *      whatever another manifest says.
  *
  * `extends` references are resolved against BUILTIN_TEMPLATES. Within a single
  * tier, the same pattern cannot appear in both `ignore` and `track` — that
@@ -33,9 +37,11 @@ export interface ResolveOptions {
 	homeDir?: string;
 	/** Optional logger for non-fatal warnings (malformed JSON, missing template). */
 	logger?: (msg: string) => void;
+	/** The profile tier — see `profileGitignoreManifest`. */
+	profile?: GitignoreManifest | null;
 }
 
-const TIER_ORDER: Tier[] = ["builtin", "global", "project"];
+const TIER_ORDER: Tier[] = ["builtin", "global", "project", "profile"];
 
 export async function resolveGitignore(
 	projectCwd: string,
@@ -59,6 +65,9 @@ export async function resolveGitignore(
 	const projectManifest = await readManifest(projectPath, log);
 	if (projectManifest) tierManifests.set("project", projectManifest);
 
+	// 4. The files the profile model generates
+	if (opts.profile) tierManifests.set("profile", opts.profile);
+
 	// Apply `extends` for each tier (templates count as part of their tier)
 	for (const tier of TIER_ORDER) {
 		const m = tierManifests.get(tier);

package/src/services/gitignore-service.ts

@@ -28,6 +28,7 @@ import {
 } from "./gitignore-fixer.js";
 import { resolveGitignore } from "./gitignore-resolver.js";
 import { readSettingsFile, writableList } from "./settings-file.js";
+import { profileGitignoreManifest } from "./tracked-live-files.js";
 
 export interface GitignoreState {
 	resolved: ResolvedManifest;
@@ -40,11 +41,77 @@ export async function loadGitignoreState(cwd: string): Promise<GitignoreState> {
 	const warnings: string[] = [];
 	const resolved = await resolveGitignore(cwd, {
 		logger: (m) => warnings.push(m),
+		profile: await profileGitignoreManifest(cwd),
 	});
 	const violations = await detectViolations(cwd, resolved);
 	return { resolved, violations, warnings };
 }
 
+export interface StartupFixResult {
+	/** Generated files removed from the index — staged, not committed. */
+	untracked: string[];
+	/** `.gitignore` entries added. */
+	appended: string[];
+	/** Files that could not be untracked, with git's reason. */
+	failed: Array<{ path: string; reason: string }>;
+}
+
+/**
+ * The startup question's fix, applied in place: every file magus generates
+ * from `.claude/profiles.json` that git tracks is removed from the index
+ * (`git rm --cached`, the existing tracked-but-should-ignore fix, which also
+ * makes sure `.gitignore` ignores it), and the additive `.gitignore` fixes
+ * are applied too. Every other violation is left for the Git State tab.
+ */
+export async function applyStartupFixes(
+	cwd: string,
+): Promise<StartupFixResult> {
+	const { resolved, violations } = await loadGitignoreState(cwd);
+	const generatedRules = resolved.rules
+		.filter((r) => r.source === "profile" && r.action === "ignore")
+		.map((r) => r.pattern);
+	const result: StartupFixResult = { untracked: [], appended: [], failed: [] };
+	for (const v of violations) {
+		if (v.kind !== "tracked-but-should-ignore" || v.source !== "profile") {
+			continue;
+		}
+		const rule =
+			generatedRules.find(
+				(p) => p === v.path || (p.endsWith("/") && v.path.startsWith(p)),
+			) ?? v.path;
+		try {
+			await coreApplyDestructiveFix(cwd, v, rule);
+			result.untracked.push(v.path);
+		} catch (error) {
+			result.failed.push({
+				path: v.path,
+				reason: error instanceof Error ? error.message : String(error),
+			});
+		}
+	}
+	result.appended = (await coreApplySafeFixes(cwd, violations)).appended;
+	return result;
+}
+
+/** What {@link applyStartupFixes} did, for the message the TUI shows. */
+export function describeStartupFix(result: StartupFixResult): string {
+	const lines: string[] = [];
+	if (result.untracked.length > 0) {
+		lines.push(
+			"Stopped tracking (the removal is staged — commit it):",
+			...result.untracked.map((p) => `  ${p}`),
+			'  git commit -m "Stop tracking generated Claude Code config"',
+		);
+	}
+	if (result.appended.length > 0) {
+		lines.push("Added to .gitignore:", ...result.appended.map((p) => `  ${p}`));
+	}
+	for (const f of result.failed) {
+		lines.push(`Could not untrack ${f.path}: ${f.reason}`);
+	}
+	return lines.length > 0 ? lines.join("\n") : "Nothing needed changing.";
+}
+
 export async function applyAllSafeFixes(
 	cwd: string,
 	violations: Violation[],