devflow-kit 2.2.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/commands/resolve.md

@@ -50,7 +50,7 @@ In multi-worktree mode, spawn all pre-flight agents **in a single message** (par
 
 **If BLOCKED:** In single-worktree mode, stop and report the blocker to user. If no reviews found, suggest `/code-review` or `/bug-analysis` first. In multi-worktree mode, report the failure but continue with other worktrees.
 
-**Extract from response:** `branch`, `branch_slug`, `pr_number`, `review_count`, `diff_files` per worktree.
+**Extract from response:** `branch`, `base_branch`, `branch_slug`, `pr_number`, `review_count`, `diff_files` per worktree.
 
 **Fetch PR body** (after extracting `pr_number`):
 ```bash
@@ -186,7 +186,7 @@ Issues are extracted from `{TARGET_DIR}` only — never cross-reference reviews
 ### Phase 1b: Fetch External Review Threads (Compliance-gated)
 
 **Produces:** THREAD_MAP
-**Requires:** PR_INFO, COMPLIANCE_SKILL_INSTALLED
+**Requires:** BRANCH_INFO, COMPLIANCE_SKILL_INSTALLED
 
 Skip this phase if `COMPLIANCE_SKILL_INSTALLED` is false.
 
@@ -205,7 +205,7 @@ Parse `THREAD_MAP` from Git agent output. If Git agent returns `TRACEABILITY: DE
 ### Phase 2: Global Triage
 
 **Produces:** TRIAGE_RESULTS
-**Requires:** ISSUES, DIFF_FILES, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, PR_DESCRIPTION, BRANCH_INFO
+**Requires:** ISSUES, DIFF_FILES, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, PR_DESCRIPTION
 
 Spawn a single global Triage agent for ALL issues:
 
@@ -217,7 +217,7 @@ WORKTREE_PATH: {worktree_path}  (omit if cwd)
 DECISIONS_CONTEXT: {decisions_context}
 FEATURE_KNOWLEDGE: {feature_knowledge}
 PR_DESCRIPTION: <pr-description>{pr_description}</pr-description>
-Triage every issue using the blast-radius disposition matrix. Assign exactly one verdict per issue.
+Triage every issue: collapse duplicates first, then apply the blast-radius disposition matrix to each group's primary. Assign exactly one verdict per issue.
 Follow devflow:apply-decisions to Read full ADR/PF bodies on demand.
 Follow devflow:apply-feature-knowledge for FEATURE_KNOWLEDGE."
 ```
@@ -229,11 +229,12 @@ Wait for Triage agent to complete before proceeding. Parse verdict ledger from T
 - **BY_DESIGN**: Intentional code (with ADR or code doc citation)
 - **FIX_SEPARATE**: Valid but out of blast-radius scope (must become manage-debt ticket)
 - **TECH_DEBT**: Architectural overhaul only — LAST RESORT
+- **DUPLICATE**: Collapsed duplicate issue — carries `duplicate_of: <primary-id>` referencing the non-DUPLICATE primary; inherits the primary's outcome
 
 Collect all decisions citations (ADR-NNN / PF-NNN) from Triage agent Reasoning columns.
 
 **Triage agent completeness assertion (avoids PF-002):** Verify the parsed ledger against ISSUES before proceeding:
-1. Every issue `id` from ISSUES must appear in exactly one verdict bucket — none may vanish, none may appear in multiple buckets.
+1. Every issue `id` from ISSUES must appear in exactly one verdict bucket — none may vanish, none may appear in multiple buckets. DUPLICATE is a valid bucket; a valid DUPLICATE entry must name its `duplicate_of` primary (the `Duplicate Of` column of the ledger's DUPLICATE table) and that primary must be a non-DUPLICATE issue id. A missing `duplicate_of` or one that chains to another DUPLICATE is a **Triage agent failure** (retry-then-abort as below).
 2. If the Triage agent output is empty, contains a skill re-entrancy guard string (e.g., contains `already running`), or is missing any issue IDs from ISSUES: treat as a **Triage agent failure**:
    - Retry the Triage agent once with the same inputs.
    - If the retry also fails the completeness check: abort with a clear error message listing the missing issue IDs and failure reason — never proceed with dropped issues.
@@ -247,7 +248,7 @@ Collect all decisions citations (ADR-NNN / PF-NNN) from Triage agent Reasoning c
 
 If FIX_NOW list is empty: skip to Phase 5 — write full summary (Phase 5), run manage-debt (Phase 9) if FIX_SEPARATE/TECH_DEBT exist, run thread resolution + resolution comment (Phase 9b), run merge readiness (Phase 9c), display results (Phase 10).
 
-Otherwise, batch FIX_NOW issues for Code agent execution:
+Otherwise, batch FIX_NOW issues for Code agent execution. **DUPLICATE issues are never dispatched** — they inherit the primary's outcome:
 - **Same-file issues** → one batch (one Code agent per file, sequential for same-file pairs)
 - **Distinct-file issues** → parallel Code agents
 - **Max 5 issues per batch** — chunk large sets
@@ -255,7 +256,7 @@ Otherwise, batch FIX_NOW issues for Code agent execution:
 ### Phase 4: Fix (Code agent × N)
 
 **Produces:** CODE_AGENT_RESULTS
-**Requires:** BATCHES, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, BRANCH_INFO
+**Requires:** BATCHES, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE
 
 For each batch, spawn Code agent with `OPERATION: issue-fix` and `PUSH: false`:
 
@@ -284,12 +285,14 @@ Collect from each Code agent:
 ### Phase 5: Write resolution-summary.md
 
 **Produces:** RESOLUTION_FILE (early write for compaction safety)
-**Requires:** TRIAGE_RESULTS, CODE_AGENT_RESULTS
+**Requires:** TRIAGE_RESULTS, CODE_AGENT_RESULTS, TARGET_DIR, BRANCH_INFO
 
 **Immediately write `resolution-summary.md`** to `{TARGET_DIR}` using the Write tool. Do this now — not in Phase 9 — while results are fresh in context. This ensures the record is persisted even if later phases (Simplify, Verification Gate, CI gate, Tech Debt) trigger context compaction.
 
 Set `Tracked` for FIX_SEPARATE and TECH_DEBT items to `(pending)` — to be backfilled after Phase 9 manage-debt.
 
+DUPLICATE issues are listed **only** in `## Duplicates` — never in `## Fixed Issues`, `## False Positives`, `## By Design`, `## Fix Separately`, `## Deferred to Tech Debt`, `## Escalations`, or `## Blocked`. A duplicate of a FALSE_POSITIVE primary therefore leaves only the primary in the `False Positive` row and the `## False Positives` section; the same holds for every other outcome the duplicate inherits.
+
 Use the template from the Output Artifact section below.
 
 ### Phase 6: Simplify
@@ -382,7 +385,7 @@ Otherwise, for each worktree with fixes:
 
 **IMPORTANT**: Run sequentially across all worktrees (not in parallel) to avoid GitHub API conflicts.
 
-If any issues are FIX_SEPARATE or TECH_DEBT, spawn Git agent:
+If any issues are FIX_SEPARATE or TECH_DEBT, spawn Git agent. **DUPLICATE issues never create their own debt tickets** — a duplicate of a deferred primary is covered by the primary's ticket:
 
 ```
 Agent(subagent_type="Git"):
@@ -407,6 +410,7 @@ Skip this step if `COMPLIANCE_SKILL_INSTALLED` is false or THREAD_MAP is empty.
 
 Prepare THREAD_MAP with verdicts from triage/code agent results:
 - For each `ext-{N}`: match to an issue verdict (FIXED, FALSE_POSITIVE, BY_DESIGN, ESCALATED) by `file:line` correlation
+- If the matched issue has verdict DUPLICATE, use the **primary's** verdict and verification status for the reply — do not expose DUPLICATE to the thread author (avoids PF-024; caller-side mapping — git.md contracts unchanged)
 - Include `commit_sha` from Code agent results for FIXED verdicts
 - Unmatched threads: ESCALATED (human review)
 
@@ -447,7 +451,7 @@ Update `## Third-Party Threads` section in resolution-summary.md with thread res
 ### Phase 9c: Merge Readiness (Compliance-gated, Report-only)
 
 **Produces:** MERGE_READINESS_REPORT
-**Requires:** PR_INFO, COMPLIANCE_SKILL_INSTALLED
+**Requires:** BRANCH_INFO, COMPLIANCE_SKILL_INSTALLED
 
 Skip this phase if `COMPLIANCE_SKILL_INSTALLED` is false.
 
@@ -466,7 +470,7 @@ If Git agent returns `TRACEABILITY: DEGRADED`: warn, proceed to Phase 10.
 
 ### Phase 10: Report
 
-**Requires:** TARGET_DIR
+**Requires:** BRANCH_INFO, TARGET_DIR
 
 The resolution summary was already written to `{TARGET_DIR}/resolution-summary.md` in Phase 5 (updated by Phase 7 and Phase 9). Display results to the user:
 
@@ -486,6 +490,7 @@ The resolution summary was already written to `{TARGET_DIR}/resolution-summary.m
 | Deferred | {n} |
 | Blocked | {n} |
 | Escalated | {n} |
+| Duplicates Collapsed | {n} |
 
 ### Verification
 Final gate: {PASS | FAILED after N attempts}
@@ -578,9 +583,9 @@ After writing, commit the two files to the current worktree branch yourself by r
 │  └─ Git agent (fetch-review-threads) → THREAD_MAP
 │
 ├─ Phase 2: Global Triage [Triage agent, opus, single agent]
-│  └─ ALL issues → verdict ledger by disposition
+│  └─ ALL issues → verdict ledger by disposition (incl. DUPLICATE with duplicate_of)
 │
-├─ Phase 3: Batch FIX_NOW issues (skip if empty)
+├─ Phase 3: Batch FIX_NOW issues (skip if empty; DUPLICATE issues never dispatched)
 │  └─ same-file sequential, distinct-file parallel, max 5/batch
 │
 ├─ Phase 4: Fix [Code agent × N, OPERATION: issue-fix, PUSH: false]
@@ -623,6 +628,8 @@ After writing, commit the two files to the current worktree branch yourself by r
 | Worktree pre-flight fails | Report failure, continue with other worktrees |
 | Empty FIX_NOW list | Skip Phases 3-4/6-8; still write full summary + run manage-debt if FIX_SEPARATE/TECH_DEBT exist |
 | ESCALATED security issues | Surfaced in ## Escalations + display callout; never routed to manage-debt |
+| DUPLICATE verdict without duplicate_of, or chained to another DUPLICATE | Treated as Triage failure — same retry-then-abort as a vanished id |
+| DUPLICATE issues in THREAD_MAP | Map ext-{N} to primary's verdict/verification status for thread reply |
 | Verification Gate FAILED after 2 attempts | Recorded as FAILED in ## Verification + blocking callout; CI gate skipped; proceed to Phase 9 (manage-debt) then Phase 10 (display) |
 | gh/GitHub absent | manage-debt fails gracefully; Tracked stays "(pending)" + noted — recorded, not dropped |
 | COMPLIANCE_SKILL_INSTALLED false | Phases 1b, 9b-step-1, and 9c are skipped; post-resolution-summary (Phase 9b step 2) still runs if a PR is known |
@@ -651,7 +658,7 @@ Written in Phase 5 (Collect Results) to `{TARGET_DIR}/resolution-summary.md`:
 ```markdown
 # Resolution Summary
 
-**Branch**: {branch} -> {base}
+**Branch**: {branch} -> {base_branch}
 **Date**: {timestamp}
 **Review**: {TARGET_DIR}
 **Command**: /resolve
@@ -673,8 +680,9 @@ Written in Phase 5 (Collect Results) to `{TARGET_DIR}/resolution-summary.md`:
 | Deferred | {n} |
 | Blocked | {n} |
 | Escalated | {n} |
+| Duplicates Collapsed | {n} |
 
-_(Note: `Deferred` = `## Fix Separately` count + `## Deferred to Tech Debt` count combined — the two sections are distinct by scope, but the Statistics row aggregates both for the convergence parser.)_
+_(Note: `Deferred` = `## Fix Separately` count + `## Deferred to Tech Debt` count combined — the two sections are distinct by scope, but the Statistics row aggregates both for the convergence parser. `Total Issues` counts every triaged issue including collapsed duplicates; every row **between** `Total Issues` and `Duplicates Collapsed` counts UNIQUE (non-DUPLICATE) issues only, so `Total Issues` equals the sum of the rows below it. Excluding duplicates from `Fixed`, `False Positive`, and `Deferred` de-skews the fp\_ratio convergence formula in code-review without any parser change.)_
 
 ## Verification
 | Command | Result |
@@ -720,6 +728,11 @@ Final gate: PASS | FAILED after {n} attempts
 |-------|-----------|---------|
 | {description} | {file}:{line} | {why} |
 
+## Duplicates
+| Issue | Duplicate Of | File:Line |
+|-------|-------------|-----------|
+| {description} | {primary-id} | {file}:{line} |
+
 ## Third-Party Threads
 | Thread | File:Line | Verdict | Status |
 |--------|-----------|---------|--------|
@@ -728,4 +741,4 @@ Final gate: PASS | FAILED after {n} attempts
 
 _(Omit `## Third-Party Threads` if `COMPLIANCE_SKILL_INSTALLED` is false or no external threads were found.)_
 
-**Statistics mapping (parser contract)**: the `Deferred` row = FIX_SEPARATE + TECH_DEBT (both deferral dispositions combined); By Design and Escalated are counted separately and excluded from `Deferred`. The `/code-review` convergence parser reads the `Deferred`, `Fixed`, and `False Positive` Statistics rows plus the `## Fixed Issues` / `## False Positives` headings — keep those labels byte-stable.
+**Statistics mapping (parser contract)**: the `Deferred` row = FIX_SEPARATE + TECH_DEBT (both deferral dispositions combined); By Design and Escalated are counted separately and excluded from `Deferred`. The `Duplicates Collapsed` row is additive — the `/code-review` convergence parser reads only `Deferred`, `Fixed`, and `False Positive` rows plus `## Fixed Issues` / `## False Positives` headings — keep those labels byte-stable. All rows that the parser reads count UNIQUE (non-DUPLICATE) issues only, so collapsed duplicates do not inflate fp\_ratio.

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.