@murmurv2/cli 2.11.0 → 2.12.0

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

@@ -2,12 +2,17 @@ import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
 import { access, mkdir, realpath, rmdir, stat } from 'node:fs/promises';
-import { loadConfig, readJson } from './config.js';
+import { loadConfig, readJson, safeError } from './config.js';
 import { readStatus } from './status.js';
+import { assistantRead, wakeColumns } from './message-status.js';
 import { writeState } from './state.js';
 /** Observe the configured directory only; this does not prove a live daemon's log destination. */
-export async function readLogPath(context) {
+export async function readLogPath(context, adapter) {
     const config = await loadConfig(context);
+    if (adapter?.logDirectory) {
+        return { schema: 'murmur.logs/1', agentId: config.agentId, dataDir: context.dataDir,
+            serviceName: context.serviceName, logDir: await adapter.logDirectory(context), source: 'native' };
+    }
     try {
         const dataDir = await realpath(context.dataDir);
         const logDir = await realpath(context.logDir);
@@ -53,8 +58,12 @@ export async function setWakeEnabled(context, adapter, enabled, apply = false) {
     let applyError = null;
     if (apply) {
         try {
-            await adapter.stop(context);
-            await adapter.start(context);
+            if ((await readStatus({ context, adapter })).service.state === 'running-unmanaged')
+                applyError = 'service.running-unmanaged';
+            else {
+                await adapter.stop(context);
+                await adapter.start(context);
+            }
         }
         catch {
             applyError = 'wake.service-apply-failed';
@@ -102,12 +111,14 @@ export async function readInbox(context, limit = 20) {
         const unread = cursor === null ? null : Number(db.prepare("SELECT COUNT(*) AS n FROM local_messages WHERE direction='inbound' AND rowid>?").get(cursor).n);
         const rows = db.prepare(`SELECT rowid,conversation_id AS conversationId,msg_id AS msgId,sender,text,
       created_at AS createdAt,transport,channel_id AS channelId,sender_member_id AS senderMemberId,
-      addressee_member_id AS addresseeMemberId FROM local_messages WHERE direction='inbound'
+      addressee_member_id AS addresseeMemberId,${wakeColumns(db)} FROM local_messages WHERE direction='inbound'
       ORDER BY created_at DESC,rowid DESC LIMIT ?`).all(limit);
         db.exec('COMMIT');
         return { schema: 'murmur.inbox/1', agentId: config.agentId, readCursor: cursor,
             unread,
-            messages: rows.map(({ rowid, ...row }) => ({ ...row, unread: cursor === null ? null : Number(rowid) > cursor })) };
+            messages: rows.map(({ rowid, ...row }) => ({ ...row, assistantRead: assistantRead(row.wake_status),
+                wake_error: row.wake_error ? safeError(row.wake_error) : null,
+                unread: cursor === null ? null : Number(rowid) > cursor })) };
     }
     finally {
         db.close();

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

@@ -47,3 +47,5 @@ export declare function validateConfig(input: unknown): AgentConfig;
 export declare function readJson(file: string): Promise<any>;
 export declare function loadConfig(context: ServiceContext): Promise<AgentConfig>;
 export declare function safeError(error: unknown): string;
+/** CLI presentation only; JSON consumers retain the stable, secret-free codes. */
+export declare function humanError(error: unknown): string;

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

@@ -68,3 +68,64 @@ export function safeError(error) {
     }
     return "operation-failed";
 }
+/** CLI presentation only; JSON consumers retain the stable, secret-free codes. */
+export function humanError(error) {
+    const code = safeError(error);
+    if (code === 'onboarding.invite-public-server-required') {
+        return 'This Invitation needs a public Server address. Ask for its public address and pass it with --broker.';
+    }
+    if (code === 'onboarding.invite-server-address-invalid') {
+        return 'Enter a valid public Server address with --broker, such as nats://server.example.com:4222. Do not include an access key in the address.';
+    }
+    const messages = {
+        'accepted-turn-unobservable': 'The Assistant accepted this message, but its outcome cannot be checked. Inspect its session before dismissing the alert; do not send the instruction again.',
+        'wake.selection-invalid': 'Choose a message and the expected Identity, then try again.',
+        'wake.identity-changed': 'The selected Identity has changed. Check its name before dismissing this alert.',
+        'wake.dismiss-not-eligible': 'This alert cannot be dismissed here. Check the message status and the selected Identity.',
+        'wake.store-invalid': 'Choose the original message history owned by your account, then try again.',
+        'onboarding.input-required': 'Provide the Invitation or Reply using standard input or choose its saved file.',
+        'onboarding.input-conflict': 'Choose one source for the Invitation or Reply: standard input or a saved file.',
+        'onboarding.stdin-required': 'Send the Invitation or Reply through standard input, or choose its saved file.',
+        'onboarding.input-too-large': 'This Invitation or Reply is too long. Ask your colleague to send a new one.',
+        'onboarding.file-invalid': 'This file cannot be used. Choose the saved Invitation or Reply your colleague sent.',
+        'onboarding.invalid-blob': 'This Invitation or Reply is incomplete or damaged. Copy the whole line your colleague sent.',
+        'onboarding.invalid-peer': 'This is not the expected Invitation or Reply. Ask your colleague to send the correct one.',
+        'onboarding.invalid-peer-key': 'The Contact details are damaged. Ask your colleague for a new Invitation or Reply.',
+        'onboarding.invalid-broker': 'The Invitation has invalid Server details. Ask your colleague for a new Invitation.',
+        'onboarding.self-peer': 'This is your own Identity. Ask your colleague to send their Reply.',
+        'onboarding.peer-key-conflict': 'This Contact has different Identity details. Verify the change with your colleague before replacing the Contact.',
+        'onboarding.existing-profile-conflict': 'Another Identity already uses this folder. Choose that Identity or an empty folder.',
+        'onboarding.file-must-be-absolute': 'Choose the input file using its full path.',
+        'onboarding.output-must-be-absolute': 'Choose the destination file using its full path.',
+        'onboarding.output-parent-required': 'Choose an existing folder to save the Invitation or Reply.',
+        'onboarding.output-inside-profile': 'Choose a destination outside the folder containing your Identity settings.',
+        'onboarding.token-file-invalid': 'The Server access key must be one line. Ask for the correct key and save it again.',
+        'onboarding.private-acl-failed': 'The file could not be protected. Choose a private folder you can write to and try again.',
+        'onboarding.user-sid-unavailable': 'Your account could not be verified. Sign in again and retry.',
+        'onboarding.poison-reset-failed': 'The Contact was saved, but waiting messages could not be prepared. Check the connection and retry.',
+        'config.missing': 'Set up your Identity or choose its existing folder, then try again.',
+        'config.identity-invalid': 'Choose an Identity name using letters, numbers, hyphens or underscores.',
+        'config.broker-url-invalid': 'Enter a valid Server address supplied by your colleague and try again.',
+        'service.running-unmanaged': 'This Service is running outside this app. Manage it where it was started.',
+        'service.previous-installation': 'A Service from a previous Murmur version uses this name. Replace it with: service install --replace-previous.',
+        'service.foreign-image': 'Another program already uses this Service name; Murmur will not change or remove it.',
+        'cli.unknown-command': 'This command is not available. Run with --help to choose an action.',
+        'cli.unknown-option': 'This option is not available. Run with --help to check the command.',
+        'cli.invalid-arguments': 'The command is incomplete. Run with --help to check the required options.',
+    };
+    if (Object.hasOwn(messages, code))
+        return messages[code];
+    if (/^onboarding\.(invite|reply|token)-file-not-found$/.test(code))
+        return 'The selected file was not found. Choose the saved Invitation, Reply or Server access key again.';
+    if (/^onboarding\.(invite|reply|token)-file-access-denied$/.test(code))
+        return 'The selected file cannot be opened. Choose a file your account can read.';
+    if (code.startsWith('cli.required-option:'))
+        return 'A required option is missing. Run with --help to complete the command.';
+    if (code.startsWith('system.EEXIST'))
+        return 'The destination already exists or another setup is in progress. Choose a new destination or wait for setup to finish.';
+    if (/^system\.(EACCES|EPERM)/.test(code))
+        return 'Access was denied. Choose a folder your account can read and write.';
+    if (code === 'database is locked')
+        return 'Your messages are busy with another action. Wait a moment and try again.';
+    return 'This action could not be completed. Check your settings and use --json to share diagnostics with your support contact.';
+}

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

@@ -17,6 +17,18 @@ export declare function runDoctor({ context, adapter, peer, timeoutMs }: DoctorO
     schema: string;
     generatedAt: string;
     agentId: string | null;
+    peerCheck: {
+        peerId: string;
+        state: "connected" | "failed" | "not-checked";
+        lastExchangeAt: string | null;
+        requestMsgId: string | null;
+        replyMsgId: string | null;
+        reason: string | null;
+    } | null;
+    wakeFault: {
+        reason: string;
+        fixHint: string;
+    } | null;
     stages: Record<string, unknown>[];
     summary: {
         worst: string;

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

@@ -88,6 +88,7 @@ export async function probeRoundtrip(c, config, peerId, connection, timeoutMs) {
 const failureHints = (serviceName) => ({
     'config.missing': 'No profile here yet: run murmur join --data-dir <this profile> --agent-id <your-agent-id> --invite-file <invite file> --reply-out <new reply file>',
     'daemon.not-running': `Install or start the service: murmur service install --data-dir <this profile> --service-name ${serviceName} (or service start with the same options if installed; on Windows from an administrator terminal)`,
+    'accepted-turn-unobservable': 'Inspect the Assistant session. After reviewing the unknown outcome, use murmur wake dismiss --data-dir <this profile> --msg-id <message-id> --expected-agent <your-identity> to acknowledge it without running it again.',
 });
 export async function runDoctor({ context, adapter, peer, timeoutMs = 10000 }) {
     if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 60000)
@@ -95,6 +96,8 @@ export async function runDoctor({ context, adapter, peer, timeoutMs = 10000 }) {
     const generatedAt = new Date().toISOString(), stages = [];
     let config = null, connection;
     let snapshot;
+    let peerCheck = peer
+        ? { peerId: peer, state: 'not-checked', lastExchangeAt: null, requestMsgId: null, replyMsgId: null, reason: null } : null;
     let failedStage = null, worst = 'ok';
     const stage = async (id, title, fn) => {
         const start = Date.now();
@@ -120,7 +123,7 @@ export async function runDoctor({ context, adapter, peer, timeoutMs = 10000 }) {
         await stage('config', 'Configuration', async () => { config = await loadConfig(context); return { detail: 'Identity, keys and peer configuration validated' }; });
         await stage('daemon', 'Daemon and store', async () => {
             snapshot = await readStatus({ context, adapter });
-            if (snapshot.service.state !== 'running')
+            if (!['running', 'running-unmanaged'].includes(snapshot.service.state))
                 throw new Error('daemon.not-running');
             if (!snapshot.service.observedStorePath || await realpath(snapshot.service.observedStorePath) !== await realpath(context.storePath))
                 throw new Error('daemon.store-unverified');
@@ -149,10 +152,14 @@ export async function runDoctor({ context, adapter, peer, timeoutMs = 10000 }) {
             if (!peer)
                 return { state: 'warn', reason: 'roundtrip.peer-required', detail: 'No diagnostic peer selected; no message sent', fixHint: 'Run murmur doctor --peer <configured-agent-id> --json' };
             const proof = await probeRoundtrip(context, config, peer, connection, timeoutMs);
+            peerCheck = { peerId: peer, state: 'connected', lastExchangeAt: proof.verifiedAt,
+                requestMsgId: proof.msgId, replyMsgId: proof.replyMsgId, reason: null };
             return { detail: `Authenticated reply persisted from ${proof.peerId}` };
         });
         await stage('wake', 'Wake mode and responder', async () => {
             const s = await readStatus({ context, adapter });
+            if (s.wake.faults.lastFault === 'accepted-turn-unobservable')
+                throw new Error('accepted-turn-unobservable');
             if (s.wake.effective.enabled === null)
                 return { state: 'warn', reason: 'wake.unmeasured', detail: 'No fresh runtime evidence' };
             if (s.wake.effective.needsRestart)
@@ -170,5 +177,15 @@ export async function runDoctor({ context, adapter, peer, timeoutMs = 10000 }) {
     finally {
         await connection?.close();
     }
-    return { schema: 'murmur.doctor/1', generatedAt, agentId: config?.agentId ?? null, stages, summary: { worst, failedStage } };
+    if (peerCheck && peerCheck.state !== 'connected') {
+        peerCheck.state = 'failed';
+        peerCheck.reason = String(stages.find(s => s.state === 'fail')?.reason ?? 'roundtrip.not-checked');
+    }
+    // A local accepted-outcome fault is useful even when an earlier network stage
+    // blocked the wake probe. This read sends no message and changes no state.
+    const local = await readStatus({ context, adapter });
+    const wakeFault = local.wake.faults.lastFault === 'accepted-turn-unobservable'
+        ? { reason: 'accepted-turn-unobservable', fixHint: failureHints(context.serviceName)['accepted-turn-unobservable'] } : null;
+    return { schema: 'murmur.doctor/1', generatedAt, agentId: config?.agentId ?? null,
+        peerCheck, wakeFault, stages, summary: { worst, failedStage } };
 }

package/runtime/packages/setup/dist/src/invitation-server.d.ts

@@ -0,0 +1,2 @@
+/** Address policy only: Invitation creation never connects or claims reachability. */
+export declare function invitationServerAddress(value: string): string;

package/runtime/packages/setup/dist/src/invitation-server.js

@@ -0,0 +1,45 @@
+import { BlockList, isIP } from 'node:net';
+const nonPublic = new BlockList();
+for (const [network, prefix] of [
+    ['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8],
+    ['169.254.0.0', 16], ['172.16.0.0', 12], ['192.0.0.0', 24], ['192.0.2.0', 24],
+    ['192.168.0.0', 16], ['198.18.0.0', 15], ['198.51.100.0', 24], ['203.0.113.0', 24],
+    ['224.0.0.0', 4], ['240.0.0.0', 4],
+])
+    nonPublic.addSubnet(network, prefix, 'ipv4');
+for (const [network, prefix] of [
+    ['::', 96], ['64:ff9b::', 96], ['2001:db8::', 32], ['fc00::', 7], ['fe80::', 10], ['ff00::', 8],
+])
+    nonPublic.addSubnet(network, prefix, 'ipv6');
+const privateSuffixes = ['local', 'localhost', 'localdomain', 'ts.net', 'internal', 'home.arpa', 'lan'];
+/** Address policy only: Invitation creation never connects or claims reachability. */
+export function invitationServerAddress(value) {
+    let host;
+    try {
+        // URL parsing otherwise silently removes whitespace and controls. Never let the
+        // checked address and the value carried in the Invitation disagree that way.
+        if (/[\s\x00-\x1f\x7f\\]/u.test(value))
+            throw new Error();
+        const url = new URL(value);
+        if (!['nats:', 'tls:'].includes(url.protocol) || !url.host || url.username || url.password
+            || url.search || url.hash || !['', '/'].includes(url.pathname) || url.port === '0')
+            throw new Error();
+        // nats/tls are opaque-host URL schemes. The standard HTTP host parser also
+        // recognizes numeric, short, hex and octal IPv4 spellings (127.1, 0x7f000001),
+        // percent-encoded hostnames, case and IPv4-mapped IPv6, without a DNS lookup.
+        host = new URL(`http://${url.host}`).hostname.replace(/^\[|\]$/g, '').replace(/\.$/, '').toLowerCase();
+        if (!isIP(host) && (host.length > 253 || !host.split('.').every(label => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label))))
+            throw new Error();
+    }
+    catch {
+        throw new Error('onboarding.invite-server-address-invalid');
+    }
+    const family = isIP(host);
+    // BlockList checks IPv4 rules for mapped IPv6 too; ::ffff:192.168.1.1 cannot
+    // turn a private IPv4 destination into a public Invitation address.
+    const privateAddress = family ? nonPublic.check(host, family === 4 ? 'ipv4' : 'ipv6')
+        : !host.includes('.') || privateSuffixes.some(suffix => host === suffix || host.endsWith(`.${suffix}`));
+    if (privateAddress)
+        throw new Error('onboarding.invite-public-server-required');
+    return value;
+}

package/runtime/packages/setup/dist/src/message-status.d.ts

@@ -0,0 +1,4 @@
+import type { DatabaseSync } from 'node:sqlite';
+/** Older stores remain readable without a migration or an invented wake result. */
+export declare function wakeColumns(db: DatabaseSync): string;
+export declare function assistantRead(wakeStatus: unknown): boolean | null;

package/runtime/packages/setup/dist/src/message-status.js

@@ -0,0 +1,10 @@
+/** Older stores remain readable without a migration or an invented wake result. */
+export function wakeColumns(db) {
+    const columns = new Set(db.prepare('PRAGMA table_info(local_messages)').all().map(row => row.name));
+    return ['wake_status', 'wake_updated_at', 'wake_error'].map(name => columns.has(name) ? name : `NULL AS ${name}`).join(',');
+}
+export function assistantRead(wakeStatus) {
+    if (wakeStatus === 'handled')
+        return true;
+    return ['pending', 'inflight', 'failed', 'dlq', 'stored-only', 'muted'].includes(String(wakeStatus)) ? false : null;
+}

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

@@ -10,27 +10,36 @@ export declare function initialize(c: ServiceContext, options: {
     serviceName: string;
     existing: boolean;
 }>;
-export declare function invite(c: ServiceContext, outFile: string): Promise<{
+export declare function invite(c: ServiceContext, outFile?: string, options?: {
+    brokerUrl?: string;
+}): Promise<{
     schema: string;
-    file: string;
+    file: string | null;
+    invitation: string;
     containsBrokerCredential: boolean;
     instruction: string;
 }>;
 export declare function join(c: ServiceContext, options: {
     agentId: string;
-    inviteFile: string;
-    replyOut: string;
+    inviteFile?: string;
+    invitation?: string;
+    replyOut?: string;
 }): Promise<{
     schema: string;
     agentId: string;
     peerId: any;
     paired: null;
-    replyFile: string;
+    replyFile: string | null;
+    reply: string;
     backup: null;
     restartRequired: boolean;
+    contactsReload: {
+        mechanism: string;
+        state: string;
+    };
     serviceName: string;
 }>;
-export declare function importPeer(c: ServiceContext, replyFile: string): Promise<{
+export declare function importPeer(c: ServiceContext, replyFile?: string, reply?: string): Promise<{
     schema: string;
     peerId: any;
     paired: null;
@@ -43,4 +52,8 @@ export declare function importPeer(c: ServiceContext, replyFile: string): Promis
         reason: string;
     };
     restartRequired: boolean;
+    contactsReload: {
+        mechanism: string;
+        state: string;
+    };
 }>;

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

@@ -10,6 +10,7 @@ import { loadConfig, validateConfig, validAgentId } from './config.js';
 import { writeState } from './state.js';
 import { refuseVirtualizedAppData } from './appdata.js';
 import { protectPrivateFile } from './private-file.js';
+import { invitationServerAddress } from './invitation-server.js';
 async function privateText(file, role) {
     if (!path.isAbsolute(file))
         throw new Error('onboarding.file-must-be-absolute');
@@ -108,7 +109,13 @@ async function restrictToCurrentUser(target, directory) {
     await execFileAsync(system32('icacls.exe'), [target, '/inheritance:r', '/grant:r', `*${sid}:${inherit}(F)`, `*S-1-5-18:${inherit}(F)`], { windowsHide: true })
         .catch(() => { throw new Error('onboarding.private-acl-failed'); });
 }
-async function outputBlob(file, value, prefix, beforeWrite) {
+const encodeBlob = (value) => {
+    const text = 'MURMUR:' + Buffer.from(JSON.stringify(value)).toString('base64url');
+    if (Buffer.byteLength(text + '\n') > 16384)
+        throw new Error('onboarding.input-too-large');
+    return text;
+};
+async function outputBlob(file, text, beforeWrite) {
     if (!path.isAbsolute(file))
         throw new Error('onboarding.output-must-be-absolute');
     const handle = await open(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600);
@@ -117,7 +124,7 @@ async function outputBlob(file, value, prefix, beforeWrite) {
         // Protect the still-empty output before writing the invitation credential.
         await protectPrivateFile(file, handle);
         await beforeWrite?.();
-        await handle.writeFile(prefix + Buffer.from(JSON.stringify(value)).toString('base64') + '\n');
+        await handle.writeFile(text + '\n');
         await handle.sync();
         written = true;
     }
@@ -185,12 +192,20 @@ async function saveChanged(c, previous, next) {
 }
 const publicPeer = (c) => ({ agentId: c.agentId, subject: c.subject,
     encryption: { publicKey: c.keys.encryption.publicKey }, signing: { publicKey: c.keys.signing.publicKey } });
-async function readBlob(file, prefix, type) {
-    const text = await privateText(file, `${type}-file`);
+async function readBlob(input, type) {
+    if ((input.file === undefined) === (input.text === undefined))
+        throw new Error('onboarding.input-required');
+    const text = (input.file !== undefined ? await privateText(input.file, `${type}-file`) : input.text).trim();
+    if (Buffer.byteLength(text, 'utf8') > 16384)
+        throw new Error('onboarding.input-too-large');
+    // Accept existing private files as well as the shared, type-tagged string format.
+    const prefix = type === 'reply' && text.startsWith('MURMUR-REPLY:') ? 'MURMUR-REPLY:' : 'MURMUR:';
     if (!text.startsWith(prefix))
         throw new Error('onboarding.invalid-blob');
     const encoded = text.slice(prefix.length);
-    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(encoded) || Buffer.from(encoded, 'base64').toString('base64') !== encoded)
+    const canonical = /^[A-Za-z0-9_-]+$/.test(encoded) && Buffer.from(encoded, 'base64url').toString('base64url') === encoded;
+    const legacy = /^[A-Za-z0-9+/]+={0,2}$/.test(encoded) && Buffer.from(encoded, 'base64').toString('base64') === encoded;
+    if (!canonical && !legacy)
         throw new Error('onboarding.invalid-blob');
     let value;
     try {
@@ -236,21 +251,24 @@ export async function initialize(c, options) {
         return { schema: 'murmur.init/1', agentId: config.agentId, dataDir: c.dataDir, serviceName: c.serviceName, existing: false };
     });
 }
-export async function invite(c, outFile) {
-    await validateOutput(c, outFile);
+export async function invite(c, outFile, options = {}) {
+    if (outFile !== undefined)
+        await validateOutput(c, outFile);
     const config = await loadConfig(c);
-    await outputBlob(outFile, { v: 1, type: 'invite', ...publicPeer(config), natsUrl: config.natsUrl, ...(config.natsToken ? { natsToken: config.natsToken } : {}) }, 'MURMUR:');
-    // The warning names what is actually inside. A person weighs "password" and "identity"
-    // differently, and the same sentence for both teaches them to ignore it.
+    const server = invitationServerAddress(options.brokerUrl ?? config.natsUrl);
+    const invitation = encodeBlob({ v: 1, type: 'invite', ...publicPeer(config), natsUrl: server, ...(config.natsToken ? { natsToken: config.natsToken } : {}) });
+    if (outFile !== undefined)
+        await outputBlob(outFile, invitation);
     const containsBrokerCredential = !!config.natsToken;
-    return { schema: 'murmur.invite/1', file: outFile, containsBrokerCredential,
+    return { schema: 'murmur.invite/1', file: outFile ?? null, invitation, containsBrokerCredential,
         instruction: containsBrokerCredential
-            ? 'This file carries the broker address and its credential. Treat it like a password: send it only through a channel you would trust with one. Importing it does not prove pairing.'
-            : 'This file carries your identity and the broker address. Send it through a channel you trust. Importing it does not prove pairing.' };
+            ? 'This Invitation contains a Server access key. Send it personally to your colleague. After exchanging the Reply, check the connection.'
+            : 'This Invitation contains your Identity and the Server address. Send it to your colleague. After exchanging the Reply, check the connection.' };
 }
 export async function join(c, options) {
-    await validateOutput(c, options.replyOut);
-    const incoming = await readBlob(options.inviteFile, 'MURMUR:', 'invite');
+    if (options.replyOut !== undefined)
+        await validateOutput(c, options.replyOut);
+    const incoming = await readBlob({ file: options.inviteFile, text: options.invitation }, 'invite');
     // Before anything is created: a profile the service cannot see must not be written at all.
     await refuseVirtualizedAppData(c.dataDir);
     return locked(c, async () => {
@@ -261,10 +279,15 @@ export async function join(c, options) {
         const next = addPeer(config, incoming);
         let backup = null;
         // Reserve the reply path before changing config: an existing output must not half-import a profile.
-        await outputBlob(options.replyOut, { v: 1, type: 'reply', ...publicPeer(next) }, 'MURMUR-REPLY:', async () => {
-            backup = await saveChanged(c, previous, next);
-        });
-        return { schema: 'murmur.join/1', agentId: next.agentId, peerId: incoming.agentId, paired: null, replyFile: options.replyOut, backup, restartRequired: true, serviceName: c.serviceName };
+        const reply = encodeBlob({ v: 1, type: 'reply', ...publicPeer(next) });
+        const save = async () => { backup = await saveChanged(c, previous, next); };
+        if (options.replyOut !== undefined)
+            await outputBlob(options.replyOut, reply, save);
+        else
+            await save();
+        return { schema: 'murmur.join/1', agentId: next.agentId, peerId: incoming.agentId, paired: null,
+            replyFile: options.replyOut ?? null, reply, backup, restartRequired: false,
+            contactsReload: { mechanism: 'config-file', state: 'pending' }, serviceName: c.serviceName };
     });
 }
 async function clearPeerPoison(c, peerId) {
@@ -287,12 +310,13 @@ async function clearPeerPoison(c, peerId) {
         return { cleared: null, reason: 'onboarding.poison-reset-failed' };
     }
 }
-export async function importPeer(c, replyFile) {
-    const incoming = await readBlob(replyFile, 'MURMUR-REPLY:', 'reply');
+export async function importPeer(c, replyFile, reply) {
+    const incoming = await readBlob({ file: replyFile, text: reply }, 'reply');
     return locked(c, async () => {
         const previous = await loadConfig(c), next = addPeer(previous, incoming);
         const backup = await saveChanged(c, previous, next);
         return { schema: 'murmur.peer/1', peerId: incoming.agentId, paired: null, backup,
-            poisonReset: await clearPeerPoison(c, incoming.agentId), restartRequired: true };
+            poisonReset: await clearPeerPoison(c, incoming.agentId), restartRequired: false,
+            contactsReload: { mechanism: 'config-file', state: 'pending' } };
     });
 }

package/runtime/packages/setup/dist/src/outbox-attention.js

@@ -1,33 +1,15 @@
 import { DatabaseSync } from 'node:sqlite';
-import { createHash } from 'node:crypto';
+import { outboxAttentionToken as tokenFor, readOutboxDismissals } from '@murmurv2/core';
 import { mkdir, rmdir } from 'node:fs/promises';
 import path from 'node:path';
-import { loadConfig, readJson, safeError, validAgentId } from './config.js';
+import { loadConfig, safeError, validAgentId } from './config.js';
 import { writeState } from './state.js';
 const stateFile = (c) => path.join(c.dataDir, 'outbox-attention.json');
 const validId = (v) => typeof v === 'string' && /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,150}$/.test(v);
 const validToken = (v) => typeof v === 'string' && /^[a-f0-9]{64}$/.test(v);
 const columns = `msg_id AS msgId,subject,attempts,created_at AS createdAt,updated_at AS failedAt,last_error AS error,version,
   json_extract(envelope_json,'$.recipients[0]') AS peer`;
-const tokenFor = (row) => createHash('sha256').update(JSON.stringify([
-    row.msgId, row.subject, row.attempts, row.createdAt, row.failedAt, row.error, row.version, row.peer,
-])).digest('hex');
-async function saved(c, agentId) {
-    let value;
-    try {
-        value = await readJson(stateFile(c));
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return { schema: 'murmur.outbox-dismissals/1', agentId, records: [] };
-        throw new Error('outbox.dismissals-unreadable');
-    }
-    if (value?.schema !== 'murmur.outbox-dismissals/1' || value.agentId !== agentId || !Array.isArray(value.records)
-        || value.records.length > 1000 || value.records.some((r) => !validId(r?.msgId) || !validToken(r?.token))
-        || new Set(value.records.map((r) => r.msgId)).size !== value.records.length)
-        throw new Error('outbox.dismissals-invalid');
-    return value;
-}
+const saved = (c, agentId) => readOutboxDismissals(stateFile(c), agentId);
 /** Metadata only. A dismissal never changes transport state or implies delivery. */
 export async function readOutboxAttention(c, agentId, db) {
     const state = await saved(c, agentId), ignored = new Map(state.records.map(r => [r.msgId, r.token]));

package/runtime/packages/setup/dist/src/platform/darwin.js

@@ -266,5 +266,11 @@ export function createDarwinAdapter(options = {}) {
             { id: "codex-desktop", installed: await hasApp(["Codex.app", "ChatGPT.app"], "com.openai.codex"), configPath: codexConfig, format: "toml" },
         ];
     }
-    return { manager: "launchd", status, install, start, stop, detectClients };
+    return { manager: "launchd", status, install, start, stop, detectClients,
+        async observeStore(ctx, pid) {
+            validate(ctx);
+            if (!Number.isSafeInteger(pid) || pid <= 0)
+                return null;
+            return observedStore(pid, ctx.storePath);
+        } };
 }

package/runtime/packages/setup/dist/src/platform/linux.js

@@ -1,7 +1,7 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { constants } from "node:fs";
-import { access, mkdir, open, readdir, readlink, realpath, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { access, mkdir, open, readdir, realpath, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { randomUUID } from "node:crypto";
 import path from "node:path";
@@ -76,8 +76,26 @@ export function createLinuxAdapter(options = {}) {
         if (await readOwned(c) !== renderLinuxUnit(c))
             throw new Error("service.profile-mismatch");
     }
+    async function observeStore(c, pid) {
+        check(c);
+        if (!Number.isSafeInteger(pid) || pid <= 0)
+            return null;
+        try {
+            const expected = await realpath(c.storePath), fdDir = path.join(options.procDir ?? "/proc", String(pid), "fd");
+            for (const fd of await readdir(fdDir)) {
+                try {
+                    if (await realpath(path.join(fdDir, fd)) === expected)
+                        return expected;
+                }
+                catch { }
+            }
+        }
+        catch { /* Inaccessible or exited processes are not liveness evidence. */ }
+        return null;
+    }
     return {
         manager: "systemd",
+        observeStore,
         async status(c) {
             check(c);
             const result = { state: "unknown", manager: "systemd", since: null, pid: null,
@@ -98,21 +116,8 @@ export function createLinuxAdapter(options = {}) {
             result.lastExitCode = /^\d+$/.test(values.ExecMainStatus ?? "") ? Number(values.ExecMainStatus) : null;
             const started = Date.parse(values.ActiveEnterTimestamp ?? "");
             result.since = Number.isFinite(started) ? new Date(started).toISOString() : null;
-            if (result.pid) {
-                try {
-                    const expected = await realpath(c.storePath), fdDir = path.join(options.procDir ?? "/proc", String(result.pid), "fd");
-                    for (const fd of await readdir(fdDir)) {
-                        try {
-                            if (await readlink(path.join(fdDir, fd)) === expected) {
-                                result.observedStorePath = expected;
-                                break;
-                            }
-                        }
-                        catch { }
-                    }
-                }
-                catch { /* Inaccessible descriptors mean unverified, not guessed from config. */ }
-            }
+            if (result.pid)
+                result.observedStorePath = await observeStore(c, result.pid);
             return result;
         },
         async install(c) {