devflow-kit 2.3.0 → 2.4.0

package/dist/cli/commands/uninstall.js

@@ -15,8 +15,8 @@ import { removeCaptureHooks } from './capture.js';
 import { removeDreamHook } from './legacy-hooks.js';
 import { removeHudStatusLine } from './hud.js';
 import { removeContextHook } from './context.js';
-import { applyDisableToSettings } from './proxy.js';
-import { readProxyState, DEFAULT_PROXY_PORT } from '../../core/proxy-state.js';
+import { applyProxyTeardownToSettings } from './proxy.js';
+import { readProxyState, proxyJsonExists } from '../../core/proxy-state.js';
 import { hudCacheDir } from '../../core/cache.js';
 import { revertExternalAgents } from '../../core/agent-models.js';
 import { detectShell, getProfilePath } from '../../core/safe-delete.js';
@@ -768,14 +768,16 @@ export async function runCleanupPhase(opts) {
             settingsContent = stripFlags(settingsContent); // also strips viewMode via view-mode registry entry
             settingsContent = stripDevflowTeammateModeFromJson(settingsContent);
             // Remove proxy hooks and ANTHROPIC_BASE_URL env in a single parse-mutate-serialize pass.
-            // REG-1: scope the URL strip to the port Devflow manages — use the pre-captured port
-            // (from opts.managedProxyPorts) because proxy.json is already deleted by
-            // removeDevFlowInstallArtifacts before this phase runs. A user's own localhost
-            // gateway on any other port is left in settings untouched.
+            // D-STRIP-1: an absent entry in managedProxyPorts means proxy.json did not exist
+            // before artifact removal — no evidence Devflow ever wrote the env vars, so
+            // applyProxyTeardownToSettings removes only our hooks and leaves the user's
+            // ANTHROPIC_BASE_URL / CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT alone.
+            // Hook removal is never gated: our hooks must not survive an uninstall.
+            // REG-1: the port-scoped URL strip protects any foreign localhost gateway on a
+            // different port — the managedPort value is from the pre-captured proxy.json port.
             {
-                const managedPort = opts.managedProxyPorts?.get(scope) ?? DEFAULT_PROXY_PORT;
                 const parsedSettings = JSON.parse(settingsContent);
-                applyDisableToSettings(parsedSettings, managedPort);
+                applyProxyTeardownToSettings(parsedSettings, opts.managedProxyPorts?.get(scope));
                 settingsContent = JSON.stringify(parsedSettings, null, 2) + '\n';
             }
             if (settingsContent !== originalContent) {
@@ -977,16 +979,24 @@ export const uninstallCommand = new Command('uninstall')
     // Pre-capture managed proxy ports for each scope BEFORE artifact removal.
     // proxy.json is deleted by removeDevFlowInstallArtifacts (inside runFullPhaseForScope),
     // so reading it after the full phase would always yield DEFAULT_PROXY_PORT. (F6)
+    //
+    // D-STRIP-1: only populate managedProxyPorts when proxy.json exists — evidence that
+    // Devflow has managed the proxy on this machine. runCleanupPhase gates the
+    // applyProxyTeardownToSettings call on the port being present in the map, so when the file
+    // is absent (never managed), no env strip is attempted and a user's own gateway vars
+    // are left untouched.
     const managedProxyPorts = new Map();
     if (!isSelectiveUninstall) {
         for (const scope of scopesToUninstall) {
             try {
                 const paths = await getInstallationPaths(scope);
-                const proxyState = await readProxyState(paths.devflowDir);
-                if (proxyState.ok)
-                    managedProxyPorts.set(scope, proxyState.value.port);
+                if (await proxyJsonExists(paths.devflowDir)) {
+                    const proxyState = await readProxyState(paths.devflowDir);
+                    if (proxyState.ok)
+                        managedProxyPorts.set(scope, proxyState.value.port);
+                }
             }
-            catch { /* non-fatal: if we can't read, we fall back to DEFAULT_PROXY_PORT */ }
+            catch { /* non-fatal */ }
         }
     }
     // Uninstall from each scope

package/dist/core/flags.js

@@ -11,6 +11,17 @@
  * point every caller reaches). applyFlags(settingsJson, FlagsRecord) is the
  * sole API; init.ts works directly with FlagsRecord (no legacy string[] bridge).
  */
+import { isDeepStrictEqual } from 'node:util';
+/**
+ * Type predicate that narrows `ClaudeCodeFlag` to `EnvBooleanFlagDef`.
+ * Narrows `f.onPayload` to `string` so callers writing to the env string-map
+ * avoid an `unknown` hop without an unsafe cast.
+ *
+ * Use in `buildPayload` and `applyFlags` only where the string type is load-bearing.
+ */
+export function isEnvBooleanFlag(f) {
+    return f.kind === 'boolean' && f.target.type === 'env';
+}
 // ─── Registry ─────────────────────────────────────────────────────────────────
 // Phase 0 probe findings: see docs/reference/claude-code-flags-probe.md
 /**
@@ -309,6 +320,24 @@ export const FLAG_REGISTRY = [
         recommended: false,
         defaultValue: false,
     },
+    {
+        // D27: gates Claude Code's AI-attribution injection into git commits and PRs.
+        // When true, writes {"commit":"","pr":""} to settings.json which suppresses attribution.
+        // When false/null (neutral), removes the key ONLY when the current value is the exact
+        // devflow-managed shape (settingDeleteGuard). A custom attribution value (e.g. an org
+        // name) is never deleted — shape guard prevents erasure (D-ATTR-GUARD).
+        id: 'suppress-attribution',
+        label: 'Suppress AI attribution',
+        description: 'Remove AI-attribution labels from git commits and pull requests',
+        hint: 'Suppresses Claude attribution labels in git commits and pull requests',
+        blurb: 'hide AI attribution labels',
+        kind: 'boolean',
+        target: { type: 'setting', key: 'attribution' },
+        onPayload: { commit: '', pr: '' },
+        settingDeleteGuard: { commit: '', pr: '' },
+        recommended: false,
+        defaultValue: false,
+    },
     // ── Valued flags (number/enum/string) ────────────────────────────────────
     {
         // Domain: unset by default; set only when users want a non-default spawn depth.
@@ -837,6 +866,78 @@ export function migrateLegacyFlagsToRecord(enabledIds, knownIds, legacyViewMode)
     return result;
 }
 // ─── Apply / Strip ────────────────────────────────────────────────────────────
+/**
+ * Returns true when `value` equals the managed shape declared by `flag.settingDeleteGuard`.
+ * Returns false when: the flag has no guard, is not a setting-target boolean, or the value
+ * does not deep-equal the guard.
+ *
+ * Single equality oracle for managed-shape comparisons — used by `canDeleteSettingKey`,
+ * `settingHoldsManagedShape`, and the Step 2b adoption fold in `convergeFlagsIntoSettings`.
+ * All three delegate here so there is exactly one `isDeepStrictEqual` call for guard matching.
+ */
+export function settingValueHoldsManagedShape(flag, value) {
+    if (flag.kind !== 'boolean' || flag.target.type !== 'setting')
+        return false;
+    const guard = flag.settingDeleteGuard;
+    if (guard === undefined)
+        return false;
+    return isDeepStrictEqual(value, guard);
+}
+/**
+ * D-ATTR-GUARD single-source predicate (consistency-01 / ADR-024).
+ *
+ * Returns true when the settings.json string contains a value at the flag's
+ * target key that equals the flag's managed shape (`settingDeleteGuard`).
+ *
+ * This is the ONE place that decides "on-disk value equals the managed shape".
+ * All consumers — `resolveExistingAttributionSuppression` (seeding priority),
+ * and the guarded-boolean adoption fold in `convergeFlagsIntoSettings` — delegate
+ * here rather than hand-rolling their own comparison.
+ *
+ * Returns false when:
+ *   - settingsJson is malformed
+ *   - root is not a plain object
+ *   - flagId is not in the registry
+ *   - the flag has no settingDeleteGuard
+ *   - the flag is not a setting-target boolean
+ *   - the on-disk value does not deep-equal the guard
+ */
+export function settingHoldsManagedShape(settingsJson, flagId) {
+    try {
+        const parsed = JSON.parse(settingsJson);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return false;
+        const flag = FLAG_REGISTRY_MAP.get(flagId);
+        if (!flag)
+            return false;
+        const value = parsed[flag.target.key];
+        return settingValueHoldsManagedShape(flag, value);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * D-ATTR-GUARD: returns true when it is safe to delete a flag's target key from
+ * settings. For flags with a settingDeleteGuard the key is only deleted when the
+ * current on-disk value deep-equals the managed shape, preventing erasure of
+ * user-customized values (e.g. an organisation attribution block) on flag
+ * disable or uninstall. Flags without a guard are always safe to delete.
+ *
+ * Delegates to `settingValueHoldsManagedShape` — the single equality oracle for
+ * managed-shape comparisons — so there is exactly one `isDeepStrictEqual` call
+ * across the entire apply/strip pipeline (ADR-024 mechanism 3).
+ *
+ * Single-source invariant: both the disable path (applyFlags neutral branch) and
+ * the uninstall path (stripFlags) collapse to this predicate.
+ */
+function canDeleteSettingKey(flag, settings) {
+    if (flag.kind !== 'boolean')
+        return true;
+    if (flag.settingDeleteGuard === undefined)
+        return true;
+    return settingValueHoldsManagedShape(flag, settings[flag.target.key]);
+}
 /**
  * Return `v` as a `Record<string, unknown>` only when it is a plain object.
  * Returns undefined for arrays, null, or non-objects.
@@ -853,8 +954,17 @@ function asPlainObject(v) {
 /** Compute the value to write to settings.json for an active flag. */
 function buildPayload(flag, value) {
     switch (flag.kind) {
-        case 'boolean':
-            return flag.onPayload;
+        case 'boolean': {
+            // D-PAYLOAD-CLONE: return a structural clone for object payloads so the
+            // FLAG_REGISTRY entry is never aliased into the caller's settings tree.
+            // Primitives (string, boolean) are values and require no clone.
+            // isEnvBooleanFlag narrows onPayload to string for env flags — no clone needed,
+            // and the string type avoids an `unknown` hop into the env string-map.
+            if (isEnvBooleanFlag(flag))
+                return flag.onPayload; // string — no clone needed
+            const p = flag.onPayload;
+            return typeof p === 'object' && p !== null ? structuredClone(p) : p;
+        }
         case 'enum':
             return value;
         case 'number':
@@ -904,7 +1014,8 @@ export function applyFlags(settingsJson, flags) {
                     delete env[flag.target.key];
             }
             else {
-                delete settings[flag.target.key];
+                if (canDeleteSettingKey(flag, settings))
+                    delete settings[flag.target.key];
             }
         }
         else {
@@ -949,7 +1060,8 @@ export function stripFlags(settingsJson) {
                 delete env[flag.target.key];
         }
         else {
-            delete settings[flag.target.key];
+            if (canDeleteSettingKey(flag, settings))
+                delete settings[flag.target.key];
         }
     }
     if (env && Object.keys(env).length === 0) {
@@ -1116,6 +1228,35 @@ export function convergeFlagsIntoSettings(settingsJson, record, opts) {
             folded[flag.id] = coerced;
         }
     }
+    // ── Step 2b: adopt guarded boolean settings before the strip ─────────────
+    // D-ATTR-ADOPT (PF-050 / ADR-024): a delete guard is evidence about the VALUE,
+    // never about the record — a pre-existing on-disk key whose value matches the
+    // managed shape means devflow wrote it, so adopt it into the record now, before
+    // stripFlags can unconditionally remove it on the next line.
+    //
+    // Mirror of the view-mode fold (Step 1): adopt only when:
+    //   (a) the flag has a settingDeleteGuard (guarded boolean only)
+    //   (b) the record does NOT already claim the key — a claimed false or null still
+    //       deletes the managed block (the user intentionally disabled it)
+    //   (c) the pre-strip on-disk value holds the managed shape
+    //
+    // This fold runs before stripFlags so applyFlags rewrites the block from the
+    // now-claimed record and the block survives on BOTH the init and flags paths.
+    for (const flag of FLAG_REGISTRY) {
+        if (flag.kind !== 'boolean')
+            continue;
+        if (flag.target.type !== 'setting')
+            continue;
+        // Skip when the record already claims this flag (claimed false/null deletes the block)
+        const claimed = claimedIn !== null &&
+            Object.prototype.hasOwnProperty.call(claimedIn, flag.id);
+        if (claimed)
+            continue;
+        // Adopt only when the on-disk value matches the managed shape exactly
+        if (settingValueHoldsManagedShape(flag, parsed[flag.target.key])) {
+            folded[flag.id] = true;
+        }
+    }
     // ── Step 3: strip all managed keys, then apply the folded record ──────────
     const stripped = stripFlags(settingsJson);
     const settings = applyFlags(stripped, folded);

package/dist/core/proxy-log.js

@@ -29,8 +29,10 @@ export const PROXY_LOG_TAIL_BYTES = 1_048_576;
  * (e.g. SUBSWITCH_CONFIG for the relay spawn and doctor spawn).
  *
  * applies ADR-003: the prior denylist rationale is gone — the routing runtime
- * reads exactly three env vars (ANTHROPIC_API_KEY, FORCE_COLOR, SUBSWITCH_CONFIG).
- * Verified by whole-dist grep of the 0.2.0 package. An allowlist is the correct
+ * reads exactly four env vars (ANTHROPIC_API_KEY, FORCE_COLOR, NO_COLOR,
+ * SUBSWITCH_CONFIG — NO_COLOR read in dist/tty.js with presence semantics; CI is
+ * read only by the `init` subcommand which devflow never invokes).
+ * Verified by whole-dist grep of the 0.4.0 package. An allowlist is the correct
  * shape: 61 inherited vars → 6.
  *
  * HOME is retained: the runtime's loadConfig resolves ~ paths via homedir().

package/dist/core/proxy-state.js

@@ -88,47 +88,72 @@ export async function writeProxyState(devflowDir, state) {
 // Pure helpers
 // ---------------------------------------------------------------------------
 /**
- * Accepted top-level keys for the subswitch 0.2.0 FileConfigSchema (z.strictObject).
+ * Accepted top-level keys for the subswitch 0.4.0 FileConfigSchema (z.strictObject).
  * Unknown top-level keys cause a hard relay startup error — never emit them.
  *
- * @D-EFR-4 Subswitch 0.2.0 routing config contract:
+ * @D-EFR-4 Subswitch 0.4.0 routing config contract:
  *   FileConfigSchema is a z.strictObject with exactly 5 accepted top-level keys:
  *   port, logLevel, anthropic, providers, limits. Unknown keys cause a hard startup
  *   error — the relay refuses to start. anthropic and limits are themselves
  *   strictObject + prefault({}), so they may be partially specified.
- *
- *   connectTimeoutMs default: subswitch 0.2.0 applies anthropic.connectTimeoutMs
- *   as upstream.setTimeout() at anthropic-passthrough.js:86 — a socket *inactivity*
- *   timeout, not a connect timeout. The 10s default kills any Anthropic request
- *   whose upstream takes >10s to emit the first response byte — routine for long
- *   opus requests (confirmed: 99 spurious 504s clustered at 10004-10098ms while
- *   successful requests ran 25s-99s). Default overridden to 120 000ms; a
- *   user-specified value always wins.
- *
- *   limits.connectTimeoutMs is a registered LEGACY KEY that causes a hard startup
- *   error. Strip it from the limits block when preserving existing config.
  */
 const ROUTING_CONFIG_ALLOWED_TOP_KEYS = new Set([
     'port', 'logLevel', 'anthropic', 'providers', 'limits',
 ]);
-/** Default anthropic.connectTimeoutMs injected when not specified by the user (ms). */
-export const DEFAULT_ANTHROPIC_CONNECT_TIMEOUT_MS = 120_000;
+/**
+ * Sub-keys of a preserved `anthropic` / `limits` block that the pinned relay rejects
+ * outright — each is a registered LEGACY KEY, and a legacy key is a hard startup
+ * error naming its replacement, not a warning. They are stripped when carrying a
+ * user's existing config forward so an upgrade cannot leave the relay unable to boot.
+ *
+ * Every entry was valid under a version devflow previously pinned, which is what makes
+ * it reachable in a real user's file:
+ *   anthropic.streamIdleTimeoutMs — valid in 0.2.0, removed in 0.3.0 (relay no longer
+ *     bounds the stream-idle phase on a connected client).
+ *   limits.connectTimeoutMs       — moved to anthropic.connectTimeoutMs in 0.3.0;
+ *     stripping it loses nothing (relay default governs).
+ *   limits.maxConcurrentRequests  — valid in 0.2.0, removed in 0.3.0 (admission gate
+ *     removed).
+ *   limits.maxBodyBytes           — valid through 0.3.0, renamed to
+ *     limits.maxBufferedBodyBytes in 0.4.0. The old spelling is a registered legacy
+ *     key, so leaving it in place would stop the relay from booting.
+ *   limits.maxUpstreamSockets     — valid in 0.3.0, moved to anthropic.maxUpstreamSockets
+ *     in 0.4.0's providers.* restructure.
+ *   limits.streamIdleTimeoutMs    — valid in 0.3.0, moved to
+ *     providers.codex.streamIdleTimeoutMs in 0.4.0.
+ *   limits.requestTimeoutMs       — valid in 0.3.0, moved to
+ *     providers.codex.requestTimeoutMs in 0.4.0.
+ *   limits.maxSseEventBytes       — valid in 0.3.0, moved to
+ *     providers.codex.maxSseEventBytes in 0.4.0.
+ *
+ * Keys retired before the 0.2.0 baseline are deliberately absent: only keys reachable
+ * in a config written by a previously pinned devflow version belong on this list.
+ */
+const ROUTING_CONFIG_REJECTED_SUBKEYS = {
+    anthropic: ['streamIdleTimeoutMs'],
+    limits: [
+        'connectTimeoutMs',
+        'maxConcurrentRequests',
+        'maxBodyBytes',
+        'maxUpstreamSockets',
+        'streamIdleTimeoutMs',
+        'requestTimeoutMs',
+        'maxSseEventBytes',
+    ],
+};
 /**
  * Build the routing config JSON for ~/.devflow/proxy-routing.json.
  *
  * Authoritatively sets `port`. Preserves any existing valid `anthropic`,
- * `limits`, `logLevel`, and `providers` blocks from `existingContent`,
- * filtering out unknown top-level keys and the legacy `limits.connectTimeoutMs`
- * field (which causes a hard relay startup error in 0.2.0).
- *
- * Injects a default `anthropic.connectTimeoutMs` of 120 000ms when the user
- * has not set one — see @D-EFR-4 for the rationale.
+ * `limits`, `logLevel`, and `providers` blocks from `existingContent`, filtering
+ * out unknown top-level keys and every sub-key in ROUTING_CONFIG_REJECTED_SUBKEYS
+ * (each one a hard relay startup error). No `anthropic` block is injected when
+ * the user has not set one — the relay's own default governs (D-EFR-4).
  *
- * If `existingContent` is missing or malformed, falls back to a clean config
- * with only `port` and `anthropic.connectTimeoutMs`.
+ * If `existingContent` is missing or malformed, falls back to a port-only config.
  *
  * applies ADR-013: pure core-layer function — no I/O.
- * @D-EFR-4: see note above for the strict top-key constraint and timeout rationale.
+ * @D-EFR-4: see note above for the strict top-key constraint.
  */
 export function buildRoutingConfigJson(port, existingContent) {
     // Parse existing config tolerantly; a malformed file falls back to clean defaults.
@@ -154,30 +179,36 @@ export function buildRoutingConfigJson(port, existingContent) {
     if (preserved.logLevel !== undefined) {
         config.logLevel = preserved.logLevel;
     }
-    // Anthropic block: preserve user settings; inject connectTimeoutMs default when absent.
-    // @D-EFR-4: the 10s upstream inactivity timeout kills long opus requests.
-    const existingAnthropic = typeof preserved.anthropic === 'object' &&
+    // Anthropic block: preserve user settings; strip legacy rejected sub-keys.
+    // No default is injected — the relay's own default governs (D-EFR-4).
+    if (typeof preserved.anthropic === 'object' &&
         preserved.anthropic !== null &&
-        !Array.isArray(preserved.anthropic)
-        ? { ...preserved.anthropic }
-        : {};
-    if (!Object.prototype.hasOwnProperty.call(existingAnthropic, 'connectTimeoutMs')) {
-        existingAnthropic.connectTimeoutMs = DEFAULT_ANTHROPIC_CONNECT_TIMEOUT_MS;
+        !Array.isArray(preserved.anthropic)) {
+        const existingAnthropic = { ...preserved.anthropic };
+        for (const key of ROUTING_CONFIG_REJECTED_SUBKEYS.anthropic) {
+            delete existingAnthropic[key];
+        }
+        if (Object.keys(existingAnthropic).length > 0) {
+            config.anthropic = existingAnthropic;
+        }
     }
-    config.anthropic = existingAnthropic;
     // Preserve providers block if present.
     if (preserved.providers !== undefined) {
         config.providers = preserved.providers;
     }
-    // Preserve limits block if present; strip legacy limits.connectTimeoutMs that
-    // causes a hard startup error in 0.2.0 (use anthropic.connectTimeoutMs instead).
+    // Preserve limits block if present, minus the sub-keys the relay hard-errors on
+    // (see ROUTING_CONFIG_REJECTED_SUBKEYS).
     if (preserved.limits !== undefined) {
         if (typeof preserved.limits === 'object' &&
             preserved.limits !== null &&
             !Array.isArray(preserved.limits)) {
             const limitsObj = { ...preserved.limits };
-            delete limitsObj['connectTimeoutMs'];
-            config.limits = limitsObj;
+            for (const key of ROUTING_CONFIG_REJECTED_SUBKEYS.limits) {
+                delete limitsObj[key];
+            }
+            if (Object.keys(limitsObj).length > 0) {
+                config.limits = limitsObj;
+            }
         }
         else {
             config.limits = preserved.limits;
@@ -210,6 +241,29 @@ export function proxyBaseUrl(port) {
 // ---------------------------------------------------------------------------
 // isProxyEnabled — the primary contract other modules consume
 // ---------------------------------------------------------------------------
+/**
+ * Returns true when ~/.devflow/proxy.json exists on disk — i.e. Devflow has
+ * previously managed the proxy on this machine.
+ *
+ * This is the evidence gate used by init and uninstall before stripping
+ * ANTHROPIC_BASE_URL / CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT:
+ * we only strip those vars when we can prove Devflow wrote them.
+ *
+ * D-STRIP-1: gate proxy env stripping on devflow-managed evidence.
+ *   readProxyState() returns Ok(defaultState) on ENOENT — it cannot distinguish
+ *   "file absent" from "file present with DEFAULT_PROXY_PORT". Callers that need
+ *   to differentiate must use proxyJsonExists() rather than checking the result
+ *   of readProxyState().
+ */
+export async function proxyJsonExists(devflowDir) {
+    try {
+        await fs.access(join(devflowDir, 'proxy.json'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Check whether the Devflow proxy is currently enabled.
  * Returns false when the proxy state file is missing, unreadable, or malformed.

package/dist/targets/claude-code/post-install.js

@@ -712,10 +712,95 @@ export async function stripUserSecurityDenyList(settingsPath) {
     await writeFileAtomicExclusive(settingsPath, stripped);
     return { removed };
 }
+/** True for a non-null, non-array object literal. */
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Every `command` string carried by a hook matcher, tolerating foreign shapes.
+ * Returns an empty array for anything that is not `{ hooks: [{ command: string }] }`.
+ */
+function hookCommandsOf(matcher) {
+    if (!isPlainObject(matcher) || !Array.isArray(matcher.hooks))
+        return [];
+    return matcher.hooks
+        .filter(isPlainObject)
+        .map((h) => h.command)
+        .filter((c) => typeof c === 'string');
+}
+/**
+ * Merge Devflow's template hook entries and top-level fields into an existing
+ * parsed settings object. Idempotent by exact command string — a hook that is
+ * already present is skipped. Sets `statusLine` only when the user has no existing
+ * value. Attribution is NOT injected here — managed by the flags pipeline (D27).
+ * Mutates `existing` in place.
+ *
+ * D-SETTINGS-1: merge strategy — never replace; only add devflow entries that are absent.
+ * Returns { changed: true } when any field was added.
+ *
+ * `existing` comes from a hand-editable file, so every branch is shape-guarded:
+ * a `hooks` value (or per-event value) that is not the expected object/array shape
+ * is left untouched rather than overwritten or thrown on (applies PF-023 — validate
+ * at the sink that mutates).
+ *
+ * Exported for testing.
+ */
+export function mergeDevflowSettingsTemplate(existing, template) {
+    let changed = false;
+    // Merge hook entries — idempotent by exact command string
+    const tmplHooks = isPlainObject(template.hooks) ? template.hooks : {};
+    const existingHooksRaw = existing.hooks;
+    if (existingHooksRaw === undefined || isPlainObject(existingHooksRaw)) {
+        const existingHooks = existingHooksRaw ?? {};
+        let hooksChanged = false;
+        for (const [event, matchers] of Object.entries(tmplHooks)) {
+            if (!Array.isArray(matchers))
+                continue;
+            for (const matcher of matchers) {
+                const cmd = hookCommandsOf(matcher)[0];
+                if (!cmd)
+                    continue;
+                const current = existingHooks[event];
+                if (current !== undefined && !Array.isArray(current))
+                    break; // foreign shape — leave the event alone
+                const eventArr = current ?? [];
+                if (eventArr.some((m) => hookCommandsOf(m).includes(cmd)))
+                    continue;
+                eventArr.push(matcher);
+                existingHooks[event] = eventArr;
+                hooksChanged = true;
+            }
+        }
+        // Attach only when something was actually added — never introduce an empty
+        // `hooks` key into a settings.json that had none.
+        if (hooksChanged) {
+            existing.hooks = existingHooks;
+            changed = true;
+        }
+    }
+    // Set statusLine only if the user has none
+    if (existing.statusLine === undefined && template.statusLine !== undefined) {
+        existing.statusLine = template.statusLine;
+        changed = true;
+    }
+    // attribution: owned exclusively by the flags pipeline (applyFlags/stripFlags, D27) — a second writer here would race it.
+    return { changed };
+}
 /**
  * Install or update settings.json with Devflow configuration.
- * Prompts interactively in TTY mode when settings already exist.
- * In non-TTY mode, skips override (safe default).
+ *
+ * Strategy (D-SETTINGS-1: merge, never overwrite wholesale):
+ * - Fresh file: write the template directly.
+ * - Existing file: MERGE devflow hook entries and fields into the parsed object.
+ *   Idempotent by exact command string — existing hooks are never duplicated or removed.
+ *   Preserves every user key (env, permissions, apiKeyHelper, model, etc.) untouched.
+ * - Parse failure: warn and skip; file left byte-identical (never clobber a broken file).
+ *
+ * The merge is additive only, so it runs without a confirmation prompt: init is called
+ * from inside an active spinner (a prompt would render on top of it), and declining
+ * could not protect the file anyway — init's own settings pass rewrites the hook set
+ * unconditionally right afterwards. A prompt whose answer changes nothing is worse
+ * than no prompt.
  *
  * The deny list is handled by init's dedicated security step
  * (applyUserSecurityDenyList / installManagedSettings) after installSettings completes.
@@ -741,38 +826,30 @@ export async function installSettings(claudeDir, rootDir, devflowDir, verbose) {
             }
             return;
         }
-        // Settings exist — check if they already have hooks
-        let hasHooks = false;
+        // Settings exist — parse and merge (never overwrite wholesale)
+        let existingParsed;
         try {
-            const existing = JSON.parse(await fs.readFile(settingsPath, 'utf-8'));
-            hasHooks = !!existing.hooks;
+            existingParsed = JSON.parse(await fs.readFile(settingsPath, 'utf-8'));
         }
-        catch { /* parse error = treat as no hooks */ }
-        if (hasHooks) {
-            // Settings already configured with hooks — nothing to do
+        catch {
+            // Parse failure — warn and skip; file left byte-identical (D-SETTINGS-1)
+            if (verbose) {
+                p.log.warn('settings.json could not be parsed — Devflow hooks not added. ' +
+                    'Fix the JSON manually and re-run devflow init.');
+            }
             return;
         }
-        // Settings exist without hooks — prompt in TTY, warn in non-TTY
-        if (process.stdin.isTTY) {
-            const confirmed = await p.confirm({
-                message: 'settings.json exists without hooks (Working Memory needs hooks). Override?',
-                initialValue: true,
-            });
-            if (p.isCancel(confirmed)) {
-                p.cancel('Installation cancelled.');
-                process.exit(0);
-            }
-            if (confirmed) {
-                await fs.writeFile(settingsPath, settingsContent, 'utf-8');
-                p.log.success('Settings overridden');
-            }
-            else {
-                p.log.info('Keeping existing settings');
-            }
+        const templateParsed = JSON.parse(settingsContent);
+        // Merge template into existing (mutates existingParsed in place).
+        // If nothing needs to be added the write is skipped entirely.
+        const { changed } = mergeDevflowSettingsTemplate(existingParsed, templateParsed);
+        if (!changed) {
+            // Already fully configured — nothing to do
+            return;
         }
-        else {
-            p.log.warn('Settings exist without hooks. Working Memory requires hooks.');
-            p.log.info('Re-run interactively to configure, or manually add hooks to settings.json');
+        await writeFileAtomicExclusive(settingsPath, JSON.stringify(existingParsed, null, 2) + '\n');
+        if (verbose) {
+            p.log.success('Settings updated with Devflow hooks and HUD');
         }
     }
     catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devflow-kit",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "A meta-harness for Claude Code — turns a single coding agent into an engineering team: orchestration, parallel review, persistent memory, self-learning, and graph workflows",
   "type": "module",
   "bin": {
@@ -63,7 +63,7 @@
     "@clack/prompts": "^0.9.1",
     "commander": "^12.0.0",
     "picocolors": "^1.1.1",
-    "subswitch": "0.2.0"
+    "subswitch": "0.4.0"
   },
   "devDependencies": {
     "@mdscript/mds": "0.2.0",