@myclaw163/clawclaw-cli 0.6.56 → 0.6.58

package/src/commands/watch.ts

@@ -1,16 +1,17 @@
 import { Command } from 'commander';
 import { existsSync, readFileSync, openSync, readSync, closeSync, statSync } from 'fs';
-import { dirname, join } from 'path';
+import { join } from 'path';
 import { AuthStore } from '../lib/auth.js';
 import { getProfileStateDir } from '../lib/init-command.js';
 import { setMeta } from '../lib/command-meta.js';
 import { EventStore, extractNewEvents } from '../pipeline/event-store.js';
 import { DEFAULT_MATCH_TIMEOUT_MS } from '../lib/match-state.js';
 import { hubReminder, readCachedGamesPlayed } from '../lib/hub-reminder.js';
+import { sendOwnerControlRequest } from '../runtime/owner-control.js';
 
 export const POLL_INTERVAL_MS = 220;
 const HEARTBEAT_INTERVAL_MS = 60_000;
-const DAEMON_WAIT_MS = 30_000;
+const RUNTIME_WAIT_MS = 30_000;
 
 export class WatchNotReadyError extends Error {
   constructor(message: string) {
@@ -19,12 +20,12 @@ export class WatchNotReadyError extends Error {
   }
 }
 
-/** Wait for event-daemon to create feed.json (parallel launch with `game start`). */
+/** Legacy helper for tests and explicit file-backed attaches. Owner paths use control socket snapshots. */
 export async function waitForFeed(
   feedPath: string,
   opts?: { signal?: AbortSignal; timeoutMs?: number; pollMs?: number },
 ): Promise<boolean> {
-  const timeoutMs = opts?.timeoutMs ?? DAEMON_WAIT_MS;
+  const timeoutMs = opts?.timeoutMs ?? RUNTIME_WAIT_MS;
   const pollMs = opts?.pollMs ?? POLL_INTERVAL_MS;
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
@@ -147,10 +148,10 @@ const ROUTING_RULES: RouteRule[] = [
   { reason: 'speech_your_turn',    match: (t) => t.includes('speech_your_turn'),   nextStep: 'It is YOUR turn to speak. Submit `ccl do -s "<draft>"` immediately. Server skips you after 45s.' },
   { reason: 'role_assigned',        match: (t) => t.includes('role_assigned'),      nextStep: 'Tell user your role, faction, win condition, and first plan.' },
   { reason: 'vote_cast',           match: (t) => t.includes('vote_cast'),          nextStep: 'A player just cast their vote. Read events[] to track who voted. No `ccl` action needed — cast your own vote immediately when vote phase starts.' },
-  { reason: 'match_start',         match: (t) => t.includes('match_start'),        nextStep: 'Matchmaking queue entered. The daemon is live and the stream is attached. Chat with the user while waiting for allocation.' },
+  { reason: 'match_start',         match: (t) => t.includes('match_start'),        nextStep: 'Matchmaking queue entered. The game runtime is live and the stream is attached. Chat with the user while waiting for allocation.' },
   { reason: 'match_waiting',       match: (t) => t.includes('match_waiting'),      nextStep: 'Still in queue (see `events[].waited_secs`). Keep chatting with the user; no tactical action required.' },
   { reason: 'match_timeout',       match: (t) => t.includes('match_timeout'),      nextStep: `Cumulative wait reached ${Math.round(DEFAULT_MATCH_TIMEOUT_MS / 60_000)} min (see \`events[].waited_secs\`). The stream will exit — discuss with the user: launch a fresh \`ccl game start\` to retry, or call it a session.` },
-  { reason: 'game_over',           match: (t) => t.includes('game_over'),          nextStep: 'Game ended. The stream process will exit. Run `ccl game start` for the next match — a single launch covers everything from queue to game_over.' },
+  { reason: 'game_over',           match: (t) => t.includes('game_over'),          nextStep: 'Game ended. The current ccl game start process is exiting automatically. Review the result with the user; start another match only if the user asks.' },
   { reason: 'strategy_alert',      match: (t) => t.includes('strategy_alert'),     nextStep: 'Your automation just made a decisive autonomous move and is briefing you (read events[].message). Lock your story to it before you next speak or vote — e.g. if it reported a corpse that is likely your own kill, present yourself as the proactive reporter, steer suspicion onto the bystanders, and do NOT confess.' },
 ];
 
@@ -259,53 +260,36 @@ export function compactEventForMonitor(event: GameEvent): GameEvent {
   return event;
 }
 
-function readAutomationSummary(feedPath: string): Record<string, any> | undefined {
-  try {
-    const raw = JSON.parse(readFileSync(join(dirname(feedPath), 'auto.json'), 'utf8'));
-    const strategy = typeof raw?.strategy === 'string' && raw.strategy.length > 0 ? raw.strategy : undefined;
-    if (!strategy) return undefined;
-    const pid = Number(raw?.pid);
-    let running = false;
-    if (Number.isFinite(pid) && pid > 0) {
-      try {
-        process.kill(pid, 0);
-        running = true;
-      } catch {
-        running = false;
-      }
-    }
-    return { strategy, running };
-  } catch {
-    return undefined;
-  }
+export function summarizeFeed(feed: any): any | null {
+  if (!feed || typeof feed !== 'object') return null;
+  const summary: any = {
+    phase: feed.phase,
+    you: {
+      name: feed.you?.name,
+      seat: feed.you?.seat,
+      role: feed.you?.role,
+      role_display: feed.you?.role_display,
+      faction: feed.you?.faction,
+      alive: feed.you?.alive,
+      x: feed.you?.x,
+      y: feed.you?.y,
+      currently_moving: feed.you?.currently_moving,
+      doing_task: feed.you?.doing_task,
+      kill_cooldown_secs: feed.you?.kill_cooldown_secs,
+      kills_remaining: feed.you?.kills_remaining,
+    },
+    game: feed.game,
+    urgent: feed.urgent,
+    meeting: feed.meeting,
+  };
+  if (feed.automation) summary.automation = feed.automation;
+  return summary;
 }
 
 export function readFeedSummary(feedPath: string): any | null {
   try {
     const feed = JSON.parse(readFileSync(feedPath, 'utf8'));
-    const summary: any = {
-      phase: feed.phase,
-      you: {
-        name: feed.you?.name,
-        seat: feed.you?.seat,
-        role: feed.you?.role,
-        role_display: feed.you?.role_display,
-        faction: feed.you?.faction,
-        alive: feed.you?.alive,
-        x: feed.you?.x,
-        y: feed.you?.y,
-        currently_moving: feed.you?.currently_moving,
-        doing_task: feed.you?.doing_task,
-        kill_cooldown_secs: feed.you?.kill_cooldown_secs,
-        kills_remaining: feed.you?.kills_remaining,
-      },
-      game: feed.game,
-      urgent: feed.urgent,
-      meeting: feed.meeting,
-    };
-    const automation = readAutomationSummary(feedPath);
-    if (automation) summary.automation = automation;
-    return summary;
+    return summarizeFeed(feed);
   } catch {
     return null;
   }
@@ -351,15 +335,17 @@ export function compactSummaryForMonitor(summary: any | null, triggers: string[]
 export interface RunStreamingOptions {
   feedPath: string;
   sessionPath: string | null;
+  readSummary?: () => any | null;
   /** Optional dynamic resolver — called each poll so the stream can follow session rotation across games. */
   getSessionPath?: () => string | null;
   stdout: (line: string) => void;
   signal?: AbortSignal;
+  skipFeedWait?: boolean;
   pollIntervalMs?: number;
   /** Emit a `heartbeat` NDJSON line after this many ms of silence so consumers don't see the stream as hung. Default 30s. Pass 0 to disable. */
   heartbeatIntervalMs?: number;
   /** Max ms to wait for feed.json when launching alongside `game start`. Default 30s. */
-  daemonWaitMs?: number;
+  runtimeWaitMs?: number;
   /**
    * Per-event-type delay overrides for the delay buffer (see DELAYABLE_EVENT_CONFIG).
    * Pass `{ kill: 0 }` to disable the kill delay in tests.
@@ -390,15 +376,17 @@ export interface RunStreamingOptions {
 }
 
 export async function runStreaming(opts: RunStreamingOptions): Promise<void> {
-  const feedReady = await waitForFeed(opts.feedPath, {
-    signal: opts.signal,
-    timeoutMs: opts.daemonWaitMs ?? DAEMON_WAIT_MS,
-    pollMs: opts.pollIntervalMs ?? POLL_INTERVAL_MS,
-  });
-  if (!feedReady) {
-    throw new WatchNotReadyError(
-      'Event daemon not ready (no feed.json). Run `ccl game start` to start or recover the game stream.',
-    );
+  if (!opts.skipFeedWait) {
+    const feedReady = await waitForFeed(opts.feedPath, {
+      signal: opts.signal,
+      timeoutMs: opts.runtimeWaitMs ?? RUNTIME_WAIT_MS,
+      pollMs: opts.pollIntervalMs ?? POLL_INTERVAL_MS,
+    });
+    if (!feedReady) {
+      throw new WatchNotReadyError(
+        'Game runtime not ready (no feed.json). Run `ccl game start` to start or recover the game stream.',
+      );
+    }
   }
   const interval = opts.pollIntervalMs ?? POLL_INTERVAL_MS;
   const heartbeatInterval = opts.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS;
@@ -409,10 +397,12 @@ export async function runStreaming(opts: RunStreamingOptions): Promise<void> {
     lastEmitMs = Date.now();
   };
 
-  // Initial state from feed.json (best-effort)
+  // Initial player name from owner snapshot or legacy feed file (best-effort).
   let youName: string | null = null;
   try {
-    youName = JSON.parse(readFileSync(opts.feedPath, 'utf8'))?.you?.name ?? null;
+    youName = opts.readSummary?.()?.you?.name
+      ?? JSON.parse(readFileSync(opts.feedPath, 'utf8'))?.you?.name
+      ?? null;
   } catch {}
 
   // Tail state for the .jsonl
@@ -427,7 +417,7 @@ export async function runStreaming(opts: RunStreamingOptions): Promise<void> {
     fileIno = statSync(currentSessionPath).ino;
   }
 
-  // Cross-game session rotation: daemon may create a new events.jsonl when a new
+  // Cross-game session rotation: the runtime may create a new events.jsonl when a new
   // game starts. If the caller provided a dynamic resolver, poll it and switch
   // tail state to the new file. Without this, the stream would silently follow the
   // previous game's file forever and look like a huge event delay.
@@ -492,10 +482,10 @@ export async function runStreaming(opts: RunStreamingOptions): Promise<void> {
     nextStep: string,
     events: GameEvent[] = [],
   ): any => {
-    const rawSummary = readFeedSummary(opts.feedPath);
+    const rawSummary = opts.readSummary?.() ?? readFeedSummary(opts.feedPath);
     const summary = compactSummaryForMonitor(rawSummary, triggers);
     // Server pushes `meeting_briefing` without `speech_order` (that field only lives in
-    // meeting state, which the daemon projects onto feed.json.meeting.speech_order).
+    // meeting state, which the runtime projects onto the owner snapshot).
     // Inject it onto the briefing event here so consumers can read it from events[]
     // directly. Guarded by caller match so a stale speech_order from a previous
     // meeting isn't ever attached.
@@ -641,7 +631,7 @@ export interface SnapshotOnceOptions {
 
 export function snapshotOnce(opts: SnapshotOnceOptions): void {
   if (!existsSync(opts.feedPath)) {
-    throw new Error('ccl daemon is not running. Start it first with `ccl game start`.');
+    throw new Error('ccl game runtime is not running. Start it first with `ccl game start`.');
   }
   const summary = readFeedSummary(opts.feedPath);
   const warning = summary?.phase === 'meeting'
@@ -661,7 +651,7 @@ export function buildErrorLine(err: any, opts?: { notReadyNextStep?: string }):
   const notReady = err?.name === 'WatchNotReadyError' || /not ready|feed\.json/i.test(msg);
   const reason = notReady ? 'not_ready' : 'error';
   const nextStep = notReady
-    ? (opts?.notReadyNextStep ?? 'Event daemon not running. Run `ccl game start` to begin a new session.')
+    ? (opts?.notReadyNextStep ?? 'Game runtime not running. Run `ccl game start` to begin a new session.')
     : msg;
   return JSON.stringify({
     exit_reason: [reason],
@@ -682,18 +672,37 @@ export function createWatchCommand(): Command {
         process.stdout.write(JSON.stringify({ exit_reason: ['not_logged_in'], error: 'Not logged in' }) + '\n');
         return;
       }
-      const feedPath = join(getProfileStateDir(profile), 'feed.json');
+      const stateDir = getProfileStateDir(profile);
+      const feedPath = join(stateDir, 'feed.json');
       const sessionPath = EventStore.latestSessionPath();
       const ctrl = new AbortController();
       process.on('SIGINT', () => ctrl.abort());
       process.on('SIGTERM', () => ctrl.abort());
+      let summaryCache: any | null = null;
+      let summaryPoll: ReturnType<typeof setInterval> | null = null;
       try {
+        const snapshot = await sendOwnerControlRequest(stateDir, 'snapshot');
+        if (!snapshot?.ok) {
+          throw new WatchNotReadyError(
+            'Game runtime not ready (no active ccl game start owner). Run `ccl game start` to start or recover the game stream.',
+          );
+        }
+        summaryCache = snapshot.summary ?? null;
+        summaryPoll = setInterval(() => {
+          void sendOwnerControlRequest(stateDir, 'snapshot')
+            .then((response) => {
+              if (response?.ok) summaryCache = response.summary ?? null;
+            })
+            .catch(() => {});
+        }, 1000);
         await runStreaming({
           feedPath,
           sessionPath,
           getSessionPath: () => EventStore.latestSessionPath(),
           stdout: (s) => process.stdout.write(s),
           signal: ctrl.signal,
+          skipFeedWait: true,
+          readSummary: () => summaryCache,
           hubReminder: hubReminder(readCachedGamesPlayed()),
         });
       } catch (err: any) {
@@ -701,6 +710,8 @@ export function createWatchCommand(): Command {
           notReadyNextStep: 'Run `ccl game start` to start or recover the game stream.',
         }));
         process.exit(1);
+      } finally {
+        if (summaryPoll) clearInterval(summaryPoll);
       }
     });
   // ── Adapter metadata: streaming mode blocks until game_over; cap at 30min for stuck-process safety ──

package/src/lib/game-client.ts

@@ -48,7 +48,7 @@ export class GameClient {
 
   /**
    * Create GameClient from active auth profile.
-   * Used by both daemon (ws: true) and CLI commands (ws: false).
+   * Used by both runtime listeners (ws: true) and CLI commands (ws: false).
    */
   static fromAuth(opts?: { ws?: boolean; authStore?: AuthStore; rawWsLogPath?: string }): GameClient {
     const store = opts?.authStore ?? new AuthStore();
@@ -282,7 +282,7 @@ export class GameClient {
       await newWs.connect();
       return true;
     } catch {
-      this.log.warn('WS_CONNECT', 'event WebSocket connection failed; daemon will retry');
+      this.log.warn('WS_CONNECT', 'event WebSocket connection failed; runtime will retry');
       newWs.disconnect();
       this.ws = null;
       this.markWsHandlersDetached();
@@ -344,7 +344,7 @@ export class GameClient {
       await newWs.connect();
       this.log.info('WS_RECONNECT', `connected to ${wsUrl}`);
     } catch {
-      this.log.warn('WS_RECONNECT', 'event WebSocket reconnect failed; daemon will retry');
+      this.log.warn('WS_RECONNECT', 'event WebSocket reconnect failed; runtime will retry');
       newWs.disconnect();
       this.ws = null;
       this.markWsHandlersDetached();

package/src/lib/host-config-patcher.test.ts

@@ -1,130 +1,130 @@
-import { mkdtempSync, readFileSync, writeFileSync, existsSync, readdirSync } from 'fs';
-import { tmpdir } from 'os';
-import { dirname, join } from 'path';
-import { describe, expect, it } from 'vitest';
-import { runHostConfigSetup, unionArrayField, type HostConfigPatcher } from './host-config-patcher.js';
-
-function tmpConfig(initial: unknown): string {
-  const dir = mkdtempSync(join(tmpdir(), 'host-cfg-'));
-  const p = join(dir, 'config.json');
-  writeFileSync(p, JSON.stringify(initial, null, 2));
-  return p;
-}
-
-const dummyHost: HostConfigPatcher<{ value: string }> = {
-  hostName: 'dummy',
-  resolveConfigPath: () => '/tmp/never-used',
-  computePatch: (current, opts) => {
-    const cur = (current as Record<string, unknown> | null) ?? {};
-    const before = (cur.values as string[] | undefined) ?? [];
-    if (before.includes(opts.value)) return { next: cur, changes: [], warnings: [] };
-    return {
-      next: { ...cur, values: [...before, opts.value] },
-      changes: [`add ${opts.value} to values`],
-      warnings: [],
-    };
-  },
-};
-
-describe('runHostConfigSetup', () => {
-  it('prints recommended patch in --print mode without touching disk', () => {
-    const r = runHostConfigSetup(dummyHost, { value: 'x' }, { print: true });
-    expect(r.exitCode).toBe(0);
-    expect(r.output.join('\n')).toContain('"values"');
-  });
-
-  it('reports missing config file gracefully', () => {
-    const r = runHostConfigSetup(dummyHost, { value: 'x' }, { configPath: '/no/such/file.json' });
-    expect(r.exitCode).toBe(0);
-    expect(r.output.some((l) => l.includes('not found'))).toBe(true);
-  });
-
-  it('reports malformed JSON with exit 1', () => {
-    const dir = mkdtempSync(join(tmpdir(), 'host-cfg-bad-'));
-    const p = join(dir, 'config.json');
-    writeFileSync(p, '{ not: valid json');
-    const r = runHostConfigSetup(dummyHost, { value: 'x' }, { configPath: p });
-    expect(r.exitCode).toBe(1);
-    expect(r.output.join('\n')).toMatch(/Failed to parse/);
-  });
-
-  it('returns exit 2 with diff in dry-run when changes pending', () => {
-    const p = tmpConfig({ values: ['a'] });
-    const r = runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p });
-    expect(r.exitCode).toBe(2);
-    const txt = r.output.join('\n');
-    expect(txt).toMatch(/Pending changes/);
-    expect(txt).toMatch(/Re-run with -y to apply/);
-    // file unchanged
-    expect(JSON.parse(readFileSync(p, 'utf-8'))).toEqual({ values: ['a'] });
-  });
-
-  it('returns exit 0 no-op when already up to date', () => {
-    const p = tmpConfig({ values: ['a'] });
-    const r = runHostConfigSetup(dummyHost, { value: 'a' }, { configPath: p });
-    expect(r.exitCode).toBe(0);
-    expect(r.output.join('\n')).toMatch(/already up to date/);
-  });
-
-  it('applies changes atomically with backup when -y', () => {
-    const p = tmpConfig({ values: ['a'] });
-    const r = runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true });
-    expect(r.exitCode).toBe(0);
-    expect(JSON.parse(readFileSync(p, 'utf-8'))).toEqual({ values: ['a', 'b'] });
-    const files = readdirSync(dirname(p));
-    expect(files.some((f) => f.startsWith('config.json.bak.'))).toBe(true);
-  });
-
-  it('--no-backup skips backup file', () => {
-    const p = tmpConfig({ values: ['a'] });
-    const r = runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true, backup: false });
-    expect(r.exitCode).toBe(0);
-    const files = readdirSync(dirname(p));
-    expect(files.some((f) => f.startsWith('config.json.bak.'))).toBe(false);
-  });
-
-  it('does not leave .tmp file behind on success', () => {
-    const p = tmpConfig({ values: ['a'] });
-    runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true, backup: false });
-    const files = readdirSync(dirname(p));
-    expect(files.some((f) => f.includes('.tmp.'))).toBe(false);
-  });
-
-  it('preserves CRLF line endings when original file uses CRLF', () => {
-    const dir = mkdtempSync(join(tmpdir(), 'host-cfg-crlf-'));
-    const p = join(dir, 'config.json');
-    writeFileSync(p, '{\r\n  "values": [\r\n    "a"\r\n  ]\r\n}\r\n');
-    runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true, backup: false });
-    const after = readFileSync(p, 'utf-8');
-    expect(after.includes('\r\n')).toBe(true);
-    expect(after.replace(/\r\n/g, '<EOL>').includes('\n')).toBe(false);
-  });
-
-  it('preserves LF line endings when original file uses LF', () => {
-    const dir = mkdtempSync(join(tmpdir(), 'host-cfg-lf-'));
-    const p = join(dir, 'config.json');
-    writeFileSync(p, '{\n  "values": [\n    "a"\n  ]\n}\n');
-    runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true, backup: false });
-    const after = readFileSync(p, 'utf-8');
-    expect(after.includes('\r\n')).toBe(false);
-  });
-});
-
-describe('unionArrayField', () => {
-  it('creates new array when field missing', () => {
-    expect(unionArrayField(undefined, 'x')).toEqual({ next: ['x'], added: true });
-  });
-
-  it('returns warning when existing value is not an array', () => {
-    const r = unionArrayField('not-an-array', 'x');
-    expect(r).toEqual({ warning: 'existing value is not an array, refusing to overwrite' });
-  });
-
-  it('returns added=false when entry already present', () => {
-    expect(unionArrayField(['a', 'b'], 'a')).toEqual({ next: ['a', 'b'], added: false });
-  });
-
-  it('appends entry when missing from array', () => {
-    expect(unionArrayField(['a'], 'b')).toEqual({ next: ['a', 'b'], added: true });
-  });
-});
+import { mkdtempSync, readFileSync, writeFileSync, existsSync, readdirSync } from 'fs';
+import { tmpdir } from 'os';
+import { dirname, join } from 'path';
+import { describe, expect, it } from 'vitest';
+import { runHostConfigSetup, unionArrayField, type HostConfigPatcher } from './host-config-patcher.js';
+
+function tmpConfig(initial: unknown): string {
+  const dir = mkdtempSync(join(tmpdir(), 'host-cfg-'));
+  const p = join(dir, 'config.json');
+  writeFileSync(p, JSON.stringify(initial, null, 2));
+  return p;
+}
+
+const dummyHost: HostConfigPatcher<{ value: string }> = {
+  hostName: 'dummy',
+  resolveConfigPath: () => '/tmp/never-used',
+  computePatch: (current, opts) => {
+    const cur = (current as Record<string, unknown> | null) ?? {};
+    const before = (cur.values as string[] | undefined) ?? [];
+    if (before.includes(opts.value)) return { next: cur, changes: [], warnings: [] };
+    return {
+      next: { ...cur, values: [...before, opts.value] },
+      changes: [`add ${opts.value} to values`],
+      warnings: [],
+    };
+  },
+};
+
+describe('runHostConfigSetup', () => {
+  it('prints recommended patch in --print mode without touching disk', () => {
+    const r = runHostConfigSetup(dummyHost, { value: 'x' }, { print: true });
+    expect(r.exitCode).toBe(0);
+    expect(r.output.join('\n')).toContain('"values"');
+  });
+
+  it('reports missing config file gracefully', () => {
+    const r = runHostConfigSetup(dummyHost, { value: 'x' }, { configPath: '/no/such/file.json' });
+    expect(r.exitCode).toBe(0);
+    expect(r.output.some((l) => l.includes('not found'))).toBe(true);
+  });
+
+  it('reports malformed JSON with exit 1', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'host-cfg-bad-'));
+    const p = join(dir, 'config.json');
+    writeFileSync(p, '{ not: valid json');
+    const r = runHostConfigSetup(dummyHost, { value: 'x' }, { configPath: p });
+    expect(r.exitCode).toBe(1);
+    expect(r.output.join('\n')).toMatch(/Failed to parse/);
+  });
+
+  it('returns exit 2 with diff in dry-run when changes pending', () => {
+    const p = tmpConfig({ values: ['a'] });
+    const r = runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p });
+    expect(r.exitCode).toBe(2);
+    const txt = r.output.join('\n');
+    expect(txt).toMatch(/Pending changes/);
+    expect(txt).toMatch(/Re-run with -y to apply/);
+    // file unchanged
+    expect(JSON.parse(readFileSync(p, 'utf-8'))).toEqual({ values: ['a'] });
+  });
+
+  it('returns exit 0 no-op when already up to date', () => {
+    const p = tmpConfig({ values: ['a'] });
+    const r = runHostConfigSetup(dummyHost, { value: 'a' }, { configPath: p });
+    expect(r.exitCode).toBe(0);
+    expect(r.output.join('\n')).toMatch(/already up to date/);
+  });
+
+  it('applies changes atomically with backup when -y', () => {
+    const p = tmpConfig({ values: ['a'] });
+    const r = runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true });
+    expect(r.exitCode).toBe(0);
+    expect(JSON.parse(readFileSync(p, 'utf-8'))).toEqual({ values: ['a', 'b'] });
+    const files = readdirSync(dirname(p));
+    expect(files.some((f) => f.startsWith('config.json.bak.'))).toBe(true);
+  });
+
+  it('--no-backup skips backup file', () => {
+    const p = tmpConfig({ values: ['a'] });
+    const r = runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true, backup: false });
+    expect(r.exitCode).toBe(0);
+    const files = readdirSync(dirname(p));
+    expect(files.some((f) => f.startsWith('config.json.bak.'))).toBe(false);
+  });
+
+  it('does not leave .tmp file behind on success', () => {
+    const p = tmpConfig({ values: ['a'] });
+    runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true, backup: false });
+    const files = readdirSync(dirname(p));
+    expect(files.some((f) => f.includes('.tmp.'))).toBe(false);
+  });
+
+  it('preserves CRLF line endings when original file uses CRLF', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'host-cfg-crlf-'));
+    const p = join(dir, 'config.json');
+    writeFileSync(p, '{\r\n  "values": [\r\n    "a"\r\n  ]\r\n}\r\n');
+    runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true, backup: false });
+    const after = readFileSync(p, 'utf-8');
+    expect(after.includes('\r\n')).toBe(true);
+    expect(after.replace(/\r\n/g, '<EOL>').includes('\n')).toBe(false);
+  });
+
+  it('preserves LF line endings when original file uses LF', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'host-cfg-lf-'));
+    const p = join(dir, 'config.json');
+    writeFileSync(p, '{\n  "values": [\n    "a"\n  ]\n}\n');
+    runHostConfigSetup(dummyHost, { value: 'b' }, { configPath: p, yes: true, backup: false });
+    const after = readFileSync(p, 'utf-8');
+    expect(after.includes('\r\n')).toBe(false);
+  });
+});
+
+describe('unionArrayField', () => {
+  it('creates new array when field missing', () => {
+    expect(unionArrayField(undefined, 'x')).toEqual({ next: ['x'], added: true });
+  });
+
+  it('returns warning when existing value is not an array', () => {
+    const r = unionArrayField('not-an-array', 'x');
+    expect(r).toEqual({ warning: 'existing value is not an array, refusing to overwrite' });
+  });
+
+  it('returns added=false when entry already present', () => {
+    expect(unionArrayField(['a', 'b'], 'a')).toEqual({ next: ['a', 'b'], added: false });
+  });
+
+  it('appends entry when missing from array', () => {
+    expect(unionArrayField(['a'], 'b')).toEqual({ next: ['a', 'b'], added: true });
+  });
+});