@murmurv2/cli 2.11.0

package/runtime/packages/setup/dist/src/cli.js

@@ -0,0 +1,130 @@
+import { configureClient, previewClientConfiguration } from './clients.js';
+import { prepareReplyTest, checkReplyTest } from './reply-test.js';
+import { listOutboxAttention, setOutboxDismissed } from './outbox-attention.js';
+import { initialize, invite, join, importPeer } from './onboarding.js';
+import { runDoctor } from './doctor.js';
+import { parseArgs } from 'node:util';
+import path from 'node:path';
+import { resolveContext } from './paths.js';
+import { createLinuxAdapter } from './platform/linux.js';
+import { createWindowsAdapter } from './platform/windows.js';
+import { createDarwinAdapter } from './platform/darwin.js';
+import { readStatus } from './status.js';
+import { setWakeEnabled, markInboxRead, readInbox, readLogPath } from './commands.js';
+import { renderStatusLine } from './status-line.js';
+import { readVersion, checkUpdates, setUpdateChecks } from './updates.js';
+export function platformAdapter() {
+    if (process.platform === 'linux')
+        return createLinuxAdapter();
+    if (process.platform === 'darwin')
+        return createDarwinAdapter();
+    if (process.platform === 'win32')
+        return createWindowsAdapter();
+    return { manager: 'none',
+        async status() {
+            return { state: 'unknown', manager: 'none', pid: null, since: null, lastExitCode: null,
+                observedStorePath: null, restartCount: null, restartWindowMs: null, detail: 'service.adapter-unavailable' };
+        },
+        async install() { throw new Error('service.adapter-unavailable'); },
+        async start() { throw new Error('service.adapter-unavailable'); },
+        async stop() { throw new Error('service.adapter-unavailable'); },
+        async detectClients() { return []; },
+    };
+}
+export const rawCliOutput = (text) => ({ kind: 'raw', text });
+export const isRawCliOutput = (value) => !!value && typeof value === 'object'
+    && value.kind === 'raw' && typeof value.text === 'string';
+export async function main(args, adapter = platformAdapter()) {
+    // `murmur --version` is the first thing people type after npm install; answer it like `murmur version`.
+    if (args.some(a => a === '--version' || a === '-v') && args.every(a => ['--version', '-v', '--json'].includes(a)))
+        return readVersion();
+    let parsed;
+    try {
+        parsed = parseArgs({ args, allowPositionals: true, options: {
+                'msg-id': { type: 'string' }, 'expected-state': { type: 'string' }, 'expected-agent': { type: 'string' },
+                'agent-id': { type: 'string' }, 'broker-url': { type: 'string' }, 'token-file': { type: 'string' }, 'invite-file': { type: 'string' }, 'reply-file': { type: 'string' }, 'reply-out': { type: 'string' }, out: { type: 'string' },
+                client: { type: 'string' }, replace: { type: 'boolean' }, 'plan-id': { type: 'string' }, 'test-token': { type: 'string' }, json: { type: 'boolean' }, line: { type: 'boolean' }, limit: { type: 'string' }, peer: { type: 'string' }, timeout: { type: 'string' }, 'data-dir': { type: 'string' }, 'service-name': { type: 'string' }, apply: { type: 'boolean' }, help: { type: 'boolean' },
+            } });
+    }
+    catch (error) {
+        // parseArgs explains itself in a sentence, which safeError must hide; keep a stable code instead.
+        throw new Error(error.code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION' ? 'cli.unknown-option' : 'cli.invalid-arguments');
+    }
+    const { values, positionals } = parsed;
+    if (values.help || !positionals.length)
+        return { commands: ['version --json', 'updates check|enable|disable --json', 'init --agent-id ID --broker-url URL [--token-file FILE]', 'invite --out FILE', 'join --agent-id ID --invite-file FILE --reply-out FILE', 'add-peer --reply-file FILE', 'status --json|--line', 'doctor --json [--peer AGENT] [--timeout MILLISECONDS]', 'logs path --json', 'service install|start|stop|uninstall', 'clients detect', 'clients preview --client ID', 'clients configure --client ID [--replace] [--plan-id SHA256]', 'reply-test prepare --peer AGENT', 'reply-test check --test-token TOKEN', 'wake pause|resume [--apply]', 'inbox read [--limit 1..100]', 'inbox mark-read', 'outbox list --json', 'outbox dismiss|restore --msg-id ID --expected-state TOKEN --expected-agent ID', 'mcp serve --data-dir ABSOLUTE'],
+            options: ['--data-dir ABSOLUTE', '--service-name NAME'], note: 'Windows service mutations require an elevated terminal and the matching native helper.' };
+    const [command, action, extra] = positionals;
+    if (extra)
+        throw new Error('cli.unexpected-argument');
+    if (values.line && command !== 'status')
+        throw new Error('cli.line-only-for-status');
+    if (values.line && values.json)
+        throw new Error('cli.output-mode-conflict');
+    if (command === 'version' && !action)
+        return readVersion();
+    if (command === 'updates' && action === 'check')
+        return checkUpdates();
+    if (command === 'updates' && ['enable', 'disable'].includes(action))
+        return setUpdateChecks(action === 'enable');
+    const context = resolveContext({ dataDir: values['data-dir'], serviceName: values['service-name'] });
+    const required = (name) => { const value = values[name]; if (typeof value !== 'string' || !value)
+        throw new Error('cli.required-option:' + name); return value; };
+    if (command === 'init' && !action)
+        return initialize(context, { agentId: required('agent-id'), brokerUrl: required('broker-url'), tokenFile: values['token-file'] });
+    if (command === 'invite' && !action)
+        return invite(context, required('out'));
+    if (command === 'join' && !action)
+        return join(context, { agentId: required('agent-id'), inviteFile: required('invite-file'), replyOut: required('reply-out') });
+    if (command === 'add-peer' && !action)
+        return importPeer(context, required('reply-file'));
+    if (command === 'status' && !action) {
+        const status = await readStatus({ context, adapter });
+        return values.line ? rawCliOutput(renderStatusLine(status)) : status;
+    }
+    if (command === 'outbox' && action === 'list')
+        return listOutboxAttention(context);
+    if (command === 'outbox' && ['dismiss', 'restore'].includes(action))
+        return setOutboxDismissed(context, required('msg-id'), required('expected-state'), required('expected-agent'), action === 'dismiss');
+    if (command === 'mcp' && action === 'serve') {
+        if (values['data-dir'] === undefined)
+            throw new Error('cli.required-option:data-dir');
+        process.env.DATA_DIR = context.dataDir;
+        process.env.MURMUR_DATA_DIR = context.dataDir;
+        process.env.MURMUR_STORE_PATH = context.storePath;
+        process.env.MURMUR_CHANNEL_ROSTER_PATH = path.join(context.dataDir, 'channel-roster.db');
+        await import('@murmurv2/mcp-server');
+        return rawCliOutput('');
+    }
+    if (command === 'logs' && action === 'path') {
+        if (process.platform === 'win32')
+            throw new Error('logs.windows-native-location-unavailable');
+        return readLogPath(context);
+    }
+    if (command === 'doctor' && !action)
+        return runDoctor({ context, adapter, peer: values.peer, timeoutMs: values.timeout === undefined ? undefined : Number(values.timeout) });
+    if (command === 'clients' && action === 'preview')
+        return previewClientConfiguration(context, adapter, required('client'));
+    if (command === 'clients' && action === 'configure')
+        return configureClient(context, adapter, required('client'), values.replace, values['plan-id']);
+    if (command === 'clients' && action === 'detect')
+        return { schema: 'murmur.clients/1', clients: await adapter.detectClients(context) };
+    if (command === 'reply-test' && action === 'prepare')
+        return prepareReplyTest(context, required('peer'));
+    if (command === 'reply-test' && action === 'check')
+        return checkReplyTest(context, required('test-token'));
+    if (command === 'wake' && ['pause', 'resume'].includes(action))
+        return setWakeEnabled(context, adapter, action === 'resume', values.apply);
+    if (command === 'inbox' && action === 'read')
+        return readInbox(context, values.limit === undefined ? 20 : Number(values.limit));
+    if (command === 'inbox' && action === 'mark-read')
+        return markInboxRead(context);
+    if (command === 'service' && ['install', 'start', 'stop', 'uninstall'].includes(action)) {
+        const operation = adapter[action];
+        if (!operation)
+            throw new Error('service.uninstall-unavailable');
+        await operation.call(adapter, context);
+        return { schema: 'murmur.service/1', action, service: await adapter.status(context) };
+    }
+    throw new Error('cli.unknown-command');
+}

package/runtime/packages/setup/dist/src/clients.d.ts

@@ -0,0 +1,151 @@
+import type { PlatformAdapter, ServiceContext } from './types.js';
+export { sameClientFileIdentity } from './file-identity.js';
+/** Read-only preview: even a missing parent directory is not created. */
+export declare function previewClientConfiguration(c: ServiceContext, adapter: PlatformAdapter, clientId: string): Promise<{
+    wakeHook?: {
+        settingsPath: string;
+        action: "replace" | "unchanged" | "add";
+    } | undefined;
+    schema: string;
+    client: "claude-code" | "claude-desktop" | "codex-cli" | "codex-desktop";
+    configPath: string;
+    agentId: string;
+    dataDir: string;
+    action: string;
+    planId: string;
+    configExisted: boolean;
+    restartRequired: boolean;
+}>;
+/**
+ * Patch only the selected Murmur entry; never execute a client or touch its auth. For Claude Code
+ * also install the Stop wake hook, so a delivered message wakes the session without a human turn.
+ */
+export declare function configureClient(c: ServiceContext, adapter: PlatformAdapter, clientId: string, replace?: boolean, expectedPlan?: string): Promise<{
+    planId: string;
+    agentId: string;
+    dataDir: string;
+    schema: string;
+    client: "claude-code" | "claude-desktop" | "codex-cli" | "codex-desktop";
+    configPath: string;
+    changed: boolean;
+    backup: null;
+    restartRequired: boolean;
+} | {
+    planId?: undefined;
+    agentId?: undefined;
+    dataDir?: undefined;
+    schema: string;
+    client: "claude-code" | "claude-desktop" | "codex-cli" | "codex-desktop";
+    configPath: string;
+    changed: boolean;
+    backup: null;
+    restartRequired: boolean;
+} | {
+    restartRequired: boolean;
+    instruction: string;
+    planId: string;
+    agentId: string;
+    dataDir: string;
+    schema: string;
+    client: "claude-code" | "claude-desktop" | "codex-cli" | "codex-desktop";
+    configPath: string;
+    changed: boolean;
+    backup: string | null;
+} | {
+    restartRequired: boolean;
+    instruction: string;
+    planId?: undefined;
+    agentId?: undefined;
+    dataDir?: undefined;
+    schema: string;
+    client: "claude-code" | "claude-desktop" | "codex-cli" | "codex-desktop";
+    configPath: string;
+    changed: boolean;
+    backup: string | null;
+} | {
+    changed: boolean;
+    wakeHook: {
+        settingsPath: string;
+        action: "unchanged";
+        changed: boolean;
+        backup: null;
+    } | {
+        settingsPath: string;
+        action: "replace" | "add";
+        changed: boolean;
+        backup: string | null;
+    };
+    planId: string;
+    agentId: string;
+    dataDir: string;
+    schema: string;
+    client: "claude-code" | "claude-desktop" | "codex-cli" | "codex-desktop";
+    configPath: string;
+    backup: null;
+    restartRequired: boolean;
+} | {
+    changed: boolean;
+    wakeHook: {
+        settingsPath: string;
+        action: "unchanged";
+        changed: boolean;
+        backup: null;
+    } | {
+        settingsPath: string;
+        action: "replace" | "add";
+        changed: boolean;
+        backup: string | null;
+    };
+    planId?: undefined;
+    agentId?: undefined;
+    dataDir?: undefined;
+    schema: string;
+    client: "claude-code" | "claude-desktop" | "codex-cli" | "codex-desktop";
+    configPath: string;
+    backup: null;
+    restartRequired: boolean;
+} | {
+    changed: boolean;
+    wakeHook: {
+        settingsPath: string;
+        action: "unchanged";
+        changed: boolean;
+        backup: null;
+    } | {
+        settingsPath: string;
+        action: "replace" | "add";
+        changed: boolean;
+        backup: string | null;
+    };
+    restartRequired: boolean;
+    instruction: string;
+    planId: string;
+    agentId: string;
+    dataDir: string;
+    schema: string;
+    client: "claude-code" | "claude-desktop" | "codex-cli" | "codex-desktop";
+    configPath: string;
+    backup: string | null;
+} | {
+    changed: boolean;
+    wakeHook: {
+        settingsPath: string;
+        action: "unchanged";
+        changed: boolean;
+        backup: null;
+    } | {
+        settingsPath: string;
+        action: "replace" | "add";
+        changed: boolean;
+        backup: string | null;
+    };
+    restartRequired: boolean;
+    instruction: string;
+    planId?: undefined;
+    agentId?: undefined;
+    dataDir?: undefined;
+    schema: string;
+    client: "claude-code" | "claude-desktop" | "codex-cli" | "codex-desktop";
+    configPath: string;
+    backup: string | null;
+}>;

package/runtime/packages/setup/dist/src/clients.js

@@ -0,0 +1,251 @@
+import * as TOML from '@iarna/toml';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, rename, rmdir, stat, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { loadConfig } from './config.js';
+import { sameClientFileIdentity } from './file-identity.js';
+import { protectPrivateFile, preparePrivateReplacement } from './private-file.js';
+export { sameClientFileIdentity } from './file-identity.js';
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+async function selectedClient(c, adapter, clientId) {
+    const client = (await adapter.detectClients(c)).find(item => item.id === clientId);
+    if (!client || !client.installed)
+        throw new Error('client.not-detected');
+    if (!client.configPath || !path.isAbsolute(client.configPath))
+        throw new Error('client.config-path-unverified');
+    return { ...client, configPath: client.configPath };
+}
+async function readClientFile(file) {
+    let handle;
+    try {
+        // O_NOFOLLOW is unavailable on Windows. Inspect the link itself there too,
+        // including dangling links, and bind the opened handle to the checked file.
+        const before = await lstat(file, { bigint: true });
+        if (!before.isFile())
+            throw new Error('client.config-file-invalid');
+        handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        const info = await handle.stat({ bigint: true });
+        const after = await lstat(file, { bigint: true });
+        if (!info.isFile() || !after.isFile() || !sameClientFileIdentity(before, info)
+            || !sameClientFileIdentity(after, info) || !sameClientFileIdentity(before, after) || info.size > 4n * 1024n * 1024n
+            || (process.getuid && info.uid !== BigInt(process.getuid())))
+            throw new Error('client.config-file-invalid');
+        return { text: await handle.readFile('utf8'), existed: true };
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return { text: '', existed: false };
+        throw e;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+function clientDocument(client, text) {
+    const parse = (value) => {
+        try {
+            const result = value.trim() ? client.format === 'json' ? JSON.parse(value) : TOML.parse(value) : {};
+            if (!object(result))
+                throw new Error();
+            return result;
+        }
+        catch {
+            throw new Error('client.config-parse-failed');
+        }
+    };
+    const original = parse(text), key = client.format === 'json' ? 'mcpServers' : 'mcp_servers';
+    if (original[key] !== undefined && !object(original[key]))
+        throw new Error('client.mcp-table-invalid');
+    return { original, key, parse };
+}
+// Claude Code reads hooks from settings.json next to its config directory, not from ~/.claude.json.
+const claudeSettingsPath = (configPath) => path.join(path.dirname(configPath), '.claude', 'settings.json');
+// Forward slashes read the same in the bash and cmd that run hook commands; node accepts them.
+const hookPath = (value) => `"${value.replaceAll('\\', '/')}"`;
+// Eight hours after each turn instead of the drain's 20-minute default: a message that arrives
+// during a working day still wakes the session (docs/wake-native.md, known limitation).
+const WAKE_WINDOW_SECONDS = 28800;
+/** The node wake drain (docs/wake-native.md): polls the store after each turn and wakes the session. */
+function desiredWakeHook(c) {
+    return { type: 'command', asyncRewake: true,
+        command: `${hookPath(c.nodePath)} --no-warnings ${hookPath(path.join(c.repoRoot, 'scripts', 'wake-drain-claude.mjs'))} --db ${hookPath(c.storePath)} --max-seconds ${WAKE_WINDOW_SECONDS}` };
+}
+const isMurmurWakeHook = (hook) => object(hook) && typeof hook.command === 'string' && hook.command.includes('wake-drain-claude');
+/** Plan the Stop hook edit; only Murmur's own wake hook is ever added, kept or replaced. */
+function planWakeHook(c, text) {
+    let settings;
+    try {
+        settings = text.trim() ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new Error('client.settings-parse-failed');
+    }
+    if (!object(settings) || (settings.hooks !== undefined && !object(settings.hooks))
+        || (settings.hooks?.Stop !== undefined && (!Array.isArray(settings.hooks.Stop)
+            || !settings.hooks.Stop.every((group) => object(group) && Array.isArray(group.hooks)))))
+        throw new Error('client.hooks-invalid');
+    const entry = desiredWakeHook(c), groups = settings.hooks?.Stop ?? [];
+    const ours = groups.flatMap(group => group.hooks.filter(isMurmurWakeHook));
+    if (ours.length === 1 && isDeepStrictEqual(ours[0], entry))
+        return { action: 'unchanged', next: settings };
+    const kept = groups.map(group => ({ ...group, hooks: group.hooks.filter((hook) => !isMurmurWakeHook(hook)) })).filter(group => group.hooks.length);
+    const next = { ...settings, hooks: { ...settings.hooks, Stop: [...kept, { hooks: [entry] }] } };
+    return { action: ours.length ? 'replace' : 'add', next };
+}
+/** Write settings.json the same guarded way as the MCP entry: lock, private backup, atomic rename. */
+async function configureWakeHook(c, file, before) {
+    await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    const lock = `${file}.murmur-lock`;
+    await mkdir(lock, { mode: 0o700 });
+    try {
+        const current = await readClientFile(file);
+        if (!isDeepStrictEqual(current, before))
+            throw new Error('client.plan-stale');
+        const { action, next } = planWakeHook(c, current.text);
+        if (action === 'unchanged')
+            return { settingsPath: file, action, changed: false, backup: null };
+        const serialized = JSON.stringify(next, null, 2) + '\n';
+        const backup = current.existed ? `${file}.murmur-backup-${randomUUID()}` : null;
+        if (backup) {
+            const out = await open(backup, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+            try {
+                await protectPrivateFile(backup, out);
+                await out.writeFile(current.text);
+                await out.sync();
+            }
+            finally {
+                await out.close();
+            }
+        }
+        const temporary = `${file}.murmur-${randomUUID()}.tmp`;
+        try {
+            const out = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+            try {
+                await preparePrivateReplacement(temporary, out, file);
+                await out.writeFile(serialized);
+                await out.sync();
+            }
+            finally {
+                await out.close();
+            }
+            if (!isDeepStrictEqual(await readClientFile(file), current))
+                throw new Error('client.plan-stale');
+            await rename(temporary, file);
+        }
+        finally {
+            await unlink(temporary).catch(() => { });
+        }
+        return { settingsPath: file, action, changed: true, backup };
+    }
+    finally {
+        await rmdir(lock);
+    }
+}
+function desiredEntry(c) {
+    return { command: c.nodePath, args: [path.join(c.repoRoot, 'packages', 'mcp-server', 'dist', 'src', 'index.js')],
+        env: { DATA_DIR: c.dataDir, MURMUR_STORE_PATH: c.storePath } };
+}
+async function planFor(c, client, current, settings) {
+    const config = await loadConfig(c), { original, key } = clientDocument(client, current.text);
+    const entry = desiredEntry(c), previous = original[key]?.murmur;
+    const action = isDeepStrictEqual(previous, entry) ? 'unchanged' : previous === undefined ? 'add' : 'replace';
+    const wakeHook = settings && { settingsPath: claudeSettingsPath(client.configPath), action: planWakeHook(c, settings.text).action };
+    // Bind confirmation to the target, exact bytes and selected identity/runtime.
+    // No existing commands, environment values, auth or config contents leave the engine.
+    const planId = createHash('sha256').update(JSON.stringify([client.id, client.configPath, current,
+        config.agentId, config.keys.signing.publicKey, config.keys.encryption.publicKey, entry, settings ?? null])).digest('hex');
+    return { schema: 'murmur.client-plan/1', client: client.id, configPath: client.configPath,
+        agentId: config.agentId, dataDir: c.dataDir, action, planId, configExisted: current.existed, restartRequired: true, ...(wakeHook ? { wakeHook } : {}) };
+}
+/** Read-only preview: even a missing parent directory is not created. */
+export async function previewClientConfiguration(c, adapter, clientId) {
+    const client = await selectedClient(c, adapter, clientId);
+    const settings = client.id === 'claude-code' ? await readClientFile(claudeSettingsPath(client.configPath)) : undefined;
+    return planFor(c, client, await readClientFile(client.configPath), settings);
+}
+/**
+ * Patch only the selected Murmur entry; never execute a client or touch its auth. For Claude Code
+ * also install the Stop wake hook, so a delivered message wakes the session without a human turn.
+ */
+export async function configureClient(c, adapter, clientId, replace = false, expectedPlan) {
+    const client = await selectedClient(c, adapter, clientId);
+    if (expectedPlan !== undefined && !/^[a-f0-9]{64}$/.test(expectedPlan))
+        throw new Error('client.plan-invalid');
+    if (client.id !== 'claude-code')
+        return configureMcpEntry(c, client, replace, expectedPlan);
+    const settingsFile = claudeSettingsPath(client.configPath), settings = await readClientFile(settingsFile);
+    // A hook must never point at a file this runtime does not ship (an older or partial bundle).
+    const drain = await stat(path.join(c.repoRoot, 'scripts', 'wake-drain-claude.mjs')).catch(() => null);
+    if (!drain?.isFile())
+        throw new Error('client.wake-drain-missing');
+    // Refuse a foreign variant of the hook before anything is written, as for the MCP entry.
+    if (planWakeHook(c, settings.text).action === 'replace' && !replace)
+        throw new Error('client.wake-hook-conflict');
+    const result = await configureMcpEntry(c, client, replace, expectedPlan, settings);
+    const wakeHook = await configureWakeHook(c, settingsFile, settings);
+    return { ...result, changed: result.changed || wakeHook.changed, wakeHook };
+}
+async function configureMcpEntry(c, client, replace, expectedPlan, settings) {
+    const clientId = client.id, file = client.configPath;
+    await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    const lock = `${file}.murmur-lock`;
+    await mkdir(lock, { mode: 0o700 });
+    try {
+        const current = await readClientFile(file), { text, existed } = current;
+        const plan = expectedPlan === undefined ? undefined : await planFor(c, client, current, settings);
+        if (plan && plan.planId !== expectedPlan)
+            throw new Error('client.plan-stale');
+        const { original, key, parse } = clientDocument(client, text), entry = desiredEntry(c);
+        const confirmed = plan ? { planId: plan.planId, agentId: plan.agentId, dataDir: plan.dataDir } : {};
+        const previous = original[key]?.murmur;
+        if (isDeepStrictEqual(previous, entry))
+            return { schema: 'murmur.client/1', client: clientId, configPath: file, changed: false, backup: null, restartRequired: true, ...confirmed };
+        if (previous !== undefined && !replace)
+            throw new Error('client.murmur-entry-conflict');
+        const next = { ...original, [key]: { ...original[key], murmur: entry } };
+        const serialized = client.format === 'json' ? JSON.stringify(next, null, 2) + '\n' : TOML.stringify(next);
+        if (!isDeepStrictEqual(parse(serialized), next))
+            throw new Error('client.config-roundtrip-failed');
+        const backup = existed ? `${file}.murmur-backup-${randomUUID()}` : null;
+        if (backup) {
+            const out = await open(backup, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+            try {
+                await protectPrivateFile(backup, out);
+                await out.writeFile(text);
+                await out.sync();
+            }
+            finally {
+                await out.close();
+            }
+        }
+        const temporary = `${file}.murmur-${randomUUID()}.tmp`;
+        try {
+            const out = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+            try {
+                await preparePrivateReplacement(temporary, out, file);
+                await out.writeFile(serialized);
+                await out.sync();
+            }
+            finally {
+                await out.close();
+            }
+            // A client can save its config while the confirmation window is open or
+            // while we prepare the backup. Refuse a changed target instead of losing it.
+            if (!isDeepStrictEqual(await readClientFile(file), current))
+                throw new Error('client.plan-stale');
+            if (plan && (await planFor(c, client, current, settings)).planId !== plan.planId)
+                throw new Error('client.plan-stale');
+            await rename(temporary, file);
+        }
+        finally {
+            await unlink(temporary).catch(() => { });
+        }
+        return { schema: 'murmur.client/1', client: clientId, configPath: file, changed: true, backup, ...confirmed,
+            restartRequired: true, instruction: 'Reload the selected client to activate the Murmur MCP entry.' };
+    }
+    finally {
+        await rmdir(lock);
+    }
+}

package/runtime/packages/setup/dist/src/commands.d.ts

@@ -0,0 +1,35 @@
+import type { PlatformAdapter, ServiceContext } from './types.js';
+/** Observe the configured directory only; this does not prove a live daemon's log destination. */
+export declare function readLogPath(context: ServiceContext): Promise<{
+    schema: string;
+    agentId: string;
+    dataDir: string;
+    serviceName: string;
+    logDir: string;
+    source: string;
+}>;
+/** Explicit local configuration mutation, serialized against other setup writers. */
+export declare function setWakeEnabled(context: ServiceContext, adapter: PlatformAdapter, enabled: boolean, apply?: boolean): Promise<{
+    schema: string;
+    configuredEnabled: boolean;
+    effectiveEnabled: any;
+    restartRequired: boolean;
+    backup: string | null;
+    applyError: string | null;
+}>;
+/** Explicit read action only; merely displaying status never consumes unread state. */
+export declare function markInboxRead(context: ServiceContext): Promise<{
+    schema: string;
+    agentId: string;
+    rowid: number;
+}>;
+/** Return durable inbound rows without advancing the independent read cursor. */
+export declare function readInbox(context: ServiceContext, limit?: number): Promise<{
+    schema: string;
+    agentId: string;
+    readCursor: number | null;
+    unread: number | null;
+    messages: {
+        unread: boolean | null;
+    }[];
+}>;