peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/services/skills/skill-registry.js

@@ -0,0 +1,67 @@
+import { join } from 'node:path';
+import { listDirectories, pathExists, readText } from '../../shared/fs.js';
+import { parseFrontmatter } from '../../shared/frontmatter.js';
+import { skillsDir } from '../../shared/paths.js';
+function getLoadFailureMessage(error) {
+    return error instanceof Error ? error.message : 'Unable to parse skill metadata';
+}
+export async function loadSkillRegistry(baseDir = skillsDir) {
+    if (!(await pathExists(baseDir))) {
+        return { skills: [], failures: [] };
+    }
+    const directories = await listDirectories(baseDir);
+    const skills = [];
+    const failures = [];
+    for (const directory of directories) {
+        // LLM-internal skills (bees) live under `bee/` per spec 2026-07-05.
+        // Recurse one level into `bee/`; treat each child as a separate skill.
+        if (directory === 'bee') {
+            const subEntries = await listDirectories(join(baseDir, 'bee'));
+            for (const subDir of subEntries) {
+                const skillPath = join(baseDir, 'bee', subDir, 'SKILL.md');
+                if (!(await pathExists(skillPath))) {
+                    continue;
+                }
+                try {
+                    const frontmatter = parseFrontmatter(await readText(skillPath));
+                    // `directory` is the on-disk skill folder name; for bees that is the
+                    // basename of the bee child, NOT `bee/<name>` (keeps the
+                    // doctor skill-name-matches-directory invariant working).
+                    skills.push({
+                        name: frontmatter.name,
+                        description: frontmatter.description,
+                        directory: subDir,
+                        skillPath
+                    });
+                }
+                catch (error) {
+                    failures.push({ directory: subDir, skillPath, message: getLoadFailureMessage(error) });
+                }
+            }
+            continue;
+        }
+        const skillPath = join(baseDir, directory, 'SKILL.md');
+        if (!(await pathExists(skillPath))) {
+            continue;
+        }
+        try {
+            const frontmatter = parseFrontmatter(await readText(skillPath));
+            skills.push({
+                name: frontmatter.name,
+                description: frontmatter.description,
+                directory,
+                skillPath
+            });
+        }
+        catch (error) {
+            failures.push({ directory, skillPath, message: getLoadFailureMessage(error) });
+        }
+    }
+    return {
+        skills: skills.sort((left, right) => left.name.localeCompare(right.name)),
+        failures: failures.sort((left, right) => left.directory.localeCompare(right.directory))
+    };
+}
+export async function listSkills(baseDir = skillsDir) {
+    return (await loadSkillRegistry(baseDir)).skills;
+}

package/dist/services/skills/skill-runbook-service.d.ts

@@ -0,0 +1,11 @@
+export type SkillRunbookInspection = {
+    name: string;
+    directory: string;
+    hasRunbook: boolean;
+    peaksCommandCount: number;
+    peaksCommandLines: string[];
+    destructiveApplyLines: string[];
+    hasAuthorizationNote: boolean;
+    ok: boolean;
+};
+export declare function inspectSkillRunbook(name: string, baseDir?: string): Promise<SkillRunbookInspection>;

package/dist/services/skills/skill-runbook-service.js

@@ -0,0 +1,128 @@
+import { dirname, join } from 'node:path';
+import * as path from 'node:path';
+import { readText } from '../../shared/fs.js';
+import { loadSkillRegistry } from './skill-registry.js';
+const DESTRUCTIVE_APPLY_PATTERNS = [
+    /peaks\s+memory\s+sync[^\n]*--apply/,
+    /peaks\s+memory\s+extract[^\n]*--apply/,
+    /peaks\s+artifacts\s+sync[^\n]*--apply/,
+    /peaks\s+openspec\s+archive[^\n]*--apply/,
+    /peaks\s+standards\s+(?:init|update)[^\n]*--apply/,
+    /peaks\s+workspace\s+reconcile[^\n]*--apply/
+];
+const AUTHORIZATION_KEYWORDS_PATTERN = /authoriz|explicit|--dry-run|approv|only after|only when/i;
+const PEAKS_COMMAND_LINE_PATTERN = /^\s*peaks\s+\w/;
+function extractRunbookSection(body) {
+    // Find a `## Default runbook` heading at the start of a line, then capture
+    // the section body up to the next `## ` heading or end of input.
+    //
+    // Implementation note: we avoid a regex with a multiline `(?=\n## |$)`
+    // lookahead because the `m` flag turns `$` into "end of any line" in
+    // JavaScript, which would let the lazy capture stop at the first `\n`.
+    // Instead, we (a) use the regex only to locate the heading, then (b)
+    // manually scan forward for the next `## ` heading or end of input.
+    const headingRe = /^## Default runbook[^\n]*(?:\n|$)/m;
+    const headingMatch = headingRe.exec(body);
+    if (headingMatch === null)
+        return null;
+    const startAfter = headingMatch.index + headingMatch[0].length;
+    const rest = body.slice(startAfter);
+    // Find the next `## ` heading at the start of a line.
+    const nextHeadingRe = /^## /m;
+    const nextMatch = nextHeadingRe.exec(rest);
+    const end = nextMatch === null ? rest.length : nextMatch.index;
+    return rest.slice(0, end);
+}
+/**
+ * Load the runbook section, falling back to `references/runbook.md` if the
+ * SKILL.md only has a pointer section. This supports skills (notably
+ * `peaks-code`) that extracted their 150-line bash runbook to a sibling
+ * reference to keep SKILL.md under the 800-line cap. The CLI
+ * `peaks skill runbook` command uses the same fallback so a human
+ * reviewer sees the full runbook regardless of where it lives.
+ *
+ * Strategy: prefer the LONGER of the two sections. A short pointer section
+ * in SKILL.md (~ 1-2 lines) is treated as a "this runbook is in the
+ * reference" marker; a long inline section (>= the reference length) is
+ * treated as the canonical runbook. This avoids the false positive where
+ * the pointer section's regex match returns a non-null but content-poor
+ * string.
+ */
+async function loadRunbookSection(skillPath, body) {
+    const inline = extractRunbookSection(body);
+    const skillDir = dirname(skillPath);
+    // Try multiple reference filenames. Convention: each skill may name its
+    // runbook file `runbook.md` (the generic name, used by peaks-code), or
+    // `<role>-runbook.md` (the role-suffixed name, used by peaks-rd → rd-runbook.md,
+    // peaks-qa → qa-runbook.md, etc.). Prefer the longest extracted section.
+    const refCandidates = [
+        join(skillDir, 'references', 'runbook.md'),
+        join(skillDir, 'references', `${path.basename(skillDir).replace(/^peaks-/, '')}-runbook.md`)
+    ];
+    let bestRef = null;
+    for (const refPath of refCandidates) {
+        try {
+            const refBody = await readText(refPath);
+            const refSection = extractRunbookSection(refBody);
+            if (refSection === null)
+                continue;
+            if (bestRef === null || refSection.length > bestRef.length) {
+                bestRef = refSection;
+            }
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // candidate not present or unreadable; try the next one
+        }
+    }
+    const refSection = bestRef;
+    if (inline === null)
+        return refSection;
+    if (refSection === null)
+        return inline;
+    return inline.length >= refSection.length ? inline : refSection;
+}
+function findDestructiveApplyLines(section) {
+    const lines = section.split(/\r?\n/);
+    return lines.filter((line) => DESTRUCTIVE_APPLY_PATTERNS.some((pattern) => pattern.test(line)));
+}
+function findPeaksCommandLines(section) {
+    return section
+        .split(/\r?\n/)
+        .filter((line) => PEAKS_COMMAND_LINE_PATTERN.test(line))
+        .map((line) => line.trim());
+}
+export async function inspectSkillRunbook(name, baseDir) {
+    const registry = await loadSkillRegistry(baseDir);
+    const skill = registry.skills.find((entry) => entry.name === name);
+    if (skill === undefined) {
+        throw new Error(`Skill "${name}" not found under skills directory`);
+    }
+    const body = await readText(skill.skillPath);
+    const section = await loadRunbookSection(skill.skillPath, body);
+    if (section === null) {
+        return {
+            name: skill.name,
+            directory: skill.directory,
+            hasRunbook: false,
+            peaksCommandCount: 0,
+            peaksCommandLines: [],
+            destructiveApplyLines: [],
+            hasAuthorizationNote: false,
+            ok: false
+        };
+    }
+    const peaksCommandLines = findPeaksCommandLines(section);
+    const destructiveApplyLines = findDestructiveApplyLines(section);
+    const hasAuthorizationNote = AUTHORIZATION_KEYWORDS_PATTERN.test(section);
+    const ok = destructiveApplyLines.length === 0 || hasAuthorizationNote;
+    return {
+        name: skill.name,
+        directory: skill.directory,
+        hasRunbook: true,
+        peaksCommandCount: peaksCommandLines.length,
+        peaksCommandLines,
+        destructiveApplyLines,
+        hasAuthorizationNote,
+        ok
+    };
+}

package/dist/services/skills/skill-statusline-renderer.d.ts

@@ -0,0 +1,6 @@
+import type { StatusLineModel } from './skill-statusline-service.js';
+/**
+ * Render the status line. The output is plain text with simple status glyphs so
+ * it stays readable in any terminal; Claude Code applies its own styling.
+ */
+export declare function renderStatusLine(model: StatusLineModel): string;

package/dist/services/skills/skill-statusline-renderer.js

@@ -0,0 +1,55 @@
+import { basename } from 'node:path';
+/**
+ * Pure formatting layer for the Peaks statusLine. Takes the read-only status
+ * model and produces the single line Claude Code paints at the bottom of the
+ * terminal. Kept separate from the reader so formatting can be tested without
+ * touching the filesystem.
+ */
+const BRAND = '⛰ Peaks';
+function formatAge(ageMs) {
+    if (ageMs === null)
+        return '';
+    const hours = Math.round(ageMs / (60 * 60 * 1000));
+    if (hours >= 1)
+        return `stale ${hours}h`;
+    const minutes = Math.max(1, Math.round(ageMs / (60 * 1000)));
+    return `stale ${minutes}m`;
+}
+function rootLabel(projectRoot) {
+    if (!projectRoot)
+        return '';
+    return basename(projectRoot);
+}
+/**
+ * Render the status line. The output is plain text with simple status glyphs so
+ * it stays readable in any terminal; Claude Code applies its own styling.
+ */
+export function renderStatusLine(model) {
+    const root = rootLabel(model.projectRoot);
+    const rootSuffix = root ? ` · ${root}` : '';
+    switch (model.state) {
+        case 'active': {
+            const presence = model.presence;
+            if (!presence)
+                return `${BRAND} ○ idle${rootSuffix}`;
+            const parts = [presence.skill];
+            if (presence.mode)
+                parts.push(presence.mode);
+            if (presence.gate)
+                parts.push(`gate:${presence.gate}`);
+            return `${BRAND} ● ${parts.join(' · ')}${rootSuffix}`;
+        }
+        case 'stale': {
+            const presence = model.presence;
+            const skill = presence?.skill ?? 'unknown';
+            const age = formatAge(model.ageMs);
+            const ageSuffix = age ? ` · ${age}` : '';
+            return `${BRAND} ⚠ ${skill}${ageSuffix}${rootSuffix}`;
+        }
+        case 'invalid-presence':
+            return `${BRAND} ⚠ presence file unreadable${rootSuffix}`;
+        case 'idle':
+        default:
+            return `${BRAND} ○ idle${rootSuffix}`;
+    }
+}

package/dist/services/skills/skill-statusline-service.d.ts

@@ -0,0 +1,24 @@
+export type StatusLineStdin = {
+    workspace?: {
+        current_dir?: string;
+        project_dir?: string;
+    };
+    cwd?: string;
+    session_id?: string;
+};
+export type StatusLineState = 'active' | 'idle' | 'stale' | 'invalid-presence';
+export type StatusLinePresence = {
+    skill: string;
+    mode?: string;
+    gate?: string;
+    setAt?: string;
+    claudeSessionId?: string;
+};
+export type StatusLineModel = {
+    state: StatusLineState;
+    projectRoot: string | null;
+    presence: StatusLinePresence | null;
+    ageMs: number | null;
+};
+export declare function parseStatusLineStdin(raw: string): StatusLineStdin | null;
+export declare function buildStatusLineModel(stdin: StatusLineStdin | null, nowMs: number): StatusLineModel;

package/dist/services/skills/skill-statusline-service.js

@@ -0,0 +1,110 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { findProjectRoot } from '../config/config-safety.js';
+/**
+ * Out-of-band Peaks skill status renderer for the Claude Code statusLine.
+ *
+ * Claude Code invokes the configured statusLine command on every turn and pipes
+ * a JSON session payload on stdin. This renderer reads the durable presence file
+ * (`.peaks/_runtime/active-skill.json`, with a one-minor-release back-compat
+ * fallback to `.peaks/.active-skill.json`) and prints a single line that
+ * Claude Code paints at the bottom of the terminal. Because it is rendered
+ * by the harness — not emitted as LLM tokens — the signal cannot be forgotten
+ * by the model, cannot be confused with normal output, and survives context
+ * compaction.
+ *
+ * This module is intentionally READ-ONLY. Unlike getSkillPresence in
+ * skill-presence-service.ts, it never deletes or rewrites the presence file:
+ * the statusLine runs on every turn and must have zero side effects.
+ */
+const PRESENCE_FILE = '.peaks/_runtime/active-skill.json';
+const PRESENCE_FILE_LEGACY = '.peaks/.active-skill.json';
+const STALE_THRESHOLD_MS = 24 * 60 * 60 * 1000;
+function resolveCwdFromStdin(stdin) {
+    const fromWorkspace = stdin?.workspace?.current_dir ?? stdin?.workspace?.project_dir;
+    if (typeof fromWorkspace === 'string' && fromWorkspace.length > 0) {
+        return resolve(fromWorkspace);
+    }
+    if (typeof stdin?.cwd === 'string' && stdin.cwd.length > 0) {
+        return resolve(stdin.cwd);
+    }
+    return process.cwd();
+}
+export function parseStatusLineStdin(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (parsed && typeof parsed === 'object') {
+            return parsed;
+        }
+        return null;
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+/**
+ * Read the presence file without any side effects. Returns null when the file is
+ * absent (idle) and a sentinel object for malformed content (invalid-presence).
+ */
+function readPresenceReadOnly(projectRoot) {
+    const presencePath = resolve(projectRoot, PRESENCE_FILE);
+    // Back-compat: prefer the new canonical path; fall back to the legacy
+    // `.peaks/.active-skill.json` for one minor release.
+    const pathToRead = existsSync(presencePath) ? presencePath : resolve(projectRoot, PRESENCE_FILE_LEGACY);
+    if (!existsSync(pathToRead)) {
+        return { presence: null, invalid: false };
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(pathToRead, 'utf8'));
+        if (!parsed || typeof parsed !== 'object') {
+            return { presence: null, invalid: true };
+        }
+        const candidate = parsed;
+        if (typeof candidate.skill !== 'string' || candidate.skill.length === 0) {
+            return { presence: null, invalid: true };
+        }
+        return {
+            presence: {
+                skill: candidate.skill,
+                ...(typeof candidate.mode === 'string' ? { mode: candidate.mode } : {}),
+                ...(typeof candidate.gate === 'string' ? { gate: candidate.gate } : {}),
+                ...(typeof candidate.setAt === 'string' ? { setAt: candidate.setAt } : {}),
+                ...(typeof candidate.claudeSessionId === 'string' ? { claudeSessionId: candidate.claudeSessionId } : {})
+            },
+            invalid: false
+        };
+    }
+    catch {
+        return { presence: null, invalid: true };
+    }
+}
+export function buildStatusLineModel(stdin, nowMs) {
+    const cwd = resolveCwdFromStdin(stdin);
+    const projectRoot = findProjectRoot(cwd);
+    if (projectRoot === null) {
+        return { state: 'idle', projectRoot: null, presence: null, ageMs: null };
+    }
+    const { presence, invalid } = readPresenceReadOnly(projectRoot);
+    if (invalid) {
+        return { state: 'invalid-presence', projectRoot, presence: null, ageMs: null };
+    }
+    if (presence === null) {
+        return { state: 'idle', projectRoot, presence: null, ageMs: null };
+    }
+    // Session binding: when the presence was stamped with a Claude session id and
+    // the live session (from stdin) is a different one, the recorded skill belongs
+    // to a previous session — render idle instead of a stale "active" skill. When
+    // either id is absent (legacy presence, or harness that omits session_id) we
+    // fall back to the time-based behavior below for backward compatibility.
+    const liveSessionId = typeof stdin?.session_id === 'string' && stdin.session_id.length > 0 ? stdin.session_id : null;
+    if (presence.claudeSessionId && liveSessionId && presence.claudeSessionId !== liveSessionId) {
+        return { state: 'idle', projectRoot, presence: null, ageMs: null };
+    }
+    const setAtMs = presence.setAt ? Date.parse(presence.setAt) : Number.NaN;
+    const ageMs = Number.isNaN(setAtMs) ? null : nowMs - setAtMs;
+    const state = ageMs !== null && ageMs > STALE_THRESHOLD_MS ? 'stale' : 'active';
+    return { state, projectRoot, presence, ageMs };
+}

package/dist/services/skills/statusline-settings-service.d.ts

@@ -0,0 +1,59 @@
+import { isInsidePath } from '../ide/shared/safe-path.js';
+import type { IdeId } from '../ide/ide-types.js';
+/**
+ * Installs (and removes) the Peaks statusLine entry in an IDE's settings
+ * file. The settings file location is adapter-driven
+ * (`getAdapter(ide).settings.dirName` + `settingsFileName`) so a future slice
+ * adding a Trae / Cursor / Codex adapter does not need to touch this file.
+ *
+ * Slice #1 only registers claude-code, so the resolved path is still
+ * `<root>/.claude/settings.json` — the same as before the refactor. The
+ * statusLine entry is rendered as `{ type: 'command', command: 'peaks
+ * statusline' }` because that is the shape Claude Code expects; future
+ * adapters may need a different entry shape (e.g. Cursor's `statusBar`
+ * field) and would override this in their adapter.
+ *
+ * Slice #3 refactor (this commit): the service is now per-IDE aware via an
+ * optional `options.ide` parameter. The CLI command is responsible for
+ * resolving the IDE (env → stdin shape → cwd → fallback to 'claude-code')
+ * via `detectIdeFromContext` and passing the result here. When `ide` is
+ * omitted, the service defaults to `'claude-code'` so existing tests and
+ * downstream callers continue to work without modification.
+ *
+ * Writes preserve all other settings keys, reject symlinked targets, and use an
+ * atomic rename so a partial write can never corrupt an existing settings file.
+ */
+export type StatusLineScope = 'project' | 'global';
+export type StatusLineSettingsOptions = {
+    /**
+     * Which IDE's adapter to install for. Defaults to `'claude-code'` for
+     * backward compatibility. The CLI command should resolve this from
+     * `detectIdeFromContext({ env, cwd, parsedStdin })` and pass the result.
+     * Throws if the IDE is not registered in the adapter registry.
+     */
+    readonly ide?: IdeId;
+};
+export type StatusLineSettingsPlan = {
+    scope: StatusLineScope;
+    settingsPath: string;
+    exists: boolean;
+    alreadyInstalled: boolean;
+    conflict: boolean;
+    conflictCommand: string | null;
+    desiredCommand: string;
+};
+export type StatusLineSettingsResult = StatusLineSettingsPlan & {
+    applied: boolean;
+};
+export declare const STATUSLINE_COMMAND = "peaks statusline";
+export { isInsidePath };
+export declare function planStatusLineInstall(scope: StatusLineScope, projectRoot?: string, options?: StatusLineSettingsOptions): StatusLineSettingsPlan;
+export declare function applyStatusLineInstall(scope: StatusLineScope, projectRoot?: string, options?: {
+    force?: boolean;
+    ide?: IdeId;
+}): StatusLineSettingsResult;
+export declare function removeStatusLineInstall(scope: StatusLineScope, projectRoot?: string, options?: StatusLineSettingsOptions): {
+    scope: StatusLineScope;
+    settingsPath: string;
+    removed: boolean;
+};

package/dist/services/skills/statusline-settings-service.js

@@ -0,0 +1,141 @@
+import { closeSync, constants, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { assertSafeSettingsFile, isInsidePath } from '../ide/shared/safe-path.js';
+import { getAdapter } from '../ide/ide-registry.js';
+export const STATUSLINE_COMMAND = 'peaks statusline';
+// Re-export the shared helper so existing consumers that imported
+// `isInsidePath` from this module keep compiling.
+export { isInsidePath };
+function resolveIde(options) {
+    return options?.ide ?? 'claude-code';
+}
+function resolveSettingsRoot(scope, projectRoot) {
+    if (scope === 'global')
+        return resolve(homedir());
+    if (!projectRoot) {
+        throw new Error('Project scope requires a project root');
+    }
+    return resolve(projectRoot);
+}
+/**
+ * Resolve + safety-check the settings path for the given IDE and scope. The
+ * `dirName` and `settingsFileName` come from the registered adapter
+ * (`getAdapter(ide)`) so the hardcoded `.claude/settings.json` is gone —
+ * future adapters swap by changing the registry, not this file.
+ */
+function resolveAndAssertSettingsPath(scope, ide, projectRoot) {
+    const root = resolveSettingsRoot(scope, projectRoot);
+    const adapter = getAdapter(ide);
+    const { settingsPath } = assertSafeSettingsFile(scope, root, adapter.settings.dirName, adapter.settings.settingsFileName);
+    return { root, settingsPath };
+}
+function readSettings(settingsPath) {
+    if (!existsSync(settingsPath))
+        return {};
+    const fd = openSync(settingsPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const raw = readFileSync(fd, 'utf8').trim();
+        if (raw.length === 0)
+            return {};
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('settings.json must contain a JSON object');
+        }
+        return parsed;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function extractExistingCommand(settings) {
+    const statusLine = settings.statusLine;
+    if (statusLine && typeof statusLine === 'object' && !Array.isArray(statusLine)) {
+        const command = statusLine.command;
+        if (typeof command === 'string')
+            return command;
+    }
+    return null;
+}
+function buildPlan(scope, settingsPath, settings, exists) {
+    const existingCommand = extractExistingCommand(settings);
+    const alreadyInstalled = existingCommand !== null && existingCommand.includes(STATUSLINE_COMMAND);
+    const conflict = existingCommand !== null && !alreadyInstalled;
+    return {
+        scope,
+        settingsPath,
+        exists,
+        alreadyInstalled,
+        conflict,
+        conflictCommand: conflict ? existingCommand : null,
+        desiredCommand: STATUSLINE_COMMAND
+    };
+}
+export function planStatusLineInstall(scope, projectRoot, options) {
+    const ide = resolveIde(options);
+    const { settingsPath } = resolveAndAssertSettingsPath(scope, ide, projectRoot);
+    const exists = existsSync(settingsPath);
+    const settings = readSettings(settingsPath);
+    return buildPlan(scope, settingsPath, settings, exists);
+}
+function atomicWriteJson(settingsPath, settings) {
+    const dir = dirname(settingsPath);
+    mkdirSync(dir, { recursive: true });
+    const tempPath = join(dir, `.settings.${randomUUID()}.tmp`);
+    const fd = openSync(tempPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        writeFileSync(fd, `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+    try {
+        renameSync(tempPath, settingsPath);
+    }
+    catch (error) {
+        try {
+            unlinkSync(tempPath);
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // best effort cleanup
+        }
+        throw error;
+    }
+}
+export function applyStatusLineInstall(scope, projectRoot, options = {}) {
+    const ide = resolveIde(options);
+    const { settingsPath } = resolveAndAssertSettingsPath(scope, ide, projectRoot);
+    const exists = existsSync(settingsPath);
+    const settings = readSettings(settingsPath);
+    const plan = buildPlan(scope, settingsPath, settings, exists);
+    if (plan.alreadyInstalled) {
+        return { ...plan, applied: false };
+    }
+    if (plan.conflict && !options.force) {
+        return { ...plan, applied: false };
+    }
+    const entry = { type: 'command', command: STATUSLINE_COMMAND, padding: 0 };
+    const nextSettings = { ...settings, statusLine: entry };
+    atomicWriteJson(settingsPath, nextSettings);
+    return { ...plan, applied: true };
+}
+export function removeStatusLineInstall(scope, projectRoot, options) {
+    const ide = resolveIde(options);
+    const { settingsPath } = resolveAndAssertSettingsPath(scope, ide, projectRoot);
+    if (!existsSync(settingsPath)) {
+        return { scope, settingsPath, removed: false };
+    }
+    const settings = readSettings(settingsPath);
+    const existingCommand = extractExistingCommand(settings);
+    if (existingCommand === null || !existingCommand.includes(STATUSLINE_COMMAND)) {
+        return { scope, settingsPath, removed: false };
+    }
+    const { statusLine: _removed, ...rest } = settings;
+    atomicWriteJson(settingsPath, rest);
+    return { scope, settingsPath, removed: true };
+}
+// Suppress unused-import warning for `isAbsolute` if it becomes unused in
+// future refactors. The pre-refactor file used it in the local isInsidePath;
+// the shared helper owns that logic now.
+void isAbsolute;