detach --purge then attach silently downgrades claude to base-URL mode, with no warning on any surface

[philcunliffe]

hyp detach claude --purge followed by hyp attach claude silently lands in base-URL mode, and nothing on any surface says so.

Found on a coworker's real macOS install while diagnosing a separate two-password-dialog report. Reproduces by reading on master at a23a3ea (the tagged, unpublished v1.23.0).

Repro

On a machine with proxy_mode: true in the effective config and Claude attached in proxy mode:

hyp detach claude --purge
hyp attach claude

Expected: attach re-establishes proxy mode, minting and trusting a CA (one password dialog).

Actual: attach reports success and writes a base-URL marker. No CA is minted, no keychain dialog appears, NODE_EXTRA_CA_CERTS/HTTPS_PROXY are never written, and Remote Control inbound stays broken. No warning is printed and no diagnostic appears in hyp status.

Why

Three correct-in-isolation behaviours compose into a dead end.

1. Attach decides its mode from the CA file, not from config.

hypaware-core/plugins-workspace/claude/src/index.js:200

const ca = await readLocalCaInfo({ stateRoot: defaultStateRoot(ctx.env) })
const result = await attach({
  ...,
  ...(ca ? { mode: MODE_PROXY, caCertPath: ca.certPath } : {}),
})

This is deliberate (LLP 0232 #proxy-attach-preflight): "the mode it writes is the mode the gateway is serving, not the one someone asked for." Attach never mints a CA; only the daemon does, in prepareInterception (hypaware-core/plugins-workspace/ai-gateway/src/source.js:479), which runs at gateway source launch or reload.

2. --purge deletes the CA but leaves proxy_mode on and does not restart the daemon.

purgeProxyTrustResidue (src/core/commands/clients.js:1586) removes the CA files, the keychain trust, and the launchd env. Nothing in the detach path writes proxy_mode, so the config still claims proxy mode while no CA exists. The running daemon holds its already-loaded CA in memory and has no reason to relaunch the source, so nothing re-mints.

3. The migration prompt that would repair this returns early.

src/core/commands/clients.js:842

if (effectiveGateway?.config?.proxy_mode === true) return

The offer to switch an install to proxy mode is skipped precisely because the config says proxy mode is already on. The config is right about intent and wrong about reality, and this is the one place that could notice.

Why it is silent

• Attach's platform-warning branch is if (ca && darwin) {...} else if (ca) {...}. There is no else for the missing-CA case, so a downgrade produces no warning (.../claude/src/index.js:225).
• collectProxyTrust bails on if (!ca) return null (src/core/daemon/status.js:1210), so the entire proxy trust: block disappears from hyp status rather than reporting a problem.

The result is an install that reports healthy while capture has quietly changed shape and Remote Control inbound is dead.

Recovery (works today, for the runbook)

hyp daemon restart
ls ~/.hyp/hypaware/tls/ca-cert.pem   # must exist before attaching
hyp attach claude

The restart re-mints the CA because prepareInterception sees proxy_mode: true. Attach then takes the proxy branch. The base-URL to proxy switch itself is sound: releaseUnmanagedKeys (.../claude/src/settings.js:479, LLP 0232 #mode-migration) restores or removes the keys the old mode owned, so no manual settings editing is needed and no detach is required first.

Re-running --purge before re-attaching deletes the freshly minted CA and returns to the same state.

Options

Not proposing a fix, since which surface owns the truth is a design call:

1. Make --purge leave a consistent world. Either restart the gateway source as part of the purge so the CA is re-minted, or clear proxy_mode so config and disk agree.
2. Let attach report the mismatch. Attach cannot see config by design, but its CLI caller can: at clients.js:842, distinguish "proxy_mode true and a CA exists" from "proxy_mode true and no CA", and on the latter say so and name the repair instead of returning.
3. Make hyp status name the state. proxy_mode: true with no CA on disk is currently invisible; today collectProxyTrust returns null for it. The inverse case (proxy mode off, CA present) is already warned about as aigw.proxy_mode_stale_ca in source.js:441, so this is the missing half of an existing pair.

(3) is the smallest honest change and is independently useful; (1) is what stops users reaching the state at all.

Related

• Follow-up: F1 and F2 from #790, plus proxy-trust status findings deferred from PR #792 #793 F3 residue already names "narrowing the re-mint triggers so config churn does not rotate the CA", the neighbouring lifecycle gap.
• PR hyp status names the CA's permitted hosts, uninstall clears every duplicate root (#793) #800 fixes duplicate keychain roots (Follow-up: F1 and F2 from #790, plus proxy-trust status findings deferred from PR #792 #793 F2), which is what led here: a purge-and-retry cycle is the workaround people reach for when the trust dialog misbehaves.
• LLP 0232 (#proxy-attach-preflight, #mode-migration), LLP 0238 (#ca-survives-detach).

[philcunliffe]

Decision: implement options 2 and 3. Option 1 is declined.

Recording the choice, plus a finding that makes option 2 smaller and more concrete than the issue body suggests.

The repair path already exists and already works

maybeOfferProxyModeMigration is called at src/core/commands/clients.js:308, before the endpoint is resolved and before attach() runs. Its own comment says why:

Before the endpoint is resolved, because an accepted migration restarts the daemon and may move the bound port.

So the full cycle already completes in a single invocation on the normal path: prompt, accept, config write, daemon restart (which mints the CA in prepareInterception), then attach() runs and finds the fresh certificate and installs the keychain trust. LLP 0244's own summary describes this as "sets the key in the local config, restarts the daemon, waits for the CA, and proceeds into the normal proxy" attach.

This is not a missing capability. It is an existing repair that declines to fire in the one state that needs it.

Option 2 (chosen): let that path run when the CA is missing

Two changes.

a. Split the early return at src/core/commands/clients.js:842.

if (effectiveGateway?.config?.proxy_mode === true) return

proxy_mode: true currently means "nothing to do". It actually covers two states:

Config	CA on disk	Meaning
proxy_mode: true	present	genuinely in proxy mode, nothing to do
proxy_mode: true	missing	config and reality disagree, repair needed

b. The 'already' outcome must stop being a silent no-op.

enableGatewayProxyMode returns outcome: 'already' when proxy_mode is on, and the caller returns silently at clients.js:947. Removing (a) alone therefore changes nothing. When the CA is absent, that branch needs to restart the daemon so the gateway re-mints, letting the attach below take the proxy branch as it already does.

Why this over option 1: the repair is a daemon restart, which is purely local. It needs no config write, so it behaves identically on fleet-managed and solo hosts. It also fixes the state however the user reached it, not only via --purge.

Caveat to handle: if no daemon service is installed, a restart cannot help. The migration flow already has the right message shape for that case (clients.js:942, "no daemon service is installed, so start one ... and re-run"). Reuse it rather than inventing new wording.

Option 3 (chosen): let hyp status name the state

collectProxyTrust bails at src/core/daemon/status.js:1210 with if (!ca) return null, so proxy_mode: true with no certificate renders as nothing at all rather than as a fault. The whole proxy trust: block disappears and the install reports healthy.

This is the missing half of a pair that already exists: the inverse state (proxy mode off, CA present) already warns as aigw.proxy_mode_stale_ca in hypaware-core/plugins-workspace/ai-gateway/src/source.js:441. Follow that precedent for shape and wording.

Purely additive and read-only. It fixes nothing on its own; it stops the machine lying about its health.

Option 1 (declined)

• 1a, re-mint during purge. Contradicts what the command promises. --purge is "a zero-residue exit for a user who wants it without uninstalling"; minting a fresh CA on the way out puts the residue straight back.
• 1b, clear proxy_mode during purge. Cannot work where it is most needed. On a fleet-managed install proxy_mode is owned by the central layer, which LLP 0031 treats as sacrosanct, so a local purge cannot clear it. The existing central branch at clients.js:878 already says as much ("enable proxy_mode in the fleet config to switch it"). It also widens purge's scope from "CA, keychain, launchd env" to editing the user's config.

Design obligation before coding

LLP 0244 is Accepted, and it settles this gate explicitly. From maybeOfferProxyModeMigration's own JSDoc:

The offer is keyed on the config, not the CA.

Option 2 adds a CA-derived trigger to that gate, so it changes what 0244 settled. Per the repo's LLP rules, an Accepted doc is a record and must not be edited: mint a new decision LLP that extends it, add an Extended-by: forward-ref to LLP 0244, and @ref the new number at both touched seams. Do not renumber or rewrite 0244.

Pick the number by the repo's own procedure (fetch origin/master and scan all branches; numbers get claimed on branches with no open PR).

Verification expected

• Traditional tests for both seams: the split gate at clients.js:842 and the 'already' restart, plus the new hyp status line on both the text and --json surfaces.
• hypaware-core/smoke/flows/client_attach_idempotent.js already asserts on attach wording and is the natural place for a regression covering the purge-then-attach sequence.
• The darwin-only half (keychain trust, the real dialog) cannot be proven on Linux. Anything touching it wants a docs/ACCEPTANCE.md pass on a real Mac, per the same caveat carried on Follow-up: F1 and F2 from #790, plus proxy-trust status findings deferred from PR #792 #793 and PR hyp status names the CA's permitted hosts, uninstall clears every duplicate root (#793) #800.