devflow-kit 1.8.3 → 2.0.0

package/dist/core/external-models.js

@@ -0,0 +1,76 @@
+/**
+ * External model dormancy predicate and Claude model alias set.
+ *
+ * Dormancy asks "does this model name need the proxy?" — answerable from the
+ * complement (the static Claude passthrough set) without any discovery I/O.
+ * This keeps the safety property correct even when discovery fails.
+ *
+ * Live model discovery (discoverExternalModels / getExternalModelsCached) lives
+ * in src/core/model-discovery.ts. The TUI picker and --set validation use the
+ * ExternalModelCatalog returned by those functions.
+ *
+ * applies ADR-013: pure core-layer module, no Claude Code adapter concerns.
+ *
+ * NOTE: the internal routing runtime package name must NEVER appear in
+ * user-visible strings, CLI output, or error messages. User-facing vocabulary:
+ * "external model routing (GPT models via your OpenAI/Codex subscription)" /
+ * "Devflow proxy".
+ */
+// ---------------------------------------------------------------------------
+// Claude model alias set — exported for TUI cycle builders and tests.
+// Lives in external-models (leaf module, no project imports) so callers in
+// agents-view/state.ts can import without cycles.
+// ---------------------------------------------------------------------------
+/**
+ * Claude model short-alias identifiers.
+ * A mapping entry with one of these model values applies unconditionally —
+ * it is NOT an external model and is NOT subject to proxy dormancy.
+ *
+ * Includes 'fable': devflow's Claude set is intentionally a SUPERSET of the
+ * routing runtime's own Anthropic passthrough regex (which does not match
+ * 'fable'). The runtime's fallbackProvider is 'anthropic', so 'fable' routes
+ * correctly. Excluding 'fable' here would misclassify it as external and
+ * silently revert it to the shipped default when the proxy is off.
+ */
+export const CLAUDE_MODEL_ALIASES = ['haiku', 'sonnet', 'opus', 'fable'];
+const CLAUDE_EXACT = new Set([...CLAUDE_MODEL_ALIASES, 'inherit']);
+/**
+ * Returns true when `model` names a Claude-native model — an alias
+ * (haiku/sonnet/opus/fable/inherit) or a full claude- prefixed identifier.
+ *
+ * Used as the COMPLEMENT predicate for dormancy: a model is external if and
+ * only if it is not a Claude model name (and not 'default').
+ *
+ * Pure function, no I/O.
+ */
+export function isClaudeModelName(model) {
+    return CLAUDE_EXACT.has(model) || model.startsWith('claude-');
+}
+// ---------------------------------------------------------------------------
+// Dormancy predicate
+// ---------------------------------------------------------------------------
+/**
+ * Returns true when `model` names a non-Claude model that requires the
+ * Devflow proxy AND the proxy is currently disabled — i.e., the entry is
+ * DORMANT and the shipped default model should be used instead.
+ *
+ * Classification is by the COMPLEMENT: a model is dormant-when-off iff it is
+ * NOT a Claude model name (and not 'default' or undefined). This makes dormancy
+ * independent of runtime discovery — a discovery failure cannot degrade the
+ * safety property by returning an empty external set.
+ *
+ * Single source of truth for dormancy — do NOT inline this predicate at call
+ * sites. (anti-pattern, KNOWLEDGE.md § Anti-Patterns — "Duplicating the dormancy predicate")
+ *
+ * Pure function, no I/O. Lives in external-models (leaf module, no project
+ * imports) so callers in agents-view/state.ts can import without cycles.
+ *
+ * @param model - The configured model string, or undefined (no mapping entry).
+ * @param proxyEnabled - Whether the Devflow proxy is currently active.
+ */
+export function isDormantExternalModel(model, proxyEnabled) {
+    if (model === undefined || proxyEnabled)
+        return false;
+    return model !== 'default' && !isClaudeModelName(model);
+}
+//# sourceMappingURL=external-models.js.map

package/dist/core/feature-config.js

@@ -0,0 +1,125 @@
+import * as path from 'path';
+import { promises as fs } from 'fs';
+import { getFeatureConfigPath } from './project-paths.js';
+export const DEFAULT_CONFIG = {
+    memory: true,
+    learning: true,
+    knowledge: true,
+    reviewPublication: 'auto',
+};
+export function getConfigPath(projectRoot) {
+    return getFeatureConfigPath(projectRoot);
+}
+/**
+ * Parse and narrow an unknown JSON value into a FeatureConfig, merging onto
+ * DEFAULT_CONFIG. Pure function — no I/O, no side effects.
+ *
+ * Coalesces legacy `decisions` key into `learning` when both are present:
+ * `decisions` wins (legacy-decisions-wins semantics; intentionally opposite to
+ * manifest.ts's new-key-wins self-heal — migration-compat requires the old key
+ * to take precedence so old configs with `decisions: false` are not silently
+ * re-enabled by a newer `learning: true` key).
+ * Silently ignores `autoCommit` — old configs may still contain it.
+ *
+ * Returns null when `parsed` is not a plain object (caller falls through to
+ * the next candidate path).
+ */
+function coerceConfig(parsed) {
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return null;
+    const p = parsed;
+    // Coalesce decisions (legacy key) → learning. decisions wins when both present.
+    let learning = DEFAULT_CONFIG.learning;
+    if (typeof p.learning === 'boolean')
+        learning = p.learning;
+    if (typeof p.decisions === 'boolean')
+        learning = p.decisions; // decisions wins
+    // Coerce reviewPublication: any invalid or absent value → 'auto' (self-heal, ADR-014 idiom).
+    const rp = p.reviewPublication;
+    const reviewPublication = rp === 'auto' || rp === 'full' || rp === 'off' ? rp : 'auto';
+    return {
+        memory: typeof p.memory === 'boolean' ? p.memory : DEFAULT_CONFIG.memory,
+        learning,
+        knowledge: typeof p.knowledge === 'boolean' ? p.knowledge : DEFAULT_CONFIG.knowledge,
+        reviewPublication,
+    };
+}
+/**
+ * Read the feature config for a project root.
+ * Returns DEFAULT_CONFIG when the file is missing or unreadable.
+ * Applies ADR-001: .devflow/config.json is the sole source of truth;
+ * `devflow init` writes it directly on first install. An absent file falls
+ * through to DEFAULT_CONFIG (all features enabled by default).
+ */
+export async function readConfig(projectRoot) {
+    const configPath = getFeatureConfigPath(projectRoot);
+    try {
+        const config = coerceConfig(JSON.parse(await fs.readFile(configPath, 'utf-8')));
+        if (config !== null)
+            return config;
+        return { ...DEFAULT_CONFIG };
+    }
+    catch {
+        return { ...DEFAULT_CONFIG };
+    }
+}
+/**
+ * Write the feature config for a project root.
+ * Creates the .devflow/ directory if missing.
+ * Uses an atomic temp+rename pattern to prevent partial reads under concurrent writes.
+ */
+export async function writeConfig(projectRoot, config) {
+    const configPath = getFeatureConfigPath(projectRoot);
+    await fs.mkdir(path.join(projectRoot, '.devflow'), { recursive: true });
+    const tmpPath = configPath + '.tmp.' + process.pid;
+    await fs.writeFile(tmpPath, JSON.stringify(config, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
+    await fs.rename(tmpPath, configPath);
+}
+/**
+ * Toggle a single feature in the feature config.
+ * Reads current config, applies the change, and writes back.
+ *
+ * D1: Non-atomic read-modify-write. Concurrent invocations of `updateFeature`
+ * could lose each other's writes. Acceptable here because: (a) devflow CLI
+ * commands are single-threaded user-initiated actions, and (b) the window is
+ * milliseconds on a local filesystem with no concurrent writers in normal use.
+ * If concurrent safety is ever required, replace with an atomic file-swap or
+ * a lock file.
+ */
+export async function updateFeature(projectRoot, feature, enabled) {
+    const config = await readConfig(projectRoot);
+    await writeConfig(projectRoot, { ...config, [feature]: enabled });
+}
+/**
+ * Check whether a specific feature is enabled for the given project root.
+ */
+export async function isFeatureEnabled(projectRoot, feature) {
+    const config = await readConfig(projectRoot);
+    return config[feature];
+}
+/**
+ * Read the feature config for a project root, returning null when the file
+ * is absent or malformed.
+ *
+ * Unlike readConfig (which falls back to DEFAULT_CONFIG on any error),
+ * readConfigIfPresent distinguishes "not configured yet" (null) from
+ * "configured with specific values" (FeatureConfig).  The distinction
+ * matters for init-seed resolution: a present config overrides the
+ * manifest for memory/learning/knowledge even when the manifest is absent.
+ *
+ * Applies ADR-001: .devflow/config.json is the source of truth; null means
+ * the config file does not exist or is unreadable — not that all features
+ * are disabled.
+ */
+export async function readConfigIfPresent(projectRoot) {
+    const configPath = getFeatureConfigPath(projectRoot);
+    try {
+        const text = await fs.readFile(configPath, 'utf-8');
+        return coerceConfig(JSON.parse(text)); // null when JSON is not a plain object
+    }
+    catch {
+        // ENOENT (absent) or SyntaxError (malformed) — treat as not present
+        return null;
+    }
+}
+//# sourceMappingURL=feature-config.js.map

package/dist/core/flags.js

@@ -0,0 +1,309 @@
+/**
+ * Claude Code flag registry.
+ *
+ * Typed, extensible mechanism for managing Claude Code feature flags.
+ * Pure functions: applyFlags, stripFlags, getDefaultFlags — no I/O.
+ */
+export const FLAG_REGISTRY = [
+    // === Recommended (default ON) ===
+    {
+        id: 'tui',
+        label: 'Fullscreen terminal UI',
+        description: 'Flicker-free fullscreen rendering',
+        hint: 'Modern fullscreen interface',
+        target: { type: 'setting', key: 'tui', value: 'fullscreen' },
+        defaultEnabled: true,
+    },
+    {
+        id: 'tool-search',
+        label: 'Deferred tool loading',
+        description: 'Load tool schemas on demand instead of all at startup',
+        hint: 'Faster startup',
+        target: { type: 'env', key: 'ENABLE_TOOL_SEARCH', value: 'true' },
+        defaultEnabled: true,
+    },
+    {
+        id: 'lsp',
+        label: 'LSP support',
+        description: 'Enable Language Server Protocol integration',
+        hint: 'Code intelligence from your editor',
+        target: { type: 'env', key: 'ENABLE_LSP_TOOL', value: 'true' },
+        defaultEnabled: true,
+    },
+    {
+        id: 'prompt-caching-1h',
+        label: 'Extended prompt cache',
+        description: 'Extend prompt cache TTL from 5min to 1h',
+        hint: 'Cheaper long sessions',
+        target: { type: 'env', key: 'ENABLE_PROMPT_CACHING_1H', value: 'true' },
+        defaultEnabled: true,
+    },
+    {
+        id: 'show-turn-duration',
+        label: 'Show turn duration',
+        description: 'Display timing info after each turn',
+        hint: 'See how long each response takes',
+        target: { type: 'setting', key: 'showTurnDuration', value: true },
+        defaultEnabled: true,
+    },
+    {
+        id: 'clear-context-on-plan',
+        label: 'Clear context on plan accept',
+        description: 'Clear context window when accepting a plan',
+        hint: 'Clean slate after planning',
+        target: { type: 'setting', key: 'showClearContextOnPlanAccept', value: true },
+        defaultEnabled: true,
+    },
+    {
+        id: 'disable-bundled-skills',
+        label: 'Disable bundled skills',
+        description: "Remove Claude Code's built-in skills and workflows (devflow provides its own)",
+        hint: 'Cleaner skill list',
+        target: { type: 'setting', key: 'disableBundledSkills', value: true },
+        defaultEnabled: true,
+    },
+    {
+        id: 'pin-sonnet-4-6',
+        label: 'Pin Sonnet to 4.6',
+        description: 'Pin the default Sonnet model to claude-sonnet-4-6',
+        hint: 'Stable, deterministic Sonnet version',
+        target: { type: 'env', key: 'ANTHROPIC_DEFAULT_SONNET_MODEL', value: 'claude-sonnet-4-6' },
+        defaultEnabled: true,
+    },
+    // === Optional (default OFF) — skip these if you're unsure ===
+    {
+        id: 'brief',
+        label: 'Brief output mode',
+        description: 'Reduce verbosity of Claude Code output',
+        hint: 'Shorter responses',
+        target: { type: 'env', key: 'CLAUDE_CODE_BRIEF', value: 'true' },
+        defaultEnabled: false,
+    },
+    {
+        id: 'thinking-summaries',
+        label: 'Thinking summaries',
+        description: 'Show thinking summaries during reasoning',
+        hint: 'See reasoning previews',
+        target: { type: 'setting', key: 'showThinkingSummaries', value: true },
+        defaultEnabled: false,
+    },
+    {
+        id: 'subprocess-env-scrub',
+        label: 'Subprocess env scrub',
+        description: 'Strip cloud credentials from subprocesses',
+        hint: 'Security: strip cloud creds from subprocesses',
+        target: { type: 'env', key: 'CLAUDE_CODE_SUBPROCESS_ENV_SCRUB', value: '1' },
+        defaultEnabled: false,
+    },
+    {
+        id: 'disable-nonessential-traffic',
+        label: 'Disable non-essential traffic',
+        description: 'Suppress usage metrics telemetry',
+        hint: 'No telemetry',
+        target: { type: 'env', key: 'CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC', value: 'true' },
+        defaultEnabled: false,
+    },
+    {
+        id: 'forked-subagents',
+        label: 'Forked subagents',
+        description: 'Better subagent perf on external builds',
+        hint: 'Faster parallel agents (experimental)',
+        target: { type: 'env', key: 'CLAUDE_CODE_FORK_SUBAGENT', value: '1' },
+        defaultEnabled: false,
+    },
+    {
+        id: 'disable-adaptive-thinking',
+        label: 'Disable adaptive thinking',
+        description: 'Disable adaptive reasoning on Opus/Sonnet 4.6',
+        hint: 'Fixed thinking budget',
+        target: { type: 'env', key: 'CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING', value: 'true' },
+        defaultEnabled: false,
+    },
+    {
+        id: 'always-thinking',
+        label: 'Always enable thinking',
+        description: 'Enable extended thinking by default',
+        hint: 'Thinking on every turn',
+        target: { type: 'setting', key: 'alwaysThinkingEnabled', value: true },
+        defaultEnabled: false,
+    },
+    {
+        id: 'disable-git-instructions',
+        label: 'Disable git instructions',
+        description: 'Remove git workflow instructions from system prompt',
+        hint: 'Smaller system prompt',
+        target: { type: 'env', key: 'CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS', value: 'true' },
+        defaultEnabled: false,
+    },
+    // NOTE: DISABLE_COMPACT and DISABLE_AUTOUPDATER intentionally omit the CLAUDE_CODE_ prefix —
+    // these names are defined by upstream Claude Code and must match exactly.
+    {
+        id: 'disable-compact',
+        label: 'Disable auto-compaction',
+        description: 'Disable automatic context compaction',
+        hint: 'Keep full context (uses more tokens)',
+        target: { type: 'env', key: 'DISABLE_COMPACT', value: 'true' },
+        defaultEnabled: false,
+    },
+    {
+        id: 'disable-1m-context',
+        label: 'Disable 1M context window',
+        description: 'Use standard context window instead of extended 1M',
+        hint: 'Use smaller context window',
+        target: { type: 'env', key: 'CLAUDE_CODE_DISABLE_1M_CONTEXT', value: 'true' },
+        defaultEnabled: false,
+    },
+    {
+        id: 'disable-autoupdater',
+        label: 'Disable auto-updater',
+        description: 'Prevent automatic update checks',
+        hint: 'No automatic updates',
+        target: { type: 'env', key: 'DISABLE_AUTOUPDATER', value: 'true' },
+        defaultEnabled: false,
+    },
+    {
+        id: 'agent-teams',
+        label: 'Agent Teams (experimental)',
+        description: 'Enable Claude Code experimental Agent Teams',
+        hint: 'Peer agents / teammate mode — experimental',
+        target: { type: 'env', key: 'CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS', value: '1' },
+        defaultEnabled: false,
+        // Note: the legacy `teammateMode:"auto"` settings key is stripped by
+        // src/core/teammate-mode-cleanup.ts during uninstall (stripDevflowTeammateModeFromJson).
+        // The env var above is the only surface managed by FLAG_REGISTRY for this flag.
+    },
+];
+/**
+ * Return IDs of all flags that are enabled by default.
+ */
+export function getDefaultFlags() {
+    return FLAG_REGISTRY.filter(f => f.defaultEnabled).map(f => f.id);
+}
+/**
+ * Apply enabled flags to a settings JSON string.
+ * Sets env vars for env-type flags and top-level keys for setting-type flags.
+ * Ignores unknown flag IDs (forward-compatible with old manifests).
+ */
+export function applyFlags(settingsJson, flagIds) {
+    const settings = JSON.parse(settingsJson);
+    const flagMap = new Map(FLAG_REGISTRY.map(f => [f.id, f]));
+    for (const id of flagIds) {
+        const flag = flagMap.get(id);
+        if (!flag)
+            continue;
+        if (flag.target.type === 'env') {
+            settings.env ??= {};
+            settings.env[flag.target.key] = flag.target.value;
+        }
+        else {
+            settings[flag.target.key] = flag.target.value;
+        }
+    }
+    return JSON.stringify(settings, null, 2) + '\n';
+}
+/**
+ * Strip all flag-managed keys from a settings JSON string.
+ * Removes env vars and top-level settings controlled by the flag registry.
+ * Cleans up empty env object when last entry is removed.
+ */
+export function stripFlags(settingsJson) {
+    const settings = JSON.parse(settingsJson);
+    const env = settings.env;
+    for (const flag of FLAG_REGISTRY) {
+        if (flag.target.type === 'env') {
+            if (env) {
+                delete env[flag.target.key];
+            }
+        }
+        else {
+            delete settings[flag.target.key];
+        }
+    }
+    if (env && Object.keys(env).length === 0) {
+        delete settings.env;
+    }
+    return JSON.stringify(settings, null, 2) + '\n';
+}
+const VIEW_MODE_KEY = 'viewMode';
+/** All valid view mode values. Used for validation at manifest read boundaries. */
+export const VIEW_MODES = ['default', 'verbose', 'focus'];
+/**
+ * Apply a view mode to a settings JSON string.
+ * 'default' removes the viewMode key (Claude Code default behaviour);
+ * 'verbose' and 'focus' set the key explicitly.
+ */
+export function applyViewMode(settingsJson, mode) {
+    const settings = JSON.parse(settingsJson);
+    if (mode === 'default') {
+        delete settings[VIEW_MODE_KEY];
+    }
+    else {
+        settings[VIEW_MODE_KEY] = mode;
+    }
+    return JSON.stringify(settings, null, 2) + '\n';
+}
+/**
+ * Strip the viewMode key from a settings JSON string.
+ * Used during uninstall / flag strip to restore Claude Code defaults.
+ */
+export function stripViewMode(settingsJson) {
+    const settings = JSON.parse(settingsJson);
+    delete settings[VIEW_MODE_KEY];
+    return JSON.stringify(settings, null, 2) + '\n';
+}
+/**
+ * Extract the non-default view mode from a settings JSON string.
+ *
+ * Returns the persisted ViewMode when it is a recognised non-default value
+ * ('focus' or 'verbose'), so callers can chain with ?? to fall through to
+ * a manifest value or the 'default' literal:
+ *
+ *   viewMode = resolveExistingViewMode(snapshot) ?? manifest?.features.viewMode ?? 'default'
+ *
+ * Returns undefined when:
+ *   - JSON is malformed
+ *   - the viewMode key is absent
+ *   - viewMode is 'default' (no meaningful override to preserve)
+ *   - viewMode is an unrecognised string
+ */
+export function resolveExistingViewMode(settingsJson) {
+    try {
+        const parsed = JSON.parse(settingsJson);
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            const existing = parsed[VIEW_MODE_KEY];
+            if (typeof existing === 'string' &&
+                VIEW_MODES.includes(existing) &&
+                existing !== 'default') {
+                return existing;
+            }
+        }
+    }
+    catch { /* malformed settings.json — treat as no opinion */ }
+    return undefined;
+}
+/**
+ * Resolve the final view mode to write, combining an existing settings value,
+ * an init-prompt-selected value, and whether the selection was explicit (via
+ * CLI flag) or implicit (prompt default / recommended path).
+ *
+ * @param current  - Existing viewMode from settings.json (resolveExistingViewMode).
+ *                   undefined means no opinion in the current settings.
+ * @param selected - What the init prompt (or recommended path) would use.
+ * @param explicit - true when the user made an explicit interactive selection in
+ *                   the Advanced init prompt, or when --reset was passed (which
+ *                   forces viewMode back to 'default' and sets explicit=true so
+ *                   that 'default' wins over any externally-set value).
+ *
+ * Rules:
+ *   1. explicit ⇒ selected wins (user intent is unambiguous, even 'default')
+ *   2. non-default current ⇒ current wins (preserve externally-set mode, e.g. /focus)
+ *   3. else ⇒ selected
+ */
+export function resolveFinalViewMode(current, selected, explicit) {
+    if (explicit)
+        return selected;
+    if (current !== undefined && current !== 'default')
+        return current;
+    return selected;
+}
+//# sourceMappingURL=flags.js.map

package/dist/core/fs-atomic.js

@@ -0,0 +1,74 @@
+import { promises as fs } from 'fs';
+/**
+ * @file fs-atomic.ts
+ *
+ * D34: Canonical atomic-write helper for the TypeScript CLI surface.
+ *
+ * Call sites: used by the CLI's exclusive-write call sites (migrations, init, post-install,
+ * uninstall, security, ambient, memory, HUD, observation I/O).
+ * The CJS counterpart (`writeExclusive` in `src/assets/scripts/hooks/json-helper.cjs` and
+ * `src/assets/scripts/hooks/decisions-usage-scan.cjs`) intentionally remains a separate
+ * implementation — same semantics, different module system. Any change to the
+ * retry logic here MUST be mirrored in both CJS files.
+ */
+/**
+ * Atomically write `filePath` by writing to a sibling `.tmp` then renaming.
+ *
+ * Uses `{ flag: 'wx' }` (O_EXCL | O_WRONLY) so the kernel rejects the open if
+ * a file — or a symlink an attacker placed there between our decision to write
+ * and the actual open() call (TOCTOU) — already exists at the `.tmp` path.
+ *
+ * On EEXIST (stale `.tmp` from a prior crash, or adversarially-placed file) we
+ * unlink and retry once. The unlink is wrapped in its own try/catch so that a
+ * concurrent writer that already removed the stale file between our EEXIST
+ * check and our unlink does not cause an unexpected throw — this matches the
+ * race-tolerant pattern in the CJS `writeExclusive` implementations.
+ *
+ * The final `fs.rename` is a single POSIX atomic operation — readers either see
+ * the old content or the new content, never a partial write.
+ *
+ * @param filePath - Absolute path to the target file.
+ * @param data - UTF-8 encoded content to write.
+ */
+export async function writeFileAtomicExclusive(filePath, data) {
+    // PID-scope the tmp name so concurrent writers from different processes
+    // (e.g., two Claude Code sessions) never collide on the same .tmp path.
+    // mirrors proxy-log.ts rotation at src/core/proxy-log.ts which PID-scopes
+    // for the same reason.  avoids PF-011.
+    const tmp = `${filePath}.tmp.${process.pid}`;
+    try {
+        await fs.writeFile(tmp, data, { encoding: 'utf-8', flag: 'wx' });
+    }
+    catch (err) {
+        if (err.code !== 'EEXIST')
+            throw err;
+        // Stale or adversarially-placed .tmp — unlink and retry once.
+        // Race-tolerant: if a concurrent writer already removed the file,
+        // the unlinkSync in the CJS counterpart silently ignores ENOENT here too.
+        try {
+            await fs.unlink(tmp);
+        }
+        catch { /* race — already removed */ }
+        await fs.writeFile(tmp, data, { encoding: 'utf-8', flag: 'wx' });
+    }
+    // Preserve the target's permission mode across the atomic replace.
+    // A user who hardened the target (e.g. settings.json → 0600 to protect
+    // ANTHROPIC_API_KEY) must not have it silently widened to umask default
+    // (~0644) on every proxy enable/disable or post-install rewrite.
+    //
+    // Non-fatal path: if stat fails (ENOENT → fresh file, or any other I/O
+    // error), skip chmod and keep the umask default — the write must still
+    // complete correctly (avoids PF-009 failure-isolation principle).
+    try {
+        const { mode } = await fs.stat(filePath);
+        // mode includes file-type bits; mask to permission bits only for chmod.
+        await fs.chmod(tmp, mode & 0o777);
+    }
+    catch {
+        // Fresh write (ENOENT) or stat/chmod failure — use umask default.
+        // Intentionally non-fatal: mode preservation is best-effort; the write
+        // itself must never be corrupted by a chmod error.
+    }
+    await fs.rename(tmp, filePath);
+}
+//# sourceMappingURL=fs-atomic.js.map

package/dist/core/git.js

@@ -0,0 +1,61 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import * as path from 'path';
+const execAsync = promisify(exec);
+/**
+ * Canonical trunk branch names used by the HUD to determine whether a branch
+ * should compare against origin/<branch> rather than the repo's default branch.
+ *
+ * Keep in exact sync with the Protected Branches (Canonical List) section in
+ * src/assets/skills/worktree-support/SKILL.md. Both lists must be updated together.
+ */
+export const TRUNK_BRANCHES = [
+    'main', 'master', 'develop', 'integration', 'trunk', 'staging', 'production',
+];
+export const TRUNK_BRANCH_PREFIXES = ['release/'];
+/**
+ * Returns true when `branch` is a canonical trunk branch — i.e., one of the
+ * TRUNK_BRANCHES literals or a branch whose name starts with a TRUNK_BRANCH_PREFIXES
+ * prefix (e.g. `release/1.2`).
+ */
+export function isTrunkBranch(branch) {
+    if (TRUNK_BRANCHES.includes(branch))
+        return true;
+    return TRUNK_BRANCH_PREFIXES.some(p => branch.startsWith(p));
+}
+/**
+ * Get git repository root directory (async, non-blocking)
+ * Returns null if not in a git repository
+ *
+ * Security: Validates output to prevent command injection
+ * - Rejects paths with injection characters (newlines, semicolons, shell operators)
+ * - Ensures path is absolute
+ * - Resolves path canonically
+ *
+ * @param cwd - Directory to resolve the git root from. Defaults to process.cwd().
+ *   Callers that already carry an explicit working directory must pass it, otherwise
+ *   they resolve half their paths from the injected dir and half from the process dir.
+ */
+export async function getGitRoot(cwd = process.cwd()) {
+    try {
+        const { stdout } = await execAsync('git rev-parse --show-toplevel', {
+            cwd,
+            encoding: 'utf-8'
+        });
+        const gitRootRaw = stdout.trim();
+        // Validate git root path (security: prevent injection)
+        if (!gitRootRaw || gitRootRaw.includes('\n') || gitRootRaw.includes(';') || gitRootRaw.includes('&&')) {
+            return null;
+        }
+        // Validate it's an absolute path
+        const gitRoot = path.resolve(gitRootRaw);
+        if (!path.isAbsolute(gitRoot)) {
+            return null;
+        }
+        return gitRoot;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=git.js.map