gipity 1.0.411 → 1.0.413

package/dist/auth.js

@@ -166,6 +166,15 @@ export async function refreshTokenIfNeeded(force = false) {
     const fresh = (a) => Date.now() <= new Date(a.expiresAt).getTime() - buffer;
     if (!force && fresh(auth))
         return; // fast path: token still good, no lock needed
+    // The specific access token the caller saw (the one the server just rejected on the
+    // force path). A locally-"fresh" token EQUAL to this can't be trusted - it's exactly
+    // what got a 401 - but a DIFFERENT fresh token means a sibling successfully rotated
+    // while we waited, and we should adopt it instead of re-refreshing with the (now
+    // single-use-consumed) refresh token. Without this, N concurrent relay dispatches
+    // that all 401 at once serialize on the lock, the first refreshes, and every other
+    // one re-tries the consumed token and hard-fails with "Session expired".
+    const rejectedAccess = auth.accessToken;
+    const adoptable = (a) => !!a && fresh(a) && (!force || a.accessToken !== rejectedAccess);
     // If the refresh token itself has expired, re-login is genuinely required; leave the
     // expired auth in place so the caller's existing 401 path prompts `gipity login`.
     const refreshExp = decodeJwtExp(auth.refreshToken);
@@ -175,10 +184,10 @@ export async function refreshTokenIfNeeded(force = false) {
     const release = await acquireRefreshLock();
     try {
         // Re-check under the lock: a sibling may have refreshed while we waited. Under
-        // force we skip this adopt — a locally-"fresh" token is exactly what the server
-        // just rejected, so we must actually refresh rather than re-adopt it.
+        // force we adopt only a token DIFFERENT from the one that was just rejected (a
+        // sibling's freshly-rotated token), never the rejected one itself.
         const held = readAuthFresh();
-        if (!force && held && fresh(held)) {
+        if (adoptable(held)) {
             cached = held;
             return;
         }
@@ -186,7 +195,7 @@ export async function refreshTokenIfNeeded(force = false) {
         const apiBase = resolveApiBase();
         for (let attempt = 1; attempt <= 3; attempt++) {
             const cur = readAuthFresh(); // a sibling may have just refreshed for us
-            if (!force && cur && fresh(cur)) {
+            if (adoptable(cur)) {
                 cached = cur;
                 return;
             }
@@ -218,7 +227,7 @@ export async function refreshTokenIfNeeded(force = false) {
             // sibling's fresh token just landed; otherwise stop and let the caller re-login.
             if (res.status === 401 || res.status === 403) {
                 const after = readAuthFresh();
-                if (after && fresh(after)) {
+                if (adoptable(after)) {
                     cached = after;
                     return;
                 }

package/dist/commands/claude.js

@@ -4,15 +4,16 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, readdir
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 import { resolveCommand, spawnCommand } from '../platform.js';
-import { getAuth, saveAuth, sessionExpired, accessTokenExpired, refreshTokenIfNeeded } from '../auth.js';
-import { get, post, publicPost, ApiError, getAccountSlug } from '../api.js';
+import { getAuth, sessionExpired, accessTokenExpired, refreshTokenIfNeeded } from '../auth.js';
+import { get, post, ApiError, getAccountSlug } from '../api.js';
+import { interactiveLogin } from '../login-flow.js';
 import { getConfig, saveConfigAt, clearConfigCache, getApiBaseOverride, DEFAULT_API_BASE, getConfigPath } from '../config.js';
 import { sync } from '../sync.js';
 import { slugify, setupClaudeHooks, ensureGipityPluginInstalled, setupClaudeMd, setupAgentsMd, setupGitignore, DEFAULT_SYNC_IGNORE, isSyncIgnored } from '../setup.js';
 import { buildProjectContextBlock as buildProjectContextBlockText, buildNewProjectPrompt, buildResumeWrap, buildFreshWrap, } from '../prompts.js';
 import * as relayState from '../relay/state.js';
 import { maybeOfferRelayOn, ensureDaemonRunning } from '../relay/onboarding.js';
-import { prompt, pickOne, decodeJwtExp, confirm } from '../utils.js';
+import { prompt, pickOne, confirm } from '../utils.js';
 import { brand, bold, info, success, warning, error as clrError, muted } from '../colors.js';
 import { createProgressReporter } from '../progress.js';
 import { printBanner } from '../banner.js';
@@ -118,33 +119,9 @@ async function buildProjectContextBlock(opts) {
     const stats = await fetchProjectStats(opts.projectGuid, opts.cwd);
     return buildProjectContextBlockText({ ...opts, ...stats });
 }
-/** Interactive email+code login flow. Used on first login and when the
- *  server returns 401 mid-command (session expired). Writes the new auth
- *  to disk and returns it. */
-async function interactiveLogin() {
-    const email = await prompt('  Email: ');
-    if (!email) {
-        console.error(`\n  ${clrError('Email required.')}`);
-        process.exit(1);
-    }
-    await publicPost('/auth/login', { email });
-    console.log('  Check your email for a 6-digit code.\n');
-    const code = await prompt('  Code: ');
-    if (!code) {
-        console.error(`\n  ${clrError('Code required.')}`);
-        process.exit(1);
-    }
-    const res = await publicPost('/auth/verify', { email, code });
-    const exp = decodeJwtExp(res.accessToken);
-    if (!exp) {
-        console.error(`\n  ${clrError('Invalid token received.')}`);
-        process.exit(1);
-    }
-    const expiresAt = new Date(exp * 1000).toISOString();
-    saveAuth({ accessToken: res.accessToken, refreshToken: res.refreshToken, email, expiresAt });
-    console.log(`  ${success(`Logged in (${email}).`)}`);
-    return getAuth();
-}
+// Interactive email+code login now lives in `login-flow.ts` (shared with
+// `gipity setup`). Used on first login and when the server returns 401
+// mid-command (session expired).
 // First-run relay onboarding now lives in `relay/onboarding.ts`
 // (`maybeOfferRelayOn`). `gipity claude` invokes it after project
 // selection, and also calls `ensureDaemonRunning` unconditionally before
@@ -310,26 +287,42 @@ export const claudeCommand = new Command('claude')
         // saved session's expiry is irrelevant when one is set — never re-login or
         // warn about expiry in that case.
         const hasEnvToken = Boolean(process.env.GIPITY_TOKEN?.trim());
-        // For an interactive saved-session run, renew the access token UP FRONT so
-        // the login line we're about to print is actually true. A saved session
-        // can look valid locally (refresh token not past its JWT expiry, so
-        // sessionExpired() is false) yet be dead on the server — most often because
-        // a sibling process sharing this auth.json already consumed the single-use
-        // refresh token (GipRunner runs many gipity processes against one auth dir).
-        // refreshTokenIfNeeded() attempts the rotation here; if it fails, the
-        // access token stays expired and accessTokenExpired() catches it below.
-        if (auth && !hasEnvToken && !nonInteractive && !sessionExpired()) {
+        // Renew the access token UP FRONT so the login line we're about to print is
+        // actually true — in BOTH interactive and headless/relay runs. A saved
+        // session can look valid locally (refresh token not past its 7-day JWT
+        // expiry, so sessionExpired() is false) yet be dead on the server: a sibling
+        // process sharing this auth.json already consumed the single-use refresh
+        // token (GipRunner and the relay run many gipity processes against one auth
+        // dir), the user logged in elsewhere, or — in dev — the server's session
+        // store was flushed/restarted. refreshTokenIfNeeded() round-trips to the
+        // server and adopts any freshly-rotated token; if it fails, the access token
+        // stays expired and accessTokenExpired() catches it below. Headless runs
+        // USED to skip this and print "Logged in" off the cheap local check alone —
+        // then the very next sync would 401 with "Session expired" and the relay
+        // would run Claude anyway against a tree it could neither pull nor push.
+        if (auth && !hasEnvToken && !sessionExpired()) {
             await refreshTokenIfNeeded();
             auth = getAuth();
         }
         // Re-login is genuinely required when the refresh token has lapsed, OR the
         // proactive renewal above could not produce a still-valid access token
-        // (refresh token rejected/rotated away). The access-token check is gated to
-        // interactive runs: headless runs can't prompt, and their downstream API
-        // call renews the token itself. Never triggered while a GIPITY_TOKEN env
+        // (refresh token rejected — rotated away, revoked, or the server forgot it).
+        // Checked identically for headless and interactive now: a dead session must
+        // not silently proceed in either. Never triggered while a GIPITY_TOKEN env
         // token is supplying auth.
         const reloginRequired = auth != null && !hasEnvToken &&
-            (sessionExpired() || (!nonInteractive && accessTokenExpired()));
+            (sessionExpired() || accessTokenExpired());
+        if (auth && reloginRequired && nonInteractive) {
+            // Headless (relay dispatch, CI): we can't prompt for a re-login, and
+            // running Claude now would work against a project tree we can neither pull
+            // nor push (every authenticated call 401s). Fail fast with the actionable
+            // message instead of printing "Logged in" and silently losing the user's
+            // changes. The relay surfaces this stderr line to the web CLI as the
+            // dispatch error, so the user sees "run: gipity login" instead of a run
+            // that appeared to work but synced nothing.
+            console.error(`  ${clrError('Your Gipity session has expired. Run: gipity login')}`);
+            process.exit(1);
+        }
         if (auth && reloginRequired) {
             // The saved session is dead (refresh token lapsed, or rotated away by a
             // sibling process), so the first API call below would 401. Re-login up

package/dist/commands/relay.js

@@ -13,6 +13,7 @@ import { confirm } from '../utils.js';
 import { bold, brand, dim, success, error as clrError, muted, } from '../colors.js';
 import * as state from '../relay/state.js';
 import * as daemon from '../relay/daemon.js';
+import { revokeRelayAgentToken } from '../relay/agent-token.js';
 import { UnsupportedPlatformError } from '../relay/installers.js';
 import { pairDevice, startDaemon, installAutostart, removeAutostart } from '../relay/setup.js';
 import { registerInstallCommands } from './relay-install.js';
@@ -268,6 +269,12 @@ relayCommand
         console.error(clrError(`Server revoke failed: ${err?.message || err}`));
         console.error(muted('Local token cleared anyway. Visit the web CLI to confirm the server-side revoke.'));
     }
+    // Also revoke the relay's agent token (minted for spawned children).
+    // Best-effort: on failure it stays visible in `gipity token list`.
+    const agentTokenRevoked = await revokeRelayAgentToken();
+    if (!agentTokenRevoked && state.getAgentToken()) {
+        console.error(muted('Could not revoke the relay agent token - check `gipity token list`.'));
+    }
     state.clearDevice();
     // Remove the OS autostart unit too. Otherwise the login service relaunches
     // `relay run`, which - finding no device but a valid login - silently

package/dist/commands/setup.js

@@ -0,0 +1,59 @@
+/**
+ * `gipity setup` — get this computer ready as a relay, then stop.
+ *
+ * Runs the SAME first steps as `gipity claude` (log in, then pair + start the
+ * relay + install the OS login service) but does NOT pick a project or launch
+ * Claude Code. For the user who wants their machine available as a relay in the
+ * web CLI without being dropped into a coding session.
+ *
+ * Shares one implementation with `gipity claude`: auth via `login-flow.ts`,
+ * relay setup via `relay/onboarding.ts` (`runRelaySetup`). Nothing to maintain
+ * twice.
+ */
+import { Command } from 'commander';
+import { getAuth, sessionExpired, refreshTokenIfNeeded } from '../auth.js';
+import { interactiveLogin } from '../login-flow.js';
+import { runRelaySetup } from '../relay/onboarding.js';
+import * as relayState from '../relay/state.js';
+import { bold, brand, success, muted, error as clrError } from '../colors.js';
+export const setupCommand = new Command('setup')
+    .description('Set up this computer as a relay (no project, no launch)')
+    .action(async () => {
+    try {
+        console.log('');
+        console.log(`  ${bold('Gipity setup')} ${muted('- get this computer ready as a relay')}`);
+        console.log('');
+        // ── Step 1: Auth ──────────────────────────────────────────────────
+        let auth = getAuth();
+        if (auth && !sessionExpired()) {
+            await refreshTokenIfNeeded();
+            auth = getAuth();
+            console.log(`  Logged in (${auth?.email}).`);
+        }
+        else {
+            if (auth)
+                console.log(`  ${muted('Your session expired. Let\'s sign you back in.')}\n`);
+            else
+                console.log('  Let\'s get you logged in.\n');
+            auth = await interactiveLogin();
+        }
+        console.log('');
+        // ── Step 2: Relay setup (always run — the user asked for it) ───────
+        const enabled = await runRelaySetup({ mode: 'run-now' });
+        // ── Step 3: Done. No project, no Claude Code launch. ──────────────
+        if (enabled) {
+            const running = relayState.isRelayEnabled() && !relayState.isPaused();
+            console.log(`  ${success('Done')} — your relay ${running ? 'is running in the background' : 'is set up'} and will start with your computer.`);
+            console.log(`  ${muted('Open')} ${brand('gipity.ai')} ${muted('and start a chat to drive Claude Code here. Manage it with `gipity relay status`.')}`);
+        }
+        else {
+            console.log(`  ${muted('No relay set up. Run `gipity setup` again anytime, or `gipity claude` to build with Gipity.')}`);
+        }
+        console.log('');
+    }
+    catch (err) {
+        console.error(`\n  ${clrError(`Error: ${err.message}`)}`);
+        process.exit(1);
+    }
+});
+//# sourceMappingURL=setup.js.map

package/dist/index.js

@@ -52,6 +52,7 @@ import { locationCommand } from './commands/location.js';
 import { doctorCommand } from './commands/doctor.js';
 import { updateCommand } from './commands/update.js';
 import { relayCommand } from './commands/relay.js';
+import { setupCommand } from './commands/setup.js';
 import { uninstallCommand } from './commands/uninstall.js';
 import { approvalCommand } from './commands/approval.js';
 import { gmailCommand } from './commands/gmail.js';
@@ -125,7 +126,7 @@ const program = new Command();
 program.enablePositionalOptions();
 // ── Command groups (logical ordering within each) ──────────────────────
 const commonGroup = [skillCommand, projectCommand, addCommand, removeCommand, deployCommand];
-const connectGroup = [claudeCommand, relayCommand];
+const connectGroup = [claudeCommand, setupCommand, relayCommand];
 const projectGroup = [domainCommand, statusCommand, initCommand];
 const filesGroup = [fileCommand, storageCommand, syncCommand, pushCommand, uploadCommand];
 const appBuildingGroup = [testCommand, fnCommand, serviceCommand, secretsCommand, notifyCommand, paymentsCommand, jobCommand, dbCommand, logsCommand, workflowCommand, realtimeCommand, rbacCommand, auditCommand, recordsCommand];
@@ -180,6 +181,7 @@ program.configureHelp({
         lines.push(bold('Quick start:'));
         lines.push(`  ${brand('gipity login')}    ${dim('- authenticate first if you haven\'t already')}`);
         lines.push(`  ${brand('gipity init')}     ${dim('- link this dir + write CLAUDE.md/AGENTS.md primers for your AI tool')}`);
+        lines.push(`  ${brand('gipity setup')}    ${dim('- set up this computer as a relay to drive from gipity.ai (no launch)')}`);
         lines.push(`  ${brand('gipity claude')}   ${dim('- or launch Claude Code with Gipity tools wired in')}`);
         lines.push('');
         lines.push(bold('Usage:'));

package/dist/login-flow.js

@@ -0,0 +1,42 @@
+/**
+ * Interactive email+code login, shared by every command that may need to log a
+ * user in mid-run (`gipity claude`, `gipity setup`). Kept in one place so the
+ * prompts, indentation, and token handling never drift between entry points.
+ *
+ * Distinct from `commands/login.ts` (the standalone `gipity login`, which also
+ * supports non-interactive `--email/--code`): this variant is the two-space
+ * indented, always-interactive flow used as a sub-step of a larger command, and
+ * it returns the fresh `AuthData` instead of exiting.
+ */
+import { publicPost } from './api.js';
+import { getAuth, saveAuth } from './auth.js';
+import { prompt, decodeJwtExp } from './utils.js';
+import { success, error as clrError } from './colors.js';
+/** Prompt for email + 6-digit code, persist the tokens, and return the new
+ *  auth. Exits the process on empty input or a bad token (the caller can't
+ *  proceed without a session). */
+export async function interactiveLogin() {
+    const email = await prompt('  Email: ');
+    if (!email) {
+        console.error(`\n  ${clrError('Email required.')}`);
+        process.exit(1);
+    }
+    await publicPost('/auth/login', { email });
+    console.log('  Check your email for a 6-digit code.\n');
+    const code = await prompt('  Code: ');
+    if (!code) {
+        console.error(`\n  ${clrError('Code required.')}`);
+        process.exit(1);
+    }
+    const res = await publicPost('/auth/verify', { email, code });
+    const exp = decodeJwtExp(res.accessToken);
+    if (!exp) {
+        console.error(`\n  ${clrError('Invalid token received.')}`);
+        process.exit(1);
+    }
+    const expiresAt = new Date(exp * 1000).toISOString();
+    saveAuth({ accessToken: res.accessToken, refreshToken: res.refreshToken, email, expiresAt });
+    console.log(`  ${success(`Logged in (${email}).`)}`);
+    return getAuth();
+}
+//# sourceMappingURL=login-flow.js.map

package/dist/relay/agent-token.js

@@ -0,0 +1,75 @@
+/**
+ * Long-lived agent API token for relay-spawned children.
+ *
+ * The daemon itself authenticates with its device token, but the children it
+ * spawns (`gipity sync`, `gipity claude -p`) used to fall back to the shared
+ * session in ~/.gipity/auth.json - and with up to 6 concurrent dispatches,
+ * sibling processes raced each other on the session's SINGLE-USE refresh
+ * token, intermittently failing with "Session expired" mid-dispatch.
+ *
+ * Instead, the daemon holds a long-lived gip_at_* agent API token (minted
+ * once, stored in relay.json 0600 next to the device token) and exports it
+ * to every child as GIPITY_TOKEN. The CLI's auth layer prefers an env token
+ * over the session, so children authenticate statelessly - no refresh, no
+ * lock, no race. If minting fails (e.g. daemon started at boot with an
+ * expired session), we return null and children fall back to the session
+ * path, which is exactly the old behavior.
+ */
+import { hostname } from 'os';
+import { post, del } from '../api.js';
+import { resolveApiBase } from '../config.js';
+import * as state from './state.js';
+/** Validate a stored token against the API. Only a definitive 401 counts as
+ *  invalid - transient failures (network, 5xx) must not discard a good token
+ *  and trigger a re-mint storm. */
+async function tokenValid(token) {
+    try {
+        const res = await fetch(`${resolveApiBase()}/users/me`, {
+            headers: { 'Authorization': `Bearer ${token}` },
+        });
+        return res.status !== 401;
+    }
+    catch {
+        return true; // network blip - assume still valid
+    }
+}
+/**
+ * Return the relay's agent token, minting one if absent or revoked. Minting
+ * uses the caller's normal session auth (the daemon process is logged in),
+ * so it can fail when the session is dead - callers treat null as "children
+ * use session auth" (graceful degradation to the old behavior).
+ */
+export async function ensureRelayAgentToken() {
+    const existing = state.getAgentToken();
+    if (existing) {
+        if (await tokenValid(existing.token))
+            return existing.token;
+        state.setAgentToken(null, null); // revoked/expired - drop and re-mint
+    }
+    try {
+        const name = `Relay on ${state.getDevice()?.name ?? hostname()}`;
+        const res = await post('/auth/agent-tokens', { name });
+        state.setAgentToken(res.data.token, res.data.shortGuid);
+        return res.data.token;
+    }
+    catch {
+        return null;
+    }
+}
+/** Best-effort server-side revocation of the relay's agent token (used when
+ *  the device is unpaired). Local state is cleared by clearDevice() either
+ *  way; a failed server call just leaves a dead-weight token the user can
+ *  still see and revoke with `gipity token list` / `revoke`. */
+export async function revokeRelayAgentToken() {
+    const existing = state.getAgentToken();
+    if (!existing?.guid)
+        return false;
+    try {
+        await del(`/auth/agent-tokens/${encodeURIComponent(existing.guid)}`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=agent-token.js.map

package/dist/relay/daemon.js

@@ -7,7 +7,7 @@ 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 { getAuth, readAuthFresh } from '../auth.js';
+import { getAuth, readAuthFresh, refreshTokenIfNeeded, accessTokenExpired } from '../auth.js';
 import { post } from '../api.js';
 import * as state from './state.js';
 import { createLineSplitter, parseEvent, mapEventToEntries, } from './stream-json.js';
@@ -15,6 +15,7 @@ import { IngestQueue } from './ingest-queue.js';
 import { DeltaAccumulator, DeltaBatcher } from './stream-delta.js';
 import { randomUUID } from 'crypto';
 import { deviceFetch, bridgeAbort as bridgeAbortImpl } from './device-http.js';
+import { ensureRelayAgentToken } from './agent-token.js';
 import { redactEntries, redactString, normalizeSecrets } from './redact.js';
 import { getMachineId } from './machine-id.js';
 // Re-exported so the existing `relay-bridge-abort.test.ts` keeps working.
@@ -84,6 +85,19 @@ async function registerDevice() {
 // so routine runs don't spam the log, but `gipity relay run --verbose`
 // surfaces every dispatch decision for live troubleshooting.
 let verboseMode = process.env.GIPITY_RELAY_VERBOSE === '1';
+// Agent token exported to spawned children as GIPITY_TOKEN (see agent-token.ts).
+// Resolved once at daemon startup; null = fall back to shared session auth.
+let relayAgentToken = null;
+/** Environment for relay-spawned `gipity` children. Adds GIPITY_TOKEN when the
+ *  daemon holds an agent token so children authenticate statelessly instead of
+ *  racing siblings on the session's single-use refresh token. */
+function childEnv(extra = {}) {
+    return {
+        ...process.env,
+        ...(relayAgentToken ? { GIPITY_TOKEN: relayAgentToken } : {}),
+        ...extra,
+    };
+}
 function setVerbose(on) { verboseMode = verboseMode || on; }
 // ANSI helpers - only colorize when stderr is a TTY.
 const TTY = !!process.stderr.isTTY;
@@ -239,6 +253,18 @@ export async function run(opts = {}) {
     process.on('exit', releasePid);
     // Also release on our shutdown signals (exit handler sometimes doesn't fire).
     ctx.abort.signal.addEventListener('abort', releasePid, { once: true });
+    // Long-lived agent token for spawned children (gipity sync / gipity claude).
+    // With it, children authenticate via GIPITY_TOKEN - stateless, no refresh -
+    // instead of racing sibling processes on the session's single-use refresh
+    // token. Minting needs a live session; on failure children fall back to
+    // session auth (the old behavior), so the daemon still runs.
+    relayAgentToken = await ensureRelayAgentToken();
+    if (relayAgentToken) {
+        log('info', 'agent token ready - spawned children use GIPITY_TOKEN');
+    }
+    else {
+        log('warn', 'no agent token (mint failed or session dead) - children fall back to session auth');
+    }
     log('info', 'relay started', { device: device.guid, name: device.name, pid: process.pid });
     // Run all loops concurrently; exit when any returns (or abort fires).
     // Cancellation poller runs alongside the dispatch loop so user-initiated
@@ -255,6 +281,9 @@ export async function run(opts = {}) {
 // ─── Heartbeat loop ────────────────────────────────────────────────────
 async function heartbeatLoop(ctx) {
     let backoff = 0;
+    // Log the "session expired" warning only on the transition into that state,
+    // not every 60s, so a genuinely-lapsed session doesn't spam the relay log.
+    let sessionWarnLogged = false;
     while (!ctx.abort.signal.aborted) {
         try {
             const r = await deviceFetch('POST', '/remote-devices/heartbeat', {}, 10_000, ctx.abort.signal);
@@ -266,6 +295,38 @@ async function heartbeatLoop(ctx) {
             if (!r.ok)
                 throw new Error(`heartbeat ${r.status}`);
             backoff = 0;
+            // Keep the USER session warm alongside the device heartbeat. The device
+            // token (used for this heartbeat and to claim dispatches) is a SEPARATE,
+            // long-lived credential from the user's OAuth session in auth.json — a
+            // healthy heartbeat says nothing about whether `gipity sync` / `gipity
+            // claude` can authenticate. The relay is long-lived but the access token
+            // lives only ~1h and the refresh token ~7d; left idle between dispatches
+            // the session lapses and the next dispatch's child scrambles to refresh
+            // (or finds it dead). Refreshing here — in the long-lived PARENT (never
+            // SIGKILL'd mid-rotate the way a per-dispatch child can be), under the
+            // shared cross-process auth lock — renews BOTH tokens well inside their
+            // windows (each refresh mints a fresh 7-day token), so a continuously
+            // running relay never gets bumped out from disuse, and dispatch children
+            // hit refreshTokenIfNeeded's fast path instead of racing to rotate the
+            // single-use token. Best-effort: it no-ops while the token is still fresh
+            // and never throws. If it can't renew, the session is genuinely dead —
+            // log it once so `gipity relay log` shows why dispatches will fail until
+            // the user re-logs in (nothing here can revive it without a TTY).
+            if (getAuth()) {
+                try {
+                    await refreshTokenIfNeeded();
+                    if (accessTokenExpired() && !sessionWarnLogged) {
+                        log('warn', 'user session expired - dispatches will fail to sync until re-login (run: gipity login)');
+                        sessionWarnLogged = true;
+                    }
+                    else if (!accessTokenExpired()) {
+                        sessionWarnLogged = false;
+                    }
+                }
+                catch (err) {
+                    log('debug', 'session warm failed', { err: err?.message });
+                }
+            }
         }
         catch (err) {
             if (ctx.abort.signal.aborted)
@@ -1096,7 +1157,7 @@ async function spawnSync(cwd, timeoutMs, onSpawn) {
     return new Promise((resolve, reject) => {
         const child = spawnCommand(cmd, ['sync', '--json'], {
             cwd,
-            env: process.env,
+            env: childEnv(),
             stdio: ['ignore', 'pipe', 'pipe'],
         });
         // Hand the child to the caller so it can register the sync in `running`,
@@ -1152,7 +1213,7 @@ export async function spawnGipityClaude(args, cwd, d, queue, meta) {
     // 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 env = { ...process.env, GIPITY_CONVERSATION_GUID: d.conversation_guid };
+    const env = 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

package/dist/relay/onboarding.js

@@ -1,13 +1,20 @@
 /**
- * One-time first-run relay onboarding. Called from `gipity claude` after
- * auth + project selection. Asks up to four Y/n questions (all default Y);
- * pressing Enter four times leaves the user with a paired + running
- * daemon that auto-starts on every subsequent `gipity claude` invocation,
- * and - if they said yes to the last question - also starts at OS login.
+ * Interactive relay setup — the single flow that pairs this computer as a
+ * relay, starts the daemon, and (optionally) installs the OS login service.
+ * ONE implementation, shared by both entry points:
+ *
+ *   - `gipity claude`  → `maybeOfferRelayOn()`  (mode 'offer-once': runs on the
+ *                        very first launch, then never nags again).
+ *   - `gipity setup`   → `runRelaySetup({ mode: 'run-now' })` (the user asked
+ *                        for it explicitly, so always run — even to re-pair or
+ *                        fix autostart on a machine that already answered).
+ *
+ * All the non-interactive primitives live in `setup.ts` (`pairDevice`,
+ * `startDaemon`, `installAutostart`); this module is only the prompts + copy.
  */
 import { hostname } from 'os';
 import { prompt, confirm } from '../utils.js';
-import { bold, brand, dim, success, error as clrError, muted, info } from '../colors.js';
+import { bold, brand, dim, success, error as clrError, muted } from '../colors.js';
 import * as state from './state.js';
 import { UnsupportedPlatformError } from './installers.js';
 import { pairDevice, startDaemon, installAutostart } from './setup.js';
@@ -16,28 +23,41 @@ import { pairDevice, startDaemon, installAutostart } from './setup.js';
  *  keep their import path. */
 export const ensureDaemonRunning = startDaemon;
 /**
- * First-run prompt block. Idempotent: if the user has already answered
- * (`relay_enabled` is a boolean), this is a no-op. Non-interactive flows
- * (e.g. `gipity claude -p`) should skip calling this.
+ * Pair this computer as a relay and get it running. Returns `true` if the relay
+ * ended up enabled (or was already), `false` if the user declined or a step
+ * failed. Non-interactive flows (e.g. `gipity claude -p`) must not call this.
  */
-export async function maybeOfferRelayOn() {
-    if (state.getRelayEnabled() !== undefined) {
-        // Already answered - just ensure the daemon is running if they're opted in.
+export async function runRelaySetup(opts) {
+    const alreadyAnswered = state.getRelayEnabled() !== undefined;
+    // `gipity claude` first-run: honor the user's prior choice and don't re-ask.
+    if (opts.mode === 'offer-once' && alreadyAnswered) {
         if (state.isRelayEnabled() && !state.isPaused())
             ensureDaemonRunning();
-        return;
+        return state.isRelayEnabled();
+    }
+    // Header. `gipity setup` frames it as the deliberate action it is; the
+    // `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.')}`);
+    }
+    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('');
+        console.log(`  ${dim('Enable now (takes 2 seconds) or turn on later with')} ${brand('gipity setup')}`);
     }
-    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('');
-    console.log(`  ${dim('Enable now (takes 2 seconds) or turn on later with')} ${brand('gipity relay install')}`);
     console.log('');
-    const enable = await confirm('  Enable remote control?', { default: 'yes' });
+    const promptText = opts.mode === 'run-now'
+        ? '  Set up remote control on this computer?'
+        : '  Enable remote control?';
+    const enable = await confirm(promptText, { default: 'yes' });
     if (!enable) {
         state.setRelayEnabled(false);
         console.log(`  ${muted('Skipped.')}`);
         console.log('');
-        return;
+        return false;
     }
     // Device name - show hostname as the default; Enter accepts.
     const defaultName = hostname() || 'my-pc';
@@ -46,7 +66,7 @@ export async function maybeOfferRelayOn() {
     if (!name || name.length > 100) {
         console.error(`  ${clrError('Device name must be 1–100 non-whitespace characters. Skipping.')}`);
         state.setRelayEnabled(false);
-        return;
+        return false;
     }
     // Create the device directly (user-auth, no pair code). `pairDevice` writes
     // the device + flips relay_enabled on; we only have to render the outcome.
@@ -56,12 +76,12 @@ export async function maybeOfferRelayOn() {
     }
     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 relay install`.')}`);
+        console.error(`  ${dim('Skipping for now - we\'ll offer again next time. Or turn it on with `gipity setup`.')}`);
         // 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`
         // run instead of silently opting the user out forever.
-        return;
+        return false;
     }
     // Start the daemon for this session.
     const startNow = await confirm('  Start the relay now (and on future `gipity claude` runs)?', { default: 'yes' });
@@ -93,6 +113,14 @@ export async function maybeOfferRelayOn() {
     console.log(`  ${success(`Registered as ${bold(device.name)} (${device.guid}).`)}`);
     console.log(`  ${dim('In the Gipity web CLI, type `/claude` to dispatch messages to this PC.')}`);
     console.log('');
-    void info;
+    return true;
+}
+/**
+ * First-run prompt block for `gipity claude`. Idempotent: if the user has
+ * already answered, this is a no-op (beyond keeping the daemon alive).
+ * Non-interactive flows (e.g. `gipity claude -p`) should skip calling this.
+ */
+export async function maybeOfferRelayOn() {
+    await runRelaySetup({ mode: 'offer-once' });
 }
 //# sourceMappingURL=onboarding.js.map

package/dist/relay/state.js

@@ -38,6 +38,8 @@ export function loadState() {
             paused: Boolean(raw.paused),
             relay_enabled: typeof raw.relay_enabled === 'boolean' ? raw.relay_enabled : undefined,
             onboard_shown: Boolean(raw.onboard_shown),
+            agent_token: typeof raw.agent_token === 'string' ? raw.agent_token : null,
+            agent_token_guid: typeof raw.agent_token_guid === 'string' ? raw.agent_token_guid : null,
         };
     }
     catch {
@@ -73,8 +75,18 @@ export function setDevice(device) {
     mutate(s => { s.device = device; });
 }
 export function clearDevice() {
-    // Forget the device → also clear pause flag (scoped to the device).
-    mutate(s => { s.device = null; s.paused = false; });
+    // Forget the device → also clear the pause flag and the agent token
+    // (both scoped to the device). Server-side token revocation is the
+    // caller's job (best-effort, see revokeRelayAgentToken).
+    mutate(s => { s.device = null; s.paused = false; s.agent_token = null; s.agent_token_guid = null; });
+}
+// ─── Agent token (exported to spawned children as GIPITY_TOKEN) ────────
+export function getAgentToken() {
+    const s = loadState();
+    return s.agent_token ? { token: s.agent_token, guid: s.agent_token_guid ?? null } : null;
+}
+export function setAgentToken(token, guid) {
+    mutate(s => { s.agent_token = token; s.agent_token_guid = guid; });
 }
 // ─── Pause ─────────────────────────────────────────────────────────────
 export function isPaused() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gipity",
-  "version": "1.0.411",
+  "version": "1.0.413",
   "description": "The full-stack platform tuned for AI agents. Database, storage, auth, functions, deploy, and drop-in kits - all agent-tuned. Pair with Claude Code or use standalone.",
   "bin": {
     "gipity": "dist/updater/shim.js",
@@ -13,7 +13,7 @@
     "postbuild": "node scripts/gen-build-info.mjs",
     "dev": "tsc --watch",
     "test": "npm run test:smoke",
-    "test:smoke": "tsc && node --test dist/__tests__/utils.test.js dist/__tests__/platform.test.js dist/__tests__/colors.test.js dist/__tests__/config.test.js dist/__tests__/sync.test.js dist/__tests__/sync-apply.test.js dist/__tests__/sync-lock.test.js dist/__tests__/auth-lock.test.js dist/__tests__/api-401-retry.test.js dist/__tests__/push-cas.test.js dist/__tests__/upload.test.js dist/__tests__/progress.test.js dist/__tests__/updater.test.js dist/__tests__/cli-smoke.test.js dist/__tests__/claude-noninteractive.test.js dist/__tests__/claude-trust.test.js dist/__tests__/relay-state.test.js dist/__tests__/relay-daemon.test.js dist/__tests__/relay-installers.test.js dist/__tests__/relay-bridge-abort.test.js dist/__tests__/relay-redact.test.js dist/__tests__/relay-machine-id.test.js dist/__tests__/stream-json.test.js dist/__tests__/ingest-queue.test.js dist/__tests__/stream-delta.test.js dist/__tests__/phase-tracker.test.js dist/__tests__/relay-ingest-contract.test.js dist/__tests__/prompts.test.js dist/__tests__/capture-transcript.test.js dist/__tests__/flag-aliases.test.js dist/__tests__/client-context.test.js dist/__tests__/adopt-cwd.test.js dist/__tests__/cli-cmd-agent.test.js dist/__tests__/cli-cmd-approval.test.js dist/__tests__/cli-cmd-audit.test.js dist/__tests__/cli-cmd-chat.test.js dist/__tests__/cli-cmd-credits.test.js dist/__tests__/cli-cmd-db.test.js dist/__tests__/cli-cmd-deploy.test.js dist/__tests__/cli-cmd-domain.test.js dist/__tests__/cli-cmd-email.test.js dist/__tests__/cli-cmd-file.test.js dist/__tests__/cli-cmd-storage.test.js dist/__tests__/cli-cmd-fn.test.js dist/__tests__/cli-cmd-service.test.js dist/__tests__/cli-cmd-job.test.js dist/__tests__/cli-cmd-generate.test.js dist/__tests__/cli-cmd-gmail.test.js dist/__tests__/cli-cmd-info.test.js dist/__tests__/cli-cmd-init.test.js dist/__tests__/cli-cmd-location.test.js dist/__tests__/cli-cmd-text.test.js dist/__tests__/cli-cmd-login.test.js dist/__tests__/cli-cmd-logout.test.js dist/__tests__/cli-cmd-token.test.js dist/__tests__/cli-cmd-logs.test.js dist/__tests__/cli-cmd-memory.test.js dist/__tests__/cli-cmd-page.test.js dist/__tests__/cli-cmd-plan.test.js dist/__tests__/cli-cmd-project.test.js dist/__tests__/cli-cmd-rbac.test.js dist/__tests__/cli-cmd-realtime.test.js dist/__tests__/cli-cmd-records.test.js dist/__tests__/cli-cmd-relay.test.js dist/__tests__/cli-cmd-doctor.test.js dist/__tests__/claude-setup.test.js dist/__tests__/cli-cmd-sandbox.test.js dist/__tests__/cli-cmd-add.test.js dist/__tests__/cli-cmd-remove.test.js dist/__tests__/cli-cmd-skill.test.js dist/__tests__/cli-cmd-test.test.js dist/__tests__/cli-cmd-workflow.test.js dist/__tests__/setup-skills-block.test.js dist/__tests__/setup-hooks.test.js",
+    "test:smoke": "tsc && node --test dist/__tests__/utils.test.js dist/__tests__/platform.test.js dist/__tests__/colors.test.js dist/__tests__/config.test.js dist/__tests__/sync.test.js dist/__tests__/sync-apply.test.js dist/__tests__/sync-lock.test.js dist/__tests__/auth-lock.test.js dist/__tests__/api-401-retry.test.js dist/__tests__/push-cas.test.js dist/__tests__/upload.test.js dist/__tests__/progress.test.js dist/__tests__/updater.test.js dist/__tests__/cli-smoke.test.js dist/__tests__/claude-noninteractive.test.js dist/__tests__/claude-trust.test.js dist/__tests__/relay-state.test.js dist/__tests__/relay-daemon.test.js dist/__tests__/relay-installers.test.js dist/__tests__/relay-bridge-abort.test.js dist/__tests__/relay-redact.test.js dist/__tests__/relay-machine-id.test.js dist/__tests__/stream-json.test.js dist/__tests__/ingest-queue.test.js dist/__tests__/stream-delta.test.js dist/__tests__/phase-tracker.test.js dist/__tests__/relay-ingest-contract.test.js dist/__tests__/prompts.test.js dist/__tests__/capture-transcript.test.js dist/__tests__/flag-aliases.test.js dist/__tests__/client-context.test.js dist/__tests__/adopt-cwd.test.js dist/__tests__/cli-cmd-agent.test.js dist/__tests__/cli-cmd-approval.test.js dist/__tests__/cli-cmd-audit.test.js dist/__tests__/cli-cmd-chat.test.js dist/__tests__/cli-cmd-credits.test.js dist/__tests__/cli-cmd-db.test.js dist/__tests__/cli-cmd-deploy.test.js dist/__tests__/cli-cmd-domain.test.js dist/__tests__/cli-cmd-email.test.js dist/__tests__/cli-cmd-file.test.js dist/__tests__/cli-cmd-storage.test.js dist/__tests__/cli-cmd-fn.test.js dist/__tests__/cli-cmd-service.test.js dist/__tests__/cli-cmd-job.test.js dist/__tests__/cli-cmd-generate.test.js dist/__tests__/cli-cmd-gmail.test.js dist/__tests__/cli-cmd-info.test.js dist/__tests__/cli-cmd-init.test.js dist/__tests__/cli-cmd-location.test.js dist/__tests__/cli-cmd-text.test.js dist/__tests__/cli-cmd-login.test.js dist/__tests__/cli-cmd-logout.test.js dist/__tests__/cli-cmd-token.test.js dist/__tests__/cli-cmd-logs.test.js dist/__tests__/cli-cmd-memory.test.js dist/__tests__/cli-cmd-page.test.js dist/__tests__/cli-cmd-plan.test.js dist/__tests__/cli-cmd-project.test.js dist/__tests__/cli-cmd-rbac.test.js dist/__tests__/cli-cmd-realtime.test.js dist/__tests__/cli-cmd-records.test.js dist/__tests__/cli-cmd-relay.test.js dist/__tests__/cli-cmd-setup.test.js dist/__tests__/cli-cmd-doctor.test.js dist/__tests__/claude-setup.test.js dist/__tests__/cli-cmd-sandbox.test.js dist/__tests__/cli-cmd-add.test.js dist/__tests__/cli-cmd-remove.test.js dist/__tests__/cli-cmd-skill.test.js dist/__tests__/cli-cmd-test.test.js dist/__tests__/cli-cmd-workflow.test.js dist/__tests__/setup-skills-block.test.js dist/__tests__/setup-hooks.test.js",
     "test:smoke:quick": "node scripts/smoke-quick.mjs",
     "test:e2e": "tsc && GIPITY_E2E=1 node --test --test-timeout=180000 dist/__tests__/cli-e2e-live.test.js dist/__tests__/cli-e2e-sync-live.test.js dist/__tests__/cli-e2e-sync-stress-live.test.js dist/__tests__/cli-e2e-rollback-live.test.js dist/__tests__/cli-e2e-services-media-live.test.js dist/__tests__/cli-e2e-workflow-live.test.js dist/__tests__/cli-e2e-sandbox-live.test.js dist/__tests__/cli-e2e-page-fetch-live.test.js dist/__tests__/cli-e2e-page-test-live.test.js",
     "test:e2e:sync": "tsc && GIPITY_E2E=1 node --test --test-timeout=180000 dist/__tests__/cli-e2e-sync-live.test.js",