dsh-zen-remote 2.3.10 → 2.4.0

package/src/cli/commands-status.ts

@@ -0,0 +1,296 @@
+/**
+ * CLI-3: the `status` command — one identity read (ping) plus whatever the
+ * role actually answers, rendered either as pretty JSON (`--json`) or as
+ * bilingual terminal lines. `--debug` is its own branch: fetch the plugin
+ * process's redacted diagnostic report over IPC and write it to a file
+ * (explicit path or a `zen-remote-debug-<role>-<yyyymmdd-hhmm>.json` in the
+ * working directory).
+ *
+ * Per SPEC the IPC channel only carries structured data — every terminal
+ * string is rendered here through the translator. The per-server line
+ * renderer is shared with `commands-client.ts` (`client list` prints the
+ * same rows), so the two surfaces cannot drift.
+ */
+
+import { writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { ADMIN_STATUS_ROUTE, ADMIN_SHARES_ROUTE } from '../admin-routes.js'
+import { WIZARD_STATUS_ROUTE } from '../wizard/routes.js'
+import { CLIENT_STATUS_ROUTE } from '../client-routes.js'
+import type { CliIpcRequestResult } from './ipc-client.js'
+import type { CliPingResponse } from './ipc-client.js'
+import type { CliTranslator } from './i18n.js'
+import type { CliExecutionContext } from './context.js'
+
+/** One pool `servers` row (client/status), defensively typed — the command
+ * layer renders whatever shape arrived, it never trusts it. */
+export type ServerRow = Record<string, unknown>
+
+/**
+ * Fetch one JSON object over IPC; every failure mode (transport error,
+ * error status, non-object body) is `null` — a broken surface means "no
+ * information" for a status view, never a failed command.
+ */
+export async function fetchBody(run: () => Promise<CliIpcRequestResult>): Promise<ServerRow | null> {
+  try {
+    const result = await run()
+    if (result.status < 200 || result.status >= 300) return null
+    return plainOf(result.body)
+  } catch {
+    return null
+  }
+}
+
+/** One plain JSON object, or null. */
+export function plainOf(value: unknown): ServerRow | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as ServerRow)
+    : null
+}
+
+function stringOf(value: unknown): string {
+  return typeof value === 'string' ? value : ''
+}
+
+function arrayOf(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : []
+}
+
+// ===========================================================================
+// Shared row rendering (status + client list)
+// ===========================================================================
+
+/** The connection-state label: the three common states translated, the rest
+ * (revoked / incompatible / unpaired) each with their own word. */
+export function stateLabelOf(t: CliTranslator, value: unknown): string {
+  switch (value) {
+    case 'online': return t('status.online')
+    case 'connecting': return t('status.connecting')
+    case 'offline': return t('status.offline')
+    case 'revoked': return t('status.state.revoked')
+    case 'incompatible': return t('status.state.incompatible')
+    case 'unpaired': return t('status.unpaired')
+    default: return stringOf(value) === '' ? t('status.offline') : String(value)
+  }
+}
+
+/** The fingerprint-compat half of the compat/bridge column. */
+export function compatLabelOf(t: CliTranslator, value: unknown): string {
+  const compat = plainOf(value)
+  if (compat === null) return t('status.client.compatUnavailable')
+  const different = arrayOf(compat.different).length
+  if (different > 0) return t('status.client.compatDiff', { count: different })
+  if (arrayOf(compat.unavailable).length > 0) return t('status.client.compatUnavailable')
+  return t('status.client.compatOk')
+}
+
+/** The bridged-plugin half: how many of the row's plugins are bridged. */
+export function bridgeLabelOf(t: CliTranslator, value: unknown): string {
+  const plugins = arrayOf(value)
+  const bridged = plugins.filter((entry) => plainOf(entry)?.bridged === true).length
+  return t('status.client.bridgeCount', { count: bridged })
+}
+
+/** One paired-host row, the exact shape both surfaces print:
+ * `[entryId] displayName  serverUrl  state  compat/bridge`. */
+export function serverLineText(t: CliTranslator, row: ServerRow): string {
+  const name = stringOf(row.displayName) !== '' ? stringOf(row.displayName) : stringOf(row.serverName)
+  return `[${stringOf(row.entryId)}] ${name}  ${stringOf(row.serverUrl)}  ${stateLabelOf(t, row.state)}  ${compatLabelOf(t, row.compat)} · ${bridgeLabelOf(t, row.pluginBridge)}`
+}
+
+// ===========================================================================
+// The status command
+// ===========================================================================
+
+function defaultDebugPath(role: string, now: Date, cwd: string): string {
+  const pad = (value: number): string => String(value).padStart(2, '0')
+  const stamp = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}`
+  return join(cwd, `zen-remote-debug-${role}-${stamp}.json`)
+}
+
+/** The `--debug` branch: fetch the redacted report and land it in a file.
+ * With `--json` the answer also prints as `{ ok, path, report }`; the
+ * bilingual completion line prints either way. */
+async function debugReportFlow(ctx: CliExecutionContext, ping: CliPingResponse): Promise<number> {
+  const { t, ipc, args } = ctx
+  const out = ctx.stdout
+  let report: unknown
+  try {
+    report = await ipc.getDebugReport()
+  } catch (error) {
+    out.write(`${t('status.debugFailed', { error: error instanceof Error ? error.message : String(error) })}\n`)
+    return 1
+  }
+  // The route answers HTTP error statuses as JSON envelopes ({ ok: false,
+  // error }) — a 503 no-handler or a 404 must never land in a file dressed
+  // up as a report (CLI-3-fix). Only a real report shape proceeds to disk.
+  const reportRecord = plainOf(report)
+  if (reportRecord === null || reportRecord.ok === false || !('_meta' in reportRecord)) {
+    const error = plainOf(reportRecord?.error)
+    const detail = typeof error?.code === 'string'
+      ? error.code
+      : reportRecord === null ? 'not an object' : 'missing _meta'
+    out.write(`${t('status.debugFailed', { error: detail })}\n`)
+    return 1
+  }
+  const outPath = args.options.debugPath ?? defaultDebugPath(ping.role, ctx.now?.() ?? new Date(), ctx.cwd ?? process.cwd())
+  try {
+    writeFileSync(outPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8')
+  } catch (error) {
+    out.write(`${t('status.debugWriteFailed', { error: error instanceof Error ? error.message : String(error) })}\n`)
+    return 1
+  }
+  if (args.options.json) {
+    out.write(`${JSON.stringify({ ok: true, path: outPath, report }, null, 2)}\n`)
+  }
+  out.write(`${t('status.debugWritten', { path: outPath })}\n`)
+  return 0
+}
+
+/** The `host` JSON section: sanitized summary of admin/status + wizard/status
+ * + the share count. */
+function hostJsonSection(admin: ServerRow | null, wizard: ServerRow | null, shares: ServerRow | null): ServerRow {
+  const gateway = admin === null ? null : plainOf(admin.gateway)
+  const reachable = admin?.gatewayReachable === true
+  const port = typeof gateway?.port === 'number'
+    ? gateway.port
+    : typeof wizard?.gatewayActualPort === 'number' ? wizard.gatewayActualPort : null
+  const devices = gateway === null ? [] : arrayOf(gateway.devices)
+  const deviceList = devices
+    .map((device) => plainOf(device))
+    .filter((device): device is ServerRow => device !== null)
+    .map((device) => ({ name: stringOf(device.name), role: stringOf(device.role) }))
+  return {
+    gateway: { reachable, port },
+    ingress: {
+      mode: stringOf(wizard?.mode) === '' ? 'off' : stringOf(wizard?.mode),
+      publicUrl: stringOf(wizard?.publicUrl),
+      caddyRunning: wizard?.caddyRunning === true,
+      cloudflaredRunning: wizard?.cloudflaredRunning === true,
+    },
+    devices: { count: deviceList.length, list: deviceList },
+    sharedSessions: arrayOf(shares?.shares).length,
+  }
+}
+
+/** The terminal host section. Every read is defensive: a surface that failed
+ * to answer simply prints nothing instead of a broken line. */
+function renderHostSection(t: CliTranslator, admin: ServerRow | null, wizard: ServerRow | null, shares: ServerRow | null): string[] {
+  const lines: string[] = [t('status.host.title')]
+  const gateway = admin === null ? null : plainOf(admin.gateway)
+  if (admin?.gatewayReachable === true && gateway !== null) {
+    const port = typeof gateway.port === 'number' ? gateway.port : wizard?.gatewayActualPort
+    lines.push(`  ${typeof port === 'number' ? t('status.host.gatewayUp', { port }) : t('status.host.gatewayUpNoPort')}`)
+  } else {
+    lines.push(`  ${t('status.host.gatewayDown')}`)
+  }
+  const mode = stringOf(wizard?.mode) === '' ? 'off' : stringOf(wizard?.mode)
+  lines.push(`  ${t('status.host.ingress', { mode })}`)
+  const publicUrl = stringOf(wizard?.publicUrl)
+  if (publicUrl !== '') lines.push(`  ${t('status.host.publicUrl', { publicUrl })}`)
+  if (mode === 'caddy') {
+    lines.push(`  ${t('status.host.processCaddy', { state: wizard?.caddyRunning === true ? t('status.process.running') : t('status.process.stopped') })}`)
+  }
+  if (mode === 'cloudflared') {
+    lines.push(`  ${t('status.host.processTunnel', { state: wizard?.cloudflaredRunning === true ? t('status.process.running') : t('status.process.stopped') })}`)
+  }
+  const devices = gateway === null ? [] : arrayOf(gateway.devices)
+  lines.push(`  ${t('status.host.devices', { count: devices.length })}`)
+  for (const device of devices) {
+    const record = plainOf(device)
+    if (record === null) continue
+    const name = stringOf(record.name)
+    if (name === '') continue
+    lines.push(t('status.host.deviceLine', { name, deviceRole: stringOf(record.role) }))
+  }
+  lines.push(`  ${t('status.host.sharedSessions', { count: arrayOf(shares?.shares).length })}`)
+  return lines
+}
+
+/** The terminal client section: the count line, the limit warning at 8/8,
+ * one row per paired host, and the last error of a troubled row. */
+function renderClientSection(t: CliTranslator, client: ServerRow): string[] {
+  const lines: string[] = [t('status.client.title')]
+  const servers = arrayOf(client.servers)
+    .map((row) => plainOf(row))
+    .filter((row): row is ServerRow => row !== null)
+  const max = typeof client.maxServers === 'number' ? client.maxServers : 8
+  lines.push(`  ${t('status.client.pairedCount', { count: servers.length, max })}`)
+  if (servers.length >= max) lines.push(`  ${t('client.limitReached')}`)
+  for (const row of servers) {
+    lines.push(`  ${serverLineText(t, row)}`)
+    const lastError = stringOf(row.lastError)
+    if (lastError !== '') lines.push(`      ${t('status.client.lastError', { error: lastError })}`)
+  }
+  return lines
+}
+
+/** The `--json` body: identity always, the sections the role answers. */
+function statusJsonBody(
+  ping: CliPingResponse,
+  admin: ServerRow | null,
+  wizard: ServerRow | null,
+  shares: ServerRow | null,
+  client: ServerRow | null,
+): ServerRow {
+  const body: ServerRow = {
+    experimental: true,
+    role: ping.role,
+    pluginVersion: ping.pluginVersion,
+    pid: ping.pid,
+    serverName: ping.serverName,
+  }
+  if (ping.serves) body.host = hostJsonSection(admin, wizard, shares)
+  if (ping.connects && client !== null) {
+    body.client = { maxServers: typeof client.maxServers === 'number' ? client.maxServers : 8, servers: arrayOf(client.servers) }
+  }
+  return body
+}
+
+/**
+ * `dsh-zen-remote status [--json] [--debug [outPath]]`. Identity from one
+ * ping; the host surfaces (admin status, wizard status, share list) and the
+ * client pool status each fetched only when the role answers them. Exit
+ * codes: 0 on any answered status, 1 when the ping itself or the debug
+ * round-trip failed.
+ */
+export async function runStatusCommand(ctx: CliExecutionContext): Promise<number> {
+  const { t, ipc, args } = ctx
+  const out = ctx.stdout
+  let ping: CliPingResponse
+  try {
+    ping = await ipc.ping()
+  } catch {
+    out.write(`${t('status.notRunning')}\n`)
+    return 1
+  }
+
+  if (args.options.debug || args.options.debugPath !== undefined) {
+    return await debugReportFlow(ctx, ping)
+  }
+
+  // The role decides which surfaces exist; fetches run concurrently and any
+  // failure degrades to "no information" rather than failing the command.
+  const [admin, wizard, shares, client] = await Promise.all([
+    ping.serves ? fetchBody(() => ipc.request('GET', ADMIN_STATUS_ROUTE)) : Promise.resolve(null),
+    ping.serves ? fetchBody(() => ipc.request('GET', WIZARD_STATUS_ROUTE)) : Promise.resolve(null),
+    ping.serves ? fetchBody(() => ipc.request('GET', ADMIN_SHARES_ROUTE)) : Promise.resolve(null),
+    ping.connects ? fetchBody(() => ipc.request('GET', CLIENT_STATUS_ROUTE)) : Promise.resolve(null),
+  ])
+
+  if (args.options.json) {
+    out.write(`${JSON.stringify(statusJsonBody(ping, admin, wizard, shares, client), null, 2)}\n`)
+    return 0
+  }
+
+  const lines = [
+    t('status.line.role', { role: t(`status.role.${ping.role}`) }),
+    t('status.machineName', { name: ping.serverName }),
+    t('status.pluginVersion', { version: ping.pluginVersion }),
+  ]
+  if (ping.profileName !== undefined) lines.push(t('status.profile', { profile: ping.profileName }))
+  if (ping.serves) lines.push(...renderHostSection(t, admin, wizard, shares))
+  if (ping.connects && client !== null) lines.push(...renderClientSection(t, client))
+  out.write(`${lines.join('\n')}\n`)
+  return 0
+}

package/src/cli/config-writer.ts

@@ -0,0 +1,354 @@
+/**
+ * The CLI's anti-shadowing config writer (CLI-1).
+ *
+ * `resolveConfig` reads four layers in the order env > row > file > default
+ * (src/config.ts). A CLI write lands in the FILE layer
+ * (`<dshHome>/lan-gate.config.json`), so two layers can silently swallow it:
+ * an environment variable set at the top, and a value the loader put on the
+ * plugin row (persisted in the current profile's `cordis.patch.yml`). The
+ * writer refuses the first case with the exact variable name, and REMOVES the
+ * shadowing keys in the other two — the in-memory row object `apply()` still
+ * holds, and the `dsh-zen-remote` `config:` block of every profile patch file
+ * it can find — so the just-written file value is what the next
+ * `resolveConfig` answers. `onAfterWrite` then lets the caller (the IPC
+ * delegate in src/index.ts) trigger the restart watcher immediately, so a
+ * restart-required field reloads the row without waiting out the 2s poll.
+ *
+ * The file is read from `dshHome` DIRECTLY, not through `readFileConfig(env)`:
+ * the latter resolves `<env.DSH_HOME ?? ~/.dsh>` and would silently read the
+ * developer's real file when a test passes an explicit dshHome with an empty
+ * env — resolution and the write must never disagree about which file is the
+ * truth.
+ *
+ * The `cordis.patch.yml` edit is line-based on purpose: the files are
+ * user-owned YAML full of comments and hand-tuned formatting that a
+ * parse-serialize round trip would destroy, and the edit itself (delete a
+ * key line and its indented children from one plugin's config block) is a
+ * purely textual operation.
+ */
+
+import { chmodSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { resolveConfig } from '../config.js'
+import type { ConfigSource, ZenRemoteConfig } from '../config.js'
+
+/**
+ * The env variable each config field answers to, for fields that HAVE one.
+ * Fields without an entry (role, serverName, idleHours, the wizard's ingress
+ * fields, pluginBridgeConsent — src/config.ts explains each absence) can
+ * never be env-shadowed, so they are deliberately missing: `writeCliConfig`
+ * falls back to the field name itself when asked for one.
+ */
+export const ENV_VAR_BY_FIELD: Readonly<Partial<Record<keyof ZenRemoteConfig, string>>> = {
+  port: 'LAN_GATE_PORT',
+  host: 'LAN_GATE_HOST',
+  targetPort: 'LAN_GATE_TARGET_PORT',
+  rateLimit: 'LAN_GATE_RATE_LIMIT',
+  trustedProxies: 'LAN_GATE_TRUSTED_PROXIES',
+  vapidSubject: 'LAN_GATE_VAPID_SUBJECT',
+  lang: 'LAN_GATE_LANG',
+  pushEvents: 'DSH_PUSH_EVENTS',
+  pushDebounceMs: 'DSH_PUSH_DEBOUNCE_MS',
+  pushSummary: 'DSH_PUSH_SUMMARY',
+  pushTurnEnd: 'DSH_PUSH_TURN_END',
+  pushTool: 'DSH_PUSH_TOOL',
+  pushEnabled: 'DSH_PUSH_ENABLED',
+  pushSessionName: 'DSH_PUSH_SESSION_NAME',
+}
+
+export interface WriteCliConfigOptions {
+  /** The DSH home the config files live under (`lan-gate.config.json`,
+   * `profiles/<name>/cordis.patch.yml`). Authoritative — env.DSH_HOME is
+   * not consulted. */
+  dshHome: string
+  /** The profile whose `cordis.patch.yml` is scanned FIRST; the fallback
+   * scan over every `<dshHome>/profiles/<name>/cordis.patch.yml` runs
+   * besides it, so an un-named profile carrying a stale key is un-shadowed
+   * too. */
+  profileName?: string | undefined
+  /** The plugin row as `apply()` received it (volatile `{ get() }` wrappers
+   * included). Shadowing keys on it are DELETED so the file layer shows
+   * through; omit on a composition without a row. */
+  row?: Record<string, unknown> | undefined
+  /** The environment carrying `LAN_GATE_*` / `DSH_PUSH_*`; defaults to
+   * `process.env`. */
+  env?: NodeJS.ProcessEnv | undefined
+  /** Keys to merge into `lan-gate.config.json` (and un-shadow everywhere). */
+  set?: Record<string, unknown> | undefined
+  /** Keys to delete from `lan-gate.config.json` (and un-shadow everywhere). */
+  unset?: readonly string[] | undefined
+  /** Called AFTER every successful write (never on a refusal and never for
+   * an empty write) — the IPC delegate passes the restart watcher's
+   * `checkNow`, which reloads the row at once when a restart-required field
+   * moved. */
+  onAfterWrite?: (() => void) | undefined
+}
+
+export type WriteCliConfigResult =
+  | { ok: true; values: ZenRemoteConfig }
+  | { ok: false; code: 'env-shadowed'; field: string; envVar: string }
+
+/**
+ * Keys that CLI explicitly wrote to `lan-gate.config.json` and unshadowed in
+ * `cordis.patch.yml` during this process lifetime, keyed by `dshHome`. When
+ * `fiber.restart()` reloads the plugin row, `cordis-plugin-loader` re-hydrates
+ * the new `config` object from its in-memory patch snapshot (without
+ * re-reading `cordis.patch.yml` from disk), which would otherwise re-shadow
+ * the file layer with stale `{ get() }` wrappers. `applyUnshadowedRowKeys`
+ * strips those stale wrappers on the reloaded `apply()`, and a subsequent
+ * Web UI save (`loader/volatile-update`) clears them via
+ * `clearUnshadowedRowKeys`.
+ */
+const unshadowedByHome = new Map<string, Set<string>>()
+
+export function applyUnshadowedRowKeys(dshHome: string, row: Record<string, unknown> | undefined): void {
+  if (row === undefined || row === null || typeof row !== 'object') return
+  const keys = unshadowedByHome.get(dshHome)
+  if (keys === undefined) return
+  for (const key of keys) {
+    const val = row[key]
+    if (val !== null && typeof val === 'object' && typeof (val as { get?: unknown }).get === 'function') {
+      delete row[key]
+    }
+  }
+}
+
+export function clearUnshadowedRowKeys(dshHome: string, keys: readonly string[]): void {
+  const set = unshadowedByHome.get(dshHome)
+  if (set === undefined) return
+  for (const key of keys) set.delete(key)
+}
+
+/** Read `<dshHome>/lan-gate.config.json` — `{}` when absent or unparsable,
+ * the same degrade-not-throw contract as src/config.ts's readFileConfig. */
+function readFileAt(dshHome: string): Record<string, unknown> {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(join(dshHome, 'lan-gate.config.json'), 'utf8'))
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return {}
+    return parsed as Record<string, unknown>
+  } catch {
+    return {}
+  }
+}
+
+/** Atomic 0600 rewrite: tmp + explicit chmod + rename, so a crash mid-write
+ * can never leave a half file behind (the discipline of the wizard's
+ * trust-proxy persister). */
+function writeJsonAtomic(dshHome: string, body: Record<string, unknown>): void {
+  const file = join(dshHome, 'lan-gate.config.json')
+  try {
+    mkdirSync(dshHome, { recursive: true })
+  } catch { /* an existing directory or an unwritable one — the write below reports it */ }
+  const tmp = `${file}.tmp-${process.pid}-${Date.now()}`
+  writeFileSync(tmp, `${JSON.stringify(body, null, 2)}\n`, { mode: 0o600 })
+  chmodSync(tmp, 0o600)
+  renameSync(tmp, file)
+}
+
+/** The candidate `cordis.patch.yml` paths: the named profile first (when
+ * given), then every profile's patch file found on disk — deduplicated, and
+ * only files that actually exist (the editor never CREATES one). */
+function patchFileCandidates(dshHome: string, profileName: string | undefined): string[] {
+  const out: string[] = []
+  const push = (candidate: string): void => {
+    if (!out.includes(candidate) && existsQuiet(candidate)) out.push(candidate)
+  }
+  if (profileName !== undefined && profileName !== '') {
+    push(join(dshHome, 'profiles', profileName, 'cordis.patch.yml'))
+  }
+  const profilesDir = join(dshHome, 'profiles')
+  try {
+    for (const entry of readdirSync(profilesDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue
+      if (entry.name === 'node_modules' || entry.name.startsWith('.') || entry.name === 'desktop') continue
+      push(join(profilesDir, entry.name, 'cordis.patch.yml'))
+    }
+  } catch { /* no profiles directory — nothing to scan */ }
+  return out
+}
+
+function existsQuiet(path: string): boolean {
+  try {
+    statSync(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function leadingSpaces(line: string): number {
+  const match = /^[ \t]*/u.exec(line)
+  return match === null ? 0 : match[0].length
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&')
+}
+
+/**
+ * Remove `keys` from EVERY `- id: dsh-zen-remote` (or bare `id:`) entry's
+ * `config:` block, purely textually: a key line and its deeper-indented
+ * children disappear, every other line — comments, other plugins' blocks,
+ * formatting — survives byte for byte. A block emptied by the removal keeps
+ * a `config: {}` line (an entry with no config key at all changes loader
+ * semantics). No match, no change: the same string comes back.
+ */
+export function unshadowPatchYml(text: string, keys: readonly string[]): string {
+  if (keys.length === 0) return text
+  const lines = text.split('\n')
+  const toDelete = new Set<number>()
+  const toReplace = new Map<number, string>()
+
+  for (let i = 0; i < lines.length; i += 1) {
+    // The id line: an optional dash + `id: dsh-zen-remote`, trailing comment
+    // allowed (`- id: agent-default-model # magpie` shows the shape). The
+    // id KEY's column is the prefix length — `config:` sits at that column.
+    const idMatch = /^([ \t]*(?:-[ \t]+)?)(id):[ \t]*dsh-zen-remote[ \t]*(?:#.*)?$/u.exec(lines[i])
+    if (idMatch === null) continue
+    const keyIndent = idMatch[1].length
+
+    // The entry's `config:` line: the first `config:` at the id column
+    // before the entry ends (a shallower line starts the next entry).
+    let configLine = -1
+    let configIndent = -1
+    for (let j = i + 1; j < lines.length; j += 1) {
+      const line = lines[j]
+      if (line.trim() === '') continue
+      const indent = leadingSpaces(line)
+      if (indent < keyIndent) break
+      if (indent === keyIndent && /^[ \t]*config[ \t]*:(\s|$|#)/u.test(line)) {
+        configLine = j
+        configIndent = indent
+        break
+      }
+    }
+    if (configLine === -1) continue
+
+    // The config block: every following line deeper than the config column
+    // (blank lines skipped — they belong to no key). The shallowest indent
+    // inside the block is where its top-level keys sit.
+    let blockEnd = configLine + 1
+    let minIndent = Number.POSITIVE_INFINITY
+    while (blockEnd < lines.length) {
+      const line = lines[blockEnd]
+      if (line.trim() === '') {
+        blockEnd += 1
+        continue
+      }
+      const indent = leadingSpaces(line)
+      if (indent <= configIndent) break
+      if (indent < minIndent) minIndent = indent
+      blockEnd += 1
+    }
+    if (!Number.isFinite(minIndent)) continue
+
+    for (const key of keys) {
+      const keyLine = new RegExp(`^([ \\t]*)${escapeRegExp(key)}[ \\t]*:(\\s|$|#)`, 'u')
+      for (let j = configLine + 1; j < blockEnd; j += 1) {
+        if (toDelete.has(j)) continue
+        const line = lines[j]
+        if (line.trim() === '') continue
+        const indent = leadingSpaces(line)
+        if (indent !== minIndent || !keyLine.test(line)) continue
+        toDelete.add(j)
+        // The key's children (deeper-indented lists/maps) go with it.
+        for (let q = j + 1; q < blockEnd; q += 1) {
+          const child = lines[q]
+          if (child.trim() === '') continue
+          if (leadingSpaces(child) <= indent) break
+          toDelete.add(q)
+        }
+      }
+    }
+    // Emptied block → keep a `config: {}` line so the entry's shape survives.
+    let remains = false
+    for (let j = configLine + 1; j < blockEnd; j += 1) {
+      if (!toDelete.has(j) && lines[j].trim() !== '') {
+        remains = true
+        break
+      }
+    }
+    if (!remains) toReplace.set(configLine, `${' '.repeat(configIndent)}config: {}`)
+  }
+
+  if (toDelete.size === 0 && toReplace.size === 0) return text
+  const out: string[] = []
+  for (let i = 0; i < lines.length; i += 1) {
+    const replacement = toReplace.get(i)
+    if (replacement !== undefined) out.push(replacement)
+    else if (!toDelete.has(i)) out.push(lines[i])
+  }
+  return out.join('\n')
+}
+
+/**
+ * Write CLI config changes through the anti-shadowing pipeline. Returns the
+ * refused `env-shadowed` verdict (with the exact field and its variable
+ * name) WITHOUT touching any file, or the freshly resolved effective values
+ * after the write, the row-key deletions and the patch-file un-shadowing.
+ */
+export function writeCliConfig(options: WriteCliConfigOptions): WriteCliConfigResult {
+  const env = options.env ?? process.env
+  const row = options.row ?? {}
+  const set = options.set ?? {}
+  const unset = options.unset ?? []
+  const setKeys = Object.keys(set)
+  const targetKeys = [...setKeys, ...unset]
+
+  if (targetKeys.length > 0) {
+    // Step 1 — the env layer is untouchable from here: a field whose CURRENT
+    // effective source is `env` (a legal value lives in a LAN_GATE_* /
+    // DSH_PUSH_* variable) refuses the write outright, naming the variable.
+    const snapshot = resolveConfig(row, readFileAt(options.dshHome), env)
+    const sources = snapshot.sources as Record<string, ConfigSource>
+    for (const key of targetKeys) {
+      if (sources[key] !== 'env') continue
+      return { ok: false, code: 'env-shadowed', field: key, envVar: ENV_VAR_BY_FIELD[key as keyof ZenRemoteConfig] ?? key }
+    }
+
+    // Step 2 — the file layer: merge / delete the keys atomically (0600).
+    const merged: Record<string, unknown> = { ...readFileAt(options.dshHome) }
+    for (const key of setKeys) merged[key] = set[key]
+    for (const key of unset) delete merged[key]
+    writeJsonAtomic(options.dshHome, merged)
+
+    // Step 3a — the row layer: the loader wrapped the row's volatile fields
+    // in `{ get() }` references, but they are still plain own properties of
+    // the same object apply() holds — a delete makes the NEXT resolveConfig
+    // fall through this layer to the freshly written file. Record the keys
+    // for this `dshHome` so a subsequent `fiber.restart()` also strips the
+    // loader's re-hydrated in-memory `{ get() }` wrappers.
+    let remembered = unshadowedByHome.get(options.dshHome)
+    if (remembered === undefined) {
+      remembered = new Set<string>()
+      unshadowedByHome.set(options.dshHome, remembered)
+    }
+    for (const key of targetKeys) {
+      remembered.add(key)
+      if (key in row) delete row[key]
+    }
+
+    // Step 3b — the persisted row layer: the profile patch files the loader
+    // itself writes when a settings save pins a key on the plugin row.
+    for (const file of patchFileCandidates(options.dshHome, options.profileName)) {
+      try {
+        const before = readFileSync(file, 'utf8')
+        const after = unshadowPatchYml(before, targetKeys)
+        if (after === before) continue
+        let mode = 0o644
+        try {
+          mode = statSync(file).mode & 0o777
+        } catch { /* keep the default */ }
+        const tmp = `${file}.tmp-${process.pid}-${Date.now()}`
+        writeFileSync(tmp, after, { mode })
+        renameSync(tmp, file)
+      } catch { /* one unreadable profile never blocks the others */ }
+    }
+
+    options.onAfterWrite?.()
+  }
+
+  // Step 4 — the caller's reload hook fired; answer the values the layers
+  // resolve to NOW (the file layer just moved; the row keys just left).
+  return { ok: true, values: resolveConfig(row, readFileAt(options.dshHome), env).values }
+}

package/src/cli/context.ts

@@ -0,0 +1,38 @@
+/**
+ * CLI-3: the execution context every command function receives. One bag with
+ * everything a command needs but never constructs itself — the parsed
+ * grammar, the live IPC client, the translator, and the interactivity
+ * verdict — plus the seams tests inject (a clock, a poll interval, an
+ * alternate working directory). Pure types: the real builder is CLI-5's
+ * main.ts; the tests assemble the object literal directly.
+ */
+
+import type { ParsedCliArgs } from './args.js'
+import type { CliIpcClient } from './ipc-client.js'
+import type { CliTranslator } from './i18n.js'
+import type { CliPrompter } from './bootstrap.js'
+
+export interface CliExecutionContext {
+  /** The command and options this run parsed. */
+  args: ParsedCliArgs
+  /** A client bound to the discovered live IPC socket. */
+  ipc: CliIpcClient
+  /** The translator for this run's language. */
+  t: CliTranslator
+  /** TTY && !`--yes`, decided once by the entry point (isInteractiveSession). */
+  interactive: boolean
+  /** The ask-everything funnel; present whenever the run may prompt. */
+  prompter?: CliPrompter
+  stdout: { write(text: string): void }
+  /** Clock for the `status --debug` default filename; default `new Date()`. */
+  now?: () => Date
+  /** Working directory for that default path; default `process.cwd()`. */
+  cwd?: string
+  /** `client pair`'s online-wait poll interval (default 250ms; tests shrink
+   * it — the 10s budget itself stays fixed). */
+  pollIntervalMs?: number
+  /** `host ingress verify`'s Ctrl-C seam: the entry point (CLI-5's main)
+   * aborts it on SIGINT so the phone-pairing wait can be skipped gracefully;
+   * tests abort it directly. */
+  abortSignal?: AbortSignal
+}