gipity 1.0.429 → 1.1.2

package/dist/knowledge.js

@@ -54,7 +54,7 @@ Prefer the cheapest option that works - CLI and sandbox are instant and free, ap
 3. App services - runtime HTTP endpoints your deployed app calls directly at \`https://a.gipity.ai/api/<PROJECT_GUID>/services/*\`. Available: LLM, TTS, image, sound, music, transcribe, video, file upload, realtime, location, push notifications (Gipity Notify - \`gipity add notify\`, send from a function with the injected \`notify()\`; see \`app-notify\`). Load the matching skill (\`app-llm\`, \`app-tts\`, etc.) before writing service code - they have the schemas, auth pattern, and common-mistake guards. For one-off generation during development, prefer \`gipity generate <image|video|speech|sound|music>\` or \`gipity chat\` - direct generation always bills you (the owner), regardless of any service \`billing_mode\` (that setting only governs the deployed app's runtime calls; never flip it just to create assets). \`gipity generate\` saves to a generic file in the current directory by default (e.g. \`./generated.png\`) - pass \`-o <path>\` to write it straight into your source tree so it deploys (e.g. \`gipity generate image "hero banner" -o src/assets/images/hero.png\`) instead of generating at cwd and moving it.
 4. Delegate to Gip (\`gipity chat "<task>"\`) - only when the work genuinely needs agent reasoning or a tool not in the CLI, sandbox, or app services. Required for: Twitter/X search, Gmail, calendar, push notifications, video understanding, audio source isolation, cross-model second opinions, multi-step orchestration. Don't use \`gipity chat\` for anything the sandbox can do - it's slower and burns tokens.
 
-You are the developer. Write files in this directory - the Gipity Claude Code plugin's hooks auto-sync them to Gipity. Don't run \`npm install\`, \`npm start\`, \`node\`, or \`python\` locally; there is no local runtime. Code runs in the Gipity sandbox.
+You are the developer. Write files in this directory - Gipity's editor hooks (installed by \`gipity init\` into Claude Code, Grok, and Codex) auto-sync them to Gipity. Don't run \`npm install\`, \`npm start\`, \`node\`, or \`python\` locally; there is no local runtime. Code runs in the Gipity sandbox.
 
 ## Use first-party services before reaching outside
 
@@ -90,7 +90,7 @@ The full "when to add a template" rule and the definition of done are spelled ou
 
 Build loop: \`gipity add\` → edit files → \`gipity deploy dev --inspect\` → fix any errors → repeat until the definition of done is met. \`deploy --inspect\` deploys and then runs the page-inspect report on the live URL in one command; use a standalone \`gipity page inspect <url>\` only when re-checking without deploying.
 
-\`add\` writes real files to disk - Read a scaffolded file before your first Write/Edit to it, or the call fails \`"File has not been read yet"\`. Don't rewrite from memory of the template.
+\`add\` writes real files to disk - Read a scaffolded file with the Read tool before your first Write/Edit to it, or the call fails \`"File has not been read yet"\` (viewing it with \`cat\`/\`head\` in Bash does not count - the harness only tracks the Read tool). Don't rewrite from memory of the template.
 
 Make your file changes and verify they landed, then run \`gipity deploy dev\` once. \`0 uploaded, N unchanged\` means nothing changed on disk - fix the files, don't re-run deploy or probe the environment.
 
@@ -146,7 +146,7 @@ Every tool call returns its full output with that call. There is no output buffe
 
 This directory is the app root - it holds \`.gipity.json\` (and \`gipity.yaml\` for backends) and is already your cwd, so run app commands here. Don't \`cd\` to a git root (\`git rev-parse --show-toplevel\`): when the app is nested in a larger repo that resolves outside the app.
 
-Write files locally - the Gipity Claude Code plugin's hooks auto-push every save to Gipity and auto-pull remote changes (images, audio from \`gipity chat\`) before each turn. Use \`gipity sync\` if things get out of sync (or if the plugin isn't installed - \`gipity status --repair-hooks\` re-enables it). Deletes are safe - use \`rollback\` with a datetime to undo, or \`file_version_restore\` for individual files.
+Write files locally - Gipity's editor hooks (installed into Claude Code, Grok, and Codex by \`gipity init\`) auto-push every save to Gipity and auto-pull remote changes (images, audio from \`gipity chat\`) before each turn. Use \`gipity sync\` if things get out of sync (or if the hooks aren't installed - \`gipity status --repair-hooks\` re-enables them). Deletes are safe - use \`rollback\` with a datetime to undo, or \`file_version_restore\` for individual files.
 
 To keep local-only material (research clones, scratch data, vendored references) in the project directory without syncing or deploying it, list it in a \`.gipityignore\` at the project root - gitignore-style, one pattern per line, \`#\` comments. Ignored paths are invisible to sync in both directions; anything that already synced before being ignored stays on the server until you delete it.
 

package/dist/prefs.js

@@ -0,0 +1,42 @@
+/**
+ * Machine-level user preferences (~/.gipity/prefs.json) - the `gipity build`
+ * agent picker's memory. Deliberately NOT in a project's .gipity.json:
+ * per-project storage would re-ask the agent question on every new project,
+ * which defeats "hit enter twice".
+ *
+ * Shape:
+ *   { "lastAgent": "claude" }
+ *
+ * The model is never stored: `gipity build` doesn't ask, so the agent's own
+ * default (and its own model memory) stays authoritative unless the user
+ * passes --model, which we forward verbatim.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+const PREFS_PATH = join(homedir(), '.gipity', 'prefs.json');
+export function readPrefs() {
+    if (!existsSync(PREFS_PATH))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(PREFS_PATH, 'utf-8'));
+        return {
+            lastAgent: typeof parsed.lastAgent === 'string' ? parsed.lastAgent : undefined,
+        };
+    }
+    catch {
+        return {}; // unreadable prefs must never block a launch
+    }
+}
+export function writePrefs(update) {
+    try {
+        const current = readPrefs();
+        const next = { ...current, ...update };
+        mkdirSync(join(homedir(), '.gipity'), { recursive: true });
+        writeFileSync(PREFS_PATH, JSON.stringify(next, null, 2) + '\n');
+    }
+    catch {
+        /* best-effort - prefs are a convenience */
+    }
+}
+//# sourceMappingURL=prefs.js.map

package/dist/project-setup.js

@@ -7,7 +7,7 @@
 import { clearConfigCache, saveConfigAt, getApiBaseOverride, DEFAULT_API_BASE } from './config.js';
 import { sync } from './sync.js';
 import { createProgressReporter } from './progress.js';
-import { setupClaudeHooks, setupGitignore, DEFAULT_TOOLS, DEFAULT_SYNC_IGNORE } from './setup.js';
+import { setupProjectTools, DEFAULT_TOOLS, DEFAULT_SYNC_IGNORE } from './setup.js';
 import { substituteDir } from './template-vars.js';
 import { muted } from './colors.js';
 /** Write `.gipity.json` in `dir`, chdir into it so the hook/skill writers
@@ -61,15 +61,7 @@ export async function finalizeLocalProject(opts) {
             throw err;
         // soft mode - swallow; caller can log
     }
-    const tools = opts.tools ?? DEFAULT_TOOLS;
-    // Claude hooks (file-sync + capture) only matter if the Claude primer is
-    // being written. Skipping them for Codex/Gemini/Cursor-only inits avoids
-    // littering `.claude/settings.json` into projects that don't use Claude.
-    if (tools.some(t => t.key === 'claude'))
-        setupClaudeHooks();
-    for (const t of tools)
-        t.setup();
-    setupGitignore();
+    setupProjectTools(opts.tools ?? DEFAULT_TOOLS);
     return { applied };
 }
 //# sourceMappingURL=project-setup.js.map

package/dist/relay/daemon.js

@@ -6,7 +6,7 @@ import { homedir, hostname, platform as osPlatform, loadavg, freemem, totalmem,
 import { join } from 'path';
 import { getApiBaseOverride, DEFAULT_API_BASE } from '../config.js';
 import { getProjectsRoot } from './paths.js';
-import { setupClaudeHooks, setupClaudeMd, setupAgentsMd, setupGitignore, DEFAULT_SYNC_IGNORE } from '../setup.js';
+import { setupProjectTools, DEFAULT_SYNC_IGNORE } from '../setup.js';
 import { getAuth, readAuthFresh, refreshTokenIfNeeded, accessTokenExpired } from '../auth.js';
 import { post } from '../api.js';
 import * as state from './state.js';
@@ -24,7 +24,8 @@ import { SessionPool, PoolFullError } from './session-pool.js';
 import { getConfig } from '../config.js';
 import { getAccountSlug } from '../api.js';
 import { buildFreshWrap, buildResumeWrap, buildProjectContextBlock } from '../prompts.js';
-import { fetchProjectStats } from '../commands/claude.js';
+import { fetchProjectStats } from '../commands/build.js';
+import { getAdapterBySource } from '../agents/index.js';
 // Re-exported so the existing `relay-bridge-abort.test.ts` keeps working.
 // New callers should import from device-http.js directly.
 export const bridgeAbort = bridgeAbortImpl;
@@ -949,6 +950,15 @@ async function handleDispatch(claimed) {
         if (!syncFailed)
             pushSystem(bootstrapped ? 'Project files synced.' : 'Attached files synced.');
     }
+    // Which agent runs this dispatch. Older servers omit remote_type - they
+    // only ever dispatched Claude Code.
+    const adapter = getAdapterBySource(d.remote_type ?? 'claude_code');
+    // Non-Claude agents take the simpler hook-capture dispatch path: no
+    // stream-json ingest, no session pool.
+    if (adapter.key !== 'claude') {
+        await handleNonClaudeDispatch(adapter, d, cwd, queue, pushSystem, flushQueue);
+        return;
+    }
     // Phase 2: if the session pool is enabled, try to run this turn in a
     // long-lived Claude Code session (fast follow-up + clean interrupt). Any
     // failure - pool saturated, SDK error, wrap failure - falls through to the
@@ -958,8 +968,11 @@ async function handleDispatch(claimed) {
         if (handled)
             return;
     }
-    // Build argv for `gipity claude -p …` (or with --resume). No shell - argv
-    // as array so the message string can't be interpreted as shell syntax.
+    // Build argv for `gipity build --agent claude -p …` (or with --resume).
+    // No shell - argv as array so the message string can't be interpreted as
+    // shell syntax. (`build` is the renamed launcher; the flags below pass
+    // through it to the `claude` binary unchanged, exactly as the legacy
+    // `gipity claude -p` spawn did.)
     //
     // `--permission-mode bypassPermissions`: a relay dispatch has no
     // human on the other end to click "Approve" - Claude prompting would
@@ -967,7 +980,7 @@ async function handleDispatch(claimed) {
     // the device and dispatching the message; skipping the interactive
     // prompt is correct (same authority as running `claude -p` in a local
     // terminal yourself).
-    const args = ['claude', '-p', d.message, '--permission-mode', 'bypassPermissions'];
+    const args = ['build', '--agent', 'claude', '-p', d.message, '--permission-mode', 'bypassPermissions'];
     // Relay sessions run in -p mode, where Claude Code's AskUserQuestion tool
     // is unavailable - so without help the model would ask clarifying
     // questions as prose the user just types back. This system-prompt
@@ -984,7 +997,7 @@ async function handleDispatch(claimed) {
     if (d.kind === 'resume' && d.remote_session_id) {
         args.push('--resume', d.remote_session_id);
     }
-    log('debug', 'spawning gipity claude', {
+    log('debug', 'spawning gipity build --agent claude', {
         id: d.short_guid,
         cwd,
         args,
@@ -1123,7 +1136,92 @@ async function handleDispatch(claimed) {
     }
     else {
         log('warn', 'dispatch child exited nonzero', { id: d.short_guid, exitCode, ms });
-        await ack(d.short_guid, 'error', `gipity claude exited with code ${exitCode}${stderrNote}`);
+        await ack(d.short_guid, 'error', `Claude Code exited with code ${exitCode}${stderrNote}`);
+    }
+}
+/**
+ * Dispatch for non-Claude agents (Codex, Grok). Deliberately simpler than
+ * the Claude path: there is no stream-json ingest mapper for these agents -
+ * hook-based session capture (Phase C) owns the transcript. The spawned
+ * `gipity build --agent <key> -p …` child gets GIPITY_CONVERSATION_GUID (so
+ * capture posts into the right conversation) and capture is NOT turned off.
+ * The daemon contributes: the "Running <agent>" marker, byte-level progress
+ * heartbeats (spawnGipityClaude's generic plumbing with streamJson:false),
+ * post-run file sync, the tail marker, and the ack. The prompt entry itself
+ * arrives via capture from the agent's own transcript - the daemon doesn't
+ * push one, or it would render twice.
+ */
+async function handleNonClaudeDispatch(adapter, d, cwd, queue, pushSystem, flushQueue) {
+    // `gipity build` translates these into the agent's own argv via the same
+    // adapter (Codex: `exec …`; Grok: `-p … --always-approve`). Raw message -
+    // AGENTS.md carries the Gipity context for these agents; no wrapping.
+    const args = ['build', '--agent', adapter.key, '-p', d.message, '--bypass-approvals'];
+    if (d.model)
+        args.push('--model', d.model);
+    if (d.kind === 'resume' && d.remote_session_id)
+        args.push('--resume', d.remote_session_id);
+    log('debug', `spawning gipity build --agent ${adapter.key}`, {
+        id: d.short_guid, cwd, args, conv: d.conversation_guid,
+        chain: d.kind === 'resume' ? `resume ${d.remote_session_id}` : 'start (fresh session)',
+    });
+    const words = d.message.trim().split(/\s+/).filter(Boolean).length;
+    pushSystem(`Running ${adapter.displayName} - ${words.toLocaleString('en-US')} words`);
+    const t0 = Date.now();
+    let exitCode = 1;
+    let spawnErr = null;
+    let killed = false;
+    let runtimeLimit = false;
+    let stderrTail = '';
+    try {
+        const result = await spawnGipityClaude(args, cwd, d, queue, { streamJson: false });
+        exitCode = result.exitCode;
+        killed = result.killed;
+        runtimeLimit = result.runtimeLimit ?? false;
+        stderrTail = result.stderrTail ?? '';
+    }
+    catch (err) {
+        spawnErr = err?.message || String(err);
+        log('error', 'dispatch spawn failed', { id: d.short_guid, err: spawnErr });
+    }
+    const dur = formatDuration(Date.now() - t0);
+    // Same post-run reconcile as the Claude path: push files the agent wrote
+    // via Bash/scripts back to VFS before the ack (hooks only cover its
+    // native edit tools). Skipped on kill - the replacement dispatch owns the tree.
+    if (!spawnErr && !killed) {
+        try {
+            await spawnSync(cwd, PROJECT_SYNC_TIMEOUT_MS);
+        }
+        catch (err) {
+            log('warn', 'sync after dispatch failed', { id: d.short_guid, err: err?.message });
+        }
+    }
+    const stderrNote = stderrTail ? `: ${stderrTail.slice(0, 300)}` : '';
+    const tail = runtimeLimit
+        ? `stopped after ${dur} (runtime limit)`
+        : killed
+            ? `cancelled (${dur})`
+            : spawnErr
+                ? `failed (${dur}: ${spawnErr})`
+                : exitCode === 0
+                    ? `finished (${dur})`
+                    : `failed (${dur}, exit ${exitCode}${stderrNote})`;
+    pushSystem(`${adapter.displayName} ${tail}`);
+    await flushQueue();
+    if (runtimeLimit) {
+        await ack(d.short_guid, 'error', `${adapter.displayName} stopped after ${dur} (runtime limit)`);
+    }
+    else if (killed) {
+        await ack(d.short_guid, 'cancelled');
+    }
+    else if (spawnErr) {
+        await ack(d.short_guid, 'error', spawnErr);
+    }
+    else if (exitCode === 0) {
+        log('info', 'dispatch done', { id: d.short_guid, agent: adapter.key });
+        await ack(d.short_guid, 'done');
+    }
+    else {
+        await ack(d.short_guid, 'error', `${adapter.displayName} exited with code ${exitCode}${stderrNote}`);
     }
 }
 /**
@@ -1372,10 +1470,7 @@ async function resolveCwdForProject(d) {
     const origCwd = process.cwd();
     try {
         process.chdir(path);
-        setupClaudeHooks();
-        setupClaudeMd();
-        setupAgentsMd();
-        setupGitignore();
+        setupProjectTools();
     }
     finally {
         process.chdir(origCwd);
@@ -1562,6 +1657,11 @@ async function spawnSync(cwd, timeoutMs, onSpawn) {
     });
 }
 export async function spawnGipityClaude(args, cwd, d, queue, meta) {
+    // streamJson (default true) = the Claude path: parse the child's
+    // stream-json stdout into ingest entries and stand hook capture down.
+    // false = non-Claude agents (Codex/Grok): hook capture owns the
+    // transcript; stdout only feeds the byte-level progress heartbeat.
+    const streamJson = meta?.streamJson !== false;
     // resolveCommand: on Windows the bare `gipity` is a .cmd shim that spawn
     // can't launch without an explicit path. An explicit env override is used
     // verbatim (it may be a full path); only the default name is resolved.
@@ -1572,13 +1672,19 @@ export async function spawnGipityClaude(args, cwd, d, queue, meta) {
     // `--include-partial-messages` adds stream_event token deltas, which
     // feed the ephemeral live-typing channel (see stream-delta.ts); whole
     // assistant/tool events still arrive unchanged for the persistent path.
-    const fullArgs = [...args, '--output-format', 'stream-json', '--verbose', '--include-partial-messages'];
+    const fullArgs = streamJson
+        ? [...args, '--output-format', 'stream-json', '--verbose', '--include-partial-messages']
+        : [...args];
     // GIPITY_CAPTURE=off: the daemon owns capture for this dispatch (it
     // parses the stream-json on stdout), so the plugin's lifecycle-hook
     // capture must stand down. `gipity claude` sets the same sentinel on the
     // Claude child when it detects a daemon spawn; setting it here too keeps
-    // dispatches double-post-free even across CLI version skew.
-    const env = childEnv({ GIPITY_CONVERSATION_GUID: d.conversation_guid, GIPITY_CAPTURE: 'off' });
+    // dispatches double-post-free even across CLI version skew. Non-Claude
+    // agents are the opposite: hook capture IS the transcript path, so the
+    // sentinel must NOT be set.
+    const env = streamJson
+        ? childEnv({ GIPITY_CONVERSATION_GUID: d.conversation_guid, GIPITY_CAPTURE: 'off' })
+        : childEnv({ GIPITY_CONVERSATION_GUID: d.conversation_guid });
     return new Promise((resolve, reject) => {
         const child = spawnCommand(cmd, fullArgs, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
         // `exited` fires when the child fully unwinds (exit event). Callers
@@ -1780,9 +1886,11 @@ export async function spawnGipityClaude(args, cwd, d, queue, meta) {
         child.stdout?.on('data', (chunk) => {
             stdoutBytesTotal += chunk.length;
             lastStdoutByteAt = Date.now();
-            splitter.push(chunk);
+            if (streamJson)
+                splitter.push(chunk);
         });
-        child.stdout?.on('end', () => splitter.flush());
+        child.stdout?.on('end', () => { if (streamJson)
+            splitter.flush(); });
         // Stderr: human-readable only (Claude's progress bars, errors).
         // Kept on the daemon's own stderr for `gipity relay log`, plus a
         // small tail ring so a crash with no stream output can include the

package/dist/relay/diagnostics.js

@@ -137,14 +137,16 @@ export async function collectDiagnostics() {
     } })();
     // Run the subprocess probes concurrently (each already bounded + best-effort)
     // so the whole snapshot costs one timeout, not the sum of four.
-    const [claude, codex, cursor, gpu] = await Promise.all([
-        probeVersion('claude'), probeVersion('codex'), probeVersion('cursor'), detectGpu(),
+    const [claude, codex, grok, cursor, gpu] = await Promise.all([
+        probeVersion('claude'), probeVersion('codex'), probeVersion('grok'), probeVersion('cursor'), detectGpu(),
     ]);
     const agents = {};
     if (claude)
         agents.claude_code = claude;
     if (codex)
         agents.codex = codex;
+    if (grok)
+        agents.grok = grok;
     if (cursor)
         agents.cursor = cursor;
     return {

package/dist/relay/onboarding.js

@@ -75,7 +75,7 @@ export async function runRelaySetup(opts) {
             console.log(`  ${dim('To register this computer again — for example under a different name —')}`);
             console.log(`  ${dim('unregister it first, then re-run setup:')}`);
             console.log(`      ${brand('gipity relay revoke')}   ${dim('# unpairs this computer and removes the login service')}`);
-            console.log(`      ${brand('gipity setup')}          ${dim('# register it again (asks for a new name)')}`);
+            console.log(`      ${brand('gipity connect')}        ${dim('# register it again (asks for a new name)')}`);
             console.log('');
         }
         return true;
@@ -84,14 +84,14 @@ export async function runRelaySetup(opts) {
     // `gipity claude` first-run frames it as an optional add-on it's offering.
     if (opts.mode === 'run-now') {
         console.log(`  ${bold('Set up this computer as a relay')}`);
-        console.log(`  ${dim('A relay runs Claude Code (or Codex) here so you can drive it from the web (')}${brand('gipity.ai')}${dim(') on any browser.')}`);
-        console.log(`  ${dim('It uses your Claude or Codex subscription — the cheapest way to pay for tokens.')}`);
+        console.log(`  ${dim('A relay runs your coding agent (Claude Code, Codex, or Grok) here so you can drive it from the web (')}${brand('gipity.ai')}${dim(') on any browser.')}`);
+        console.log(`  ${dim('It uses your Claude, Codex, or Grok subscription — the cheapest way to pay for tokens.')}`);
     }
     else {
-        console.log(`  ${bold('Remote control of Claude Code')}`);
-        console.log(`  ${dim('Drive this Claude Code from the web (')}${brand('gipity.ai')}${dim(') on any browser (desktop or phone).')}`);
+        console.log(`  ${bold('Remote control of your coding agent')}`);
+        console.log(`  ${dim('Drive your coding agent on this computer from the web (')}${brand('gipity.ai')}${dim(') on any browser (desktop or phone).')}`);
         console.log('');
-        console.log(`  ${dim('Enable now (takes 2 seconds) or turn on later with')} ${brand('gipity setup')}`);
+        console.log(`  ${dim('Enable now (takes 2 seconds) or turn on later with')} ${brand('gipity connect')}`);
     }
     console.log('');
     const promptText = opts.mode === 'run-now'
@@ -121,7 +121,7 @@ export async function runRelaySetup(opts) {
     }
     catch (err) {
         console.error(`\n  ${clrError(`Could not create device: ${err?.message || err}`)}`);
-        console.error(`  ${dim('Skipping for now - we\'ll offer again next time. Or turn it on with `gipity setup`.')}`);
+        console.error(`  ${dim('Skipping for now - we\'ll offer again next time. Or turn it on with `gipity connect`.')}`);
         // Deliberately DON'T persist relay_enabled here: the user SAID YES, and
         // this is a transient failure (network blip, server down). Leaving the
         // tri-state unset means onboarding re-offers on the next `gipity claude`
@@ -129,7 +129,7 @@ export async function runRelaySetup(opts) {
         return false;
     }
     // Start the daemon for this session.
-    const startNow = await confirm('  Start the relay now (and on future `gipity claude` runs)?', { default: 'yes' });
+    const startNow = await confirm('  Start the relay now (and on future `gipity build` runs)?', { default: 'yes' });
     if (startNow) {
         startDaemon();
     }
@@ -145,7 +145,7 @@ export async function runRelaySetup(opts) {
                     // generic non-zero. The relay itself is unaffected (it's already
                     // running this session, and `gipity claude` restarts it).
                     console.log(`  ${muted('Auto-start needs systemd, which this WSL distro has off. The relay still runs -')}`);
-                    console.log(`  ${muted('it started just now and `gipity claude` restarts it. For boot-time auto-start:')}`);
+                    console.log(`  ${muted('it started just now and `gipity build` restarts it. For boot-time auto-start:')}`);
                     console.log(`  ${muted('add [boot] systemd=true to /etc/wsl.conf, restart WSL, then run')} ${brand('gipity relay install')}${muted('.')}`);
                 }
                 else {

package/dist/relay/setup.js

@@ -60,8 +60,10 @@ export function resolveCliPath() {
 /**
  * Create + persist a relay device, marking the relay opted-in. Idempotent
  * unless `force`: if this machine is already paired and `!force`, the
- * existing device is returned untouched (no server call). With `force`, the
- * old device is revoked server-side (best-effort) before re-pairing.
+ * existing device is returned untouched (no server call). With `force`, we
+ * simply re-register: the server's machine_id dedup reattaches the same
+ * device row and rotates its token (no pre-revoke - revoking first forced a
+ * NEW row and orphaned the conversations bound to the old one, issue #291).
  *
  * Throws on a bad name or if the `/remote-devices` call fails (e.g. 401 when
  * the user isn't logged in) — callers translate that into their own UX.
@@ -78,12 +80,10 @@ export async function pairDevice(opts = {}) {
         };
     }
     if (existing && opts.force) {
-        try {
-            await post(`/remote-devices/${encodeURIComponent(existing.guid)}/revoke`, {});
-        }
-        catch {
-            // Best-effort: a stale server-side device is harmless; proceed to re-pair.
-        }
+        // Re-register in place: POST /remote-devices with this machine_id
+        // reattaches the existing row and rotates the token, which invalidates
+        // the old bearer anyway - a separate revoke round-trip only detached
+        // the row and orphaned its conversations.
         state.clearDevice();
     }
     const name = (opts.name?.trim() || friendlyDeviceName()).trim();

package/dist/relay/state.js

@@ -8,7 +8,7 @@
  *     paused: boolean,
  *   }
  *
- * The `token` field is the raw device bearer returned by /pair/claim - it
+ * The `token` field is the raw device bearer returned by POST /remote-devices - it
  * never leaves this file or the Authorization header. A future chunk will
  * move it to OS keychain (macOS Keychain, libsecret, wincred); the state
  * module's public surface is designed to absorb that change.