flowviant 0.97.0 → 0.100.0

package/bin/lib/deploy.mjs

@@ -64,12 +64,26 @@
 
 
 import { spawn } from 'node:child_process';
-import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import {
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  realpathSync,
+  rmdirSync,
+  rmSync,
+  symlinkSync,
+  unlinkSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, isAbsolute, join, relative, sep } from 'node:path';
 import { FLEET_URL, FLEET_TOKEN, USER_AGENT, DAEMON_INSTANCE } from './config.mjs';
 import { c, note, ok, warn } from './ui.mjs';
 import { scrub, myPubB64 } from './env.mjs';
 import { childEnv } from './childEnv.mjs';
-import { git } from './git.mjs';
+import { git, gitNetAsync } from './git.mjs';
 
 const deployUrl = (tail) => FLEET_URL.replace(/\/agents\/?$/, `/${tail}`);
 
@@ -157,24 +171,60 @@ export async function reportDeployConfig(repoRoot, baseRef) {
     o && typeof o === 'object'
       ? Object.fromEntries(Object.entries(o).map(([k, v]) => [k, scrub(String(v ?? ''))]))
       : o;
-  const meta = targets.map((t) => ({
-    id: t.id,
-    label: t.label,
-    provider: t.provider || 'cloudflare',
-    command: scrub(String(t.command ?? '')),
-    build: t.build ? scrub(String(t.build)) : t.build,
-    commands: scrubCmds(t.commands),
-    healthcheck: t.healthcheck,
-    healthStatus: t.healthStatus,
-    pushSecrets: t.pushSecrets,
-    // Deploy-on-merge: the env this target auto-deploys to when commits land
-    // on base. MUST ride this map — a field forgotten here never reaches the
-    // server, and the server is what turns a landed report into the job.
-    ...(typeof t.onMerge === 'string' ? { onMerge: t.onMerge } : {}),
-  }));
+  /**
+   * NORMALIZE BEFORE POSTING (2026-09-24, the audit). `.flowviant/deploy.json`
+   * is a hand-written file; the shared schema treats `healthStatus` /
+   * `healthcheck` / `build` / `label` as display metadata and drops what it
+   * cannot read rather than refusing the whole target — but this file used to
+   * send them through unmodified, so a `"healthStatus": "200"` (which
+   * `verifyHealth` below already coerces with `Number()`) or a `null` label
+   * used to reach the wire looking present-but-unreadable. Send exactly what
+   * the mirror is going to keep instead of what the file happened to spell:
+   * a numeric `healthStatus` when the value is numeric or a numeric string,
+   * and no key at all for `label` / `healthcheck` / `build` when the file's
+   * value is not a non-empty string.
+   */
+  const numOrOmit = (v) => {
+    if (typeof v === 'number' && Number.isFinite(v)) return v;
+    if (typeof v === 'string' && /^\s*\d+\s*$/.test(v)) return Number(v);
+    return undefined;
+  };
+  const strOrOmit = (v) => (typeof v === 'string' && v.trim() ? v : undefined);
+  const meta = targets.map((t) => {
+    const label = strOrOmit(t.label);
+    const build = strOrOmit(t.build);
+    const healthcheck = strOrOmit(t.healthcheck);
+    const healthStatus = numOrOmit(t.healthStatus);
+    return {
+      id: t.id,
+      ...(label !== undefined ? { label } : {}),
+      provider: t.provider || 'cloudflare',
+      command: scrub(String(t.command ?? '')),
+      ...(build !== undefined ? { build: scrub(build) } : {}),
+      commands: scrubCmds(t.commands),
+      ...(healthcheck !== undefined ? { healthcheck } : {}),
+      ...(healthStatus !== undefined ? { healthStatus } : {}),
+      pushSecrets: t.pushSecrets,
+      // Deploy-on-merge: the env this target auto-deploys to when commits land
+      // on base. MUST ride this map — a field forgotten here never reaches the
+      // server, and the server is what turns a landed report into the job.
+      ...(typeof t.onMerge === 'string' ? { onMerge: t.onMerge } : {}),
+    };
+  });
   try {
-    await post('deploy-config', { pubkey: myPubB64(), targets: meta });
+    const data = await post('deploy-config', { pubkey: myPubB64(), targets: meta });
+    // Set on any 2xx, rejected targets included — the route now accepts a
+    // report per-target rather than failing the whole thing, so a target it
+    // could not read is not a reason to re-post this same file forever.
     lastConfigJson = json;
+    // THE SERVER NAMES WHAT IT COULD NOT READ. Warned once per CHANGED config —
+    // this function only reaches here when the file did — never once per poll.
+    const rejected = Array.isArray(data?.rejected) ? data.rejected : [];
+    for (const r of rejected) {
+      warn(
+        `deploy: .flowviant/deploy.json target "${r?.id ?? '?'}" was not accepted — ${r?.reason ?? 'invalid'}`
+      );
+    }
   } catch (e) {
     warn(`deploy: could not report config — ${e.message}`);
   }
@@ -323,14 +373,8 @@ export function processDeployJobs(jobs, ctx) {
               }
             });
         }, 60_000);
-        const targets = readDeployConfig(ctx.repoRoot, ctx.baseRef);
-        const target = targets.find((t) => t.id === job.targetId);
-        if (!target) {
-          await report(job, ctx, { ok: false, message: `target "${job.targetId}" not in .flowviant/deploy.json` });
-          return;
-        }
         note(`${c.cyan('deploy')} ${c.dim(`— ${job.kind} ${job.targetId} → ${job.env}…`)}`);
-        const outcome = await runDeploy(job, target, ctx);
+        const outcome = await runDeploy(job, ctx);
         // From here the work is DONE. Whatever the report does, this job must
         // never run again in this process.
         ran.add(job.id);
@@ -351,7 +395,271 @@ export function processDeployJobs(jobs, ctx) {
   }
 }
 
-async function runDeploy(job, target, ctx) {
+/**
+ * A DEPLOY BUILDS THE BASE COMMIT, NEVER THE OPERATOR'S WORKING TREE
+ * (audit 2026-09-24).
+ *
+ * `readDeployConfig` reads the TARGET off base so that authoring a command
+ * requires landing it — and then every command ran with `cwd: repoRoot`, the
+ * operator's own checkout, on whatever branch they left it with whatever they
+ * had not committed. So `npm run build` and `wrangler deploy` read the
+ * package.json scripts, wrangler.toml and source of that working tree:
+ * deploy-on-merge (queued by a teammate's ship, a PR merge or an agent merge,
+ * none of which moves the checkout) shipped code WITHOUT the merge that
+ * triggered it, and a co-owner's "deploy it to prod" shipped the operator's
+ * half-finished branch. Reproduced: a checkout on `feature` with an
+ * uncommitted edit deployed the edit.
+ *
+ * So a deploy runs in a THROWAWAY DETACHED WORKTREE at the base tip — the
+ * shipMerge shape — and the config is read from THAT SHA, so the command and
+ * the code it builds are one commit. The directory dies in a `finally`.
+ *
+ * What a fresh worktree does not have is what git does not track: installed
+ * dependencies and the operator's env files. Those are the checkout's
+ * ENVIRONMENT, not its code, so for every directory base tracks (three levels
+ * deep) a `node_modules` in the checkout is re-created as a directory of links
+ * to its entries — a WORKSPACE package's link re-pointed at base's own copy of
+ * that package, never the checkout's working tree — and a `.env` / `.env.*` /
+ * `.dev.vars` the base commit does not carry is COPIED in. Stated residual:
+ * installed third-party packages and those env files are still the checkout's,
+ * so a dependency installed for a feature branch, or an untracked env file an
+ * agent edited, reaches the build; so does a workspace package's untracked
+ * build output (`dist/`), which is simply absent here and fails the build
+ * loudly rather than shipping the checkout's. A `.bin` shim is linked whole, so
+ * a workspace package's own CLI still runs from the checkout. Submodules are
+ * not initialised. The code and the commands no longer come from the checkout.
+ */
+const ENV_FILE_RE = /^(?:\.env(?:\..+)?|\.dev\.vars)$/;
+const lexists = (p) => {
+  try {
+    lstatSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** Bring the checkout's untracked environment into a deploy worktree. Returns
+ *  every path it created, so the cleanup can unlink them BEFORE the worktree
+ *  is removed (a recursive delete must never be handed a symlink into the
+ *  operator's own node_modules). */
+export function linkCheckoutEnvironment(repoRoot, dir) {
+  const made = [];
+  let realRoot = repoRoot;
+  try {
+    realRoot = realpathSync(repoRoot);
+  } catch {
+    /* compared as given */
+  }
+  /**
+   * A node_modules is a REAL directory of per-entry links, not one link to the
+   * checkout's (review, audit 2026-09-24). A workspace package — npm, yarn and
+   * pnpm all install one as a link like `node_modules/@x/shared ->
+   * ../../packages/shared` — resolves THROUGH the checkout's node_modules into
+   * the checkout's WORKING TREE, so a whole-directory link had every bundler
+   * import the operator's uncommitted `packages/shared/src` into a deploy of
+   * base. An entry whose real path is inside the checkout but outside any
+   * node_modules is re-pointed at the SAME path in this worktree (base's copy);
+   * one base does not carry is left out, since base cannot import what it does
+   * not have. Every other entry links to the checkout's own, as before.
+   */
+  const linkNodeModules = (src, dst, depth) => {
+    let entries;
+    try {
+      entries = readdirSync(src, { withFileTypes: true });
+      mkdirSync(dst);
+      made.push(dst);
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const s = join(src, e.name);
+      const d = join(dst, e.name);
+      // A scope directory holds packages, not a package: one level down.
+      if (depth === 0 && e.name.startsWith('@') && e.isDirectory()) {
+        linkNodeModules(s, d, 1);
+        continue;
+      }
+      let target = s;
+      if (e.isSymbolicLink()) {
+        let real;
+        try {
+          real = realpathSync(s);
+        } catch {
+          continue; // a dangling link — nothing to bring
+        }
+        const rel = relative(realRoot, real);
+        const inCheckout = rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+        if (inCheckout && !rel.split(sep).includes('node_modules')) {
+          if (!existsSync(join(dir, rel))) continue;
+          target = join(dir, rel);
+        }
+      }
+      try {
+        symlinkSync(target, d);
+        made.push(d);
+      } catch {
+        /* the build says so if it needed it */
+      }
+    }
+  };
+  const walk = (rel, depth) => {
+    let entries;
+    try {
+      entries = readdirSync(join(repoRoot, rel), { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const src = join(repoRoot, rel, e.name);
+      const dst = join(dir, rel, e.name);
+      if (e.name === '.git') continue;
+      if (e.name === 'node_modules') {
+        if (e.isDirectory() && !lexists(dst)) linkNodeModules(src, dst, 0);
+        continue;
+      }
+      if (e.isFile() && ENV_FILE_RE.test(e.name)) {
+        if (!lexists(dst)) {
+          try {
+            copyFileSync(src, dst);
+            made.push(dst);
+          } catch {
+            /* unreadable — the build says so if it needed it */
+          }
+        }
+        continue;
+      }
+      // Recurse only into directories BASE tracks — an untracked `dist/` or a
+      // cache is neither code nor environment, and walking it costs a scan.
+      if (e.isDirectory() && depth < 3 && existsSync(dst) && !lexists(join(dst, '.git'))) {
+        walk(join(rel, e.name), depth + 1);
+      }
+    }
+  };
+  walk('', 0);
+  return made;
+}
+
+/**
+ * Cut the deploy worktree at the base tip. Returns `{ dir, sha, cleanup }`, or
+ * throws with a sentence when base does not resolve. `worktreeDir` defaults to
+ * the daemon's own worktree home for this repo (fleet.mjs keys it the same
+ * way); the job id is hashed into the path, never joined raw — it is a
+ * server-named string.
+ */
+export async function openDeployCheckout({ repoRoot, baseRef, jobId, worktreeDir }) {
+  if (!baseRef) throw new Error('no base branch resolved, so there is nothing to deploy from');
+  try {
+    // A NETWORK call, so timed, non-interactive and off the event loop — a
+    // bare `git fetch` here is `execFileSync` with no timeout, and a remote
+    // that prompts or a half-open connection froze every poll and lease on
+    // the machine until it returned.
+    await gitNetAsync(['fetch', 'origin', '--quiet'], repoRoot);
+  } catch {
+    /* offline — deploy the base this box last saw, and say which */
+  }
+  let sha;
+  try {
+    sha = git(['rev-parse', '--verify', `${baseRef}^{commit}`], repoRoot);
+  } catch {
+    throw new Error(`the base branch ${baseRef} does not resolve on this machine`);
+  }
+  const home =
+    worktreeDir ??
+    join(
+      homedir(),
+      '.flowviant',
+      'worktrees',
+      `${basename(repoRoot)}-${createHash('sha256').update(repoRoot).digest('hex').slice(0, 8)}`
+    );
+  const dir = join(home, 'deploy', createHash('sha256').update(String(jobId)).digest('hex').slice(0, 16));
+  mkdirSync(join(home, 'deploy'), { recursive: true });
+  const drop = (made = [], target = dir) => {
+    // Newest first, so a node_modules directory we made is empty of our links
+    // by the time it is removed.
+    for (const p of [...made].reverse()) {
+      try {
+        unlinkSync(p);
+      } catch {
+        try {
+          rmdirSync(p);
+        } catch {
+          /* already gone */
+        }
+      }
+    }
+    try {
+      git(['worktree', 'remove', '--force', target], repoRoot);
+    } catch {
+      /* not registered */
+    }
+    // Every symlink we made is already unlinked, and `rmSync` unlinks a
+    // symlink rather than descending it, so this can only delete our own copy.
+    try {
+      rmSync(target, { recursive: true, force: true });
+    } catch {
+      /* best-effort */
+    }
+    try {
+      git(['worktree', 'prune'], repoRoot);
+    } catch {
+      /* best-effort */
+    }
+  };
+  drop(); // a corpse from a crashed deploy of the same job
+  // …and any other job's corpse old enough that no deploy can still be running
+  // in it (two commands at most, 30 minutes each), so a daemon killed
+  // mid-deploy does not leave a checkout on disk for ever.
+  try {
+    const cutoff = Date.now() - 3 * 60 * 60 * 1000;
+    for (const name of readdirSync(join(home, 'deploy'))) {
+      const p = join(home, 'deploy', name);
+      try {
+        if (p !== dir && lstatSync(p).mtimeMs < cutoff) drop([], p);
+      } catch {
+        /* gone meanwhile */
+      }
+    }
+  } catch {
+    /* nothing to sweep */
+  }
+  git(['worktree', 'add', '--detach', dir, sha], repoRoot);
+  let made = [];
+  try {
+    made = linkCheckoutEnvironment(repoRoot, dir);
+  } catch {
+    /* the build says so if it needed any of it */
+  }
+  return { dir, sha, cleanup: () => drop(made) };
+}
+
+export async function runDeploy(job, ctx) {
+  let checkout;
+  try {
+    checkout = await openDeployCheckout({
+      repoRoot: ctx.repoRoot,
+      baseRef: ctx.baseRef,
+      jobId: job.id,
+      worktreeDir: ctx.worktreeDir,
+    });
+  } catch (e) {
+    return { ok: false, message: `deploy not run — ${e.message}`, logs: [] };
+  }
+  try {
+    const targets = readDeployConfig(ctx.repoRoot, checkout.sha);
+    const target = targets.find((t) => t.id === job.targetId);
+    if (!target) {
+      return { ok: false, message: `target "${job.targetId}" not in .flowviant/deploy.json`, logs: [] };
+    }
+    const outcome = await runDeployIn(job, target, checkout.dir);
+    const short = checkout.sha.slice(0, 12);
+    return { ...outcome, sha: checkout.sha, message: `${outcome.message} (${short})` };
+  } finally {
+    checkout.cleanup();
+  }
+}
+
+async function runDeployIn(job, target, cwd) {
   // AN ALLOWLIST, not `{...process.env}` minus names. What stood here was
   //
   //     const env = { ...process.env, ...deployCreds() };
@@ -369,18 +677,44 @@ async function runDeploy(job, target, ctx) {
   // nothing else. It replaced `extra: deployCreds()` when the vault was deleted
   // — the credentials are the OPERATOR's now, in the shell they started the
   // daemon in, rather than values Flowviant decrypted onto the box.
-  const env = childEnv({ cwd: ctx.repoRoot, deploy: true }); // infra creds; never a file
+  const env = childEnv({ cwd, deploy: true }); // infra creds; never a file
   const logs = [];
+  /**
+   * THE ENV-ISOLATION GUARD, RE-APPLIED HERE (2026-09-24, the audit).
+   *
+   * The server already refuses a non-prod trigger whose target declares no
+   * per-env override — `createDeployJob`'s own comment names the same
+   * fallback this file resolves, `commands?.[env] || command`, as the reason:
+   * the base `command` (and the bare `npx wrangler rollback` default) is the
+   * PROD command, so a dev/preview trigger with no override would silently
+   * run production. But that check reads the SERVER'S MIRROR
+   * (`reportDeployConfig`'s last post), and this function reads the file OFF
+   * THE COMMIT it is about to build and run — a window the trigger-time check
+   * cannot close: the file on base changed after the last report, or this
+   * daemon has not reported yet. So the same rule is asked again here,
+   * against the only copy that is about to matter, and prod is the one env
+   * this never touches.
+   */
+  if (job.env !== 'prod') {
+    const key = job.kind === 'rollback' ? `rollback:${job.env}` : job.env;
+    if (!target.commands?.[key]) {
+      return {
+        ok: false,
+        message: `target declares no ${job.env} command — refusing to fall back to the prod command`,
+        logs,
+      };
+    }
+  }
   // Rollback is a single wrangler command; deploy is build → secrets → deploy.
   if (job.kind === 'rollback') {
     const cmd = target.commands?.[`rollback:${job.env}`] || `npx wrangler rollback`;
-    const r = await run(cmd, { cwd: ctx.repoRoot, env });
+    const r = await run(cmd, { cwd, env });
     logs.push(...tailLines(r.out));
     return { ok: r.ok, message: r.ok ? 'rolled back' : logs.slice(-6).join('\n'), logs };
   }
 
   if (target.build) {
-    const b = await run(target.build, { cwd: ctx.repoRoot, env });
+    const b = await run(target.build, { cwd, env });
     logs.push(...tailLines(b.out));
     if (!b.ok) return { ok: false, message: `build failed:\n${logs.slice(-6).join('\n')}`, logs };
   }
@@ -397,7 +731,7 @@ async function runDeploy(job, target, ctx) {
   // values belong there. `target.pushSecrets` stays parsed and reported, which
   // is what every retired key in this product does.
   const cmd = target.commands?.[job.env] || target.command;
-  const d = await run(cmd, { cwd: ctx.repoRoot, env });
+  const d = await run(cmd, { cwd, env });
   logs.push(...tailLines(d.out));
   if (!d.ok) return { ok: false, message: `deploy failed:\n${logs.slice(-8).join('\n')}`, logs };
 

package/bin/lib/desktopContract.mjs

@@ -0,0 +1,227 @@
+/** Local, read-only desktop contract and bounded daemon logs. */
+import { createHash } from 'node:crypto';
+import { appendFileSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { format } from 'node:util';
+import { FLEET_URL, MACHINE_HOST, USER_AGENT, VERSION } from './config.mjs';
+import { listStoredProjects } from './credentials.mjs';
+import { readStoredPubB64 } from './env.mjs';
+import { daemonRunningFor } from './instance.mjs';
+import { runningViaNpx } from './launchCommand.mjs';
+import { boxesUrlFrom, fetchBoxesFor } from './machines.mjs';
+import { detectRuntimes } from './runtimes.mjs';
+import { runningCompiledBinary } from './update.mjs';
+
+export const MAX_DAEMON_LOG_BYTES = 2 * 1024 * 1024;
+const store = () => join(homedir(), '.flowviant');
+const key = (projectId) => createHash('sha256').update(String(projectId)).digest('hex').slice(0, 16);
+export const daemonLogPath = (projectId) => join(store(), `daemon-${key(projectId)}.log`);
+export const daemonStatePath = (projectId) => join(store(), `daemon-${key(projectId)}.state.json`);
+
+function readState(projectId) {
+  try {
+    const value = JSON.parse(readFileSync(daemonStatePath(projectId), 'utf8'));
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  } catch { return {}; }
+}
+
+export function writeDaemonState(projectId, change) {
+  if (!projectId) return;
+  try {
+    mkdirSync(store(), { recursive: true });
+    const path = daemonStatePath(projectId);
+    const current = readState(projectId);
+    const next = { ...current, ...change, pid: process.pid };
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(next), { mode: 0o600 });
+    renameSync(tmp, path);
+  } catch { /* a local readout must never interrupt a daemon */ }
+}
+
+export function setRuntimeLimit(projectId, runtime, words) {
+  if (!projectId || !runtime) return false;
+  const state = readState(projectId);
+  const limits = { ...(state.limits ?? {}) };
+  if (words == null) {
+    if (!Object.hasOwn(limits, runtime)) return false;
+    delete limits[runtime];
+  } else {
+    if (limits[runtime] === words) return false;
+    limits[runtime] = words;
+  }
+  writeDaemonState(projectId, { limits });
+  emitMachineEvent({ event: words == null ? 'limit-cleared' : 'limit-hit', runtime, ...(words == null ? {} : { message: words }) });
+  return true;
+}
+
+export function installChannel() {
+  return runningCompiledBinary() ? 'binary' : runningViaNpx() ? 'npx' : 'npm-g';
+}
+
+export function desktopStatus({ entries = listStoredProjects(), runtimes = detectRuntimes(), runningFor = daemonRunningFor, stateFor = readState, pidFor = lockPid } = {}) {
+  return {
+    schema: 1,
+    version: VERSION,
+    installChannel: installChannel(),
+    projects: entries.map((entry) => {
+      const running = runningFor(entry.fleetToken);
+      const state = stateFor(entry.projectId);
+      const liveState = running === true && state.pid != null && state.pid === pidFor(entry.fleetToken) ? state : null;
+      return {
+        id: entry.projectId,
+        name: entry.name ?? null,
+        dir: entry.repoRoot ?? null,
+        running,
+        holder: liveState?.holder ?? null,
+        lastPoll: state.lastPoll ?? null,
+        logFile: daemonLogPath(entry.projectId),
+        runtimes: runtimes.map((rt) => ({
+          id: rt.id,
+          installed: rt.installed,
+          version: rt.version ?? null,
+          dispatchable: rt.dispatchable,
+          ...(liveState?.limits?.[rt.id] ? { parkedByLimit: true, message: liveState.limits[rt.id] } : {}),
+        })),
+      };
+    }),
+    // A box with no projects still has installed CLIs.
+    runtimes: runtimes.map((rt) => ({ id: rt.id, installed: rt.installed, version: rt.version ?? null, dispatchable: rt.dispatchable })),
+  };
+}
+
+const REMOTE_TIMEOUT_MS = 4_000;
+
+async function remoteRead(read, timeoutMs) {
+  const controller = new AbortController();
+  let timer;
+  try {
+    // Abort the request and bound body parsing even if a fetch ignores its signal.
+    return await Promise.race([
+      read(controller.signal),
+      new Promise((resolve) => {
+        timer = setTimeout(() => {
+          controller.abort();
+          resolve({ error: `timed out after ${timeoutMs}ms` });
+        }, timeoutMs);
+      }),
+    ]);
+  } catch (error) {
+    return { error: String(error?.message ?? error) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function liveAgent(row) {
+  if (!row || typeof row !== 'object' || typeof row.id !== 'string' || !row.id ||
+      typeof row.name !== 'string' || !row.name || typeof row.status !== 'string' ||
+      typeof row.runtime !== 'string' || !row.runtime ||
+      !['delivered', 'total'].every((field) => Number.isInteger(row[field]) && row[field] >= 0) ||
+      !['asks', 'parked'].every((field) => typeof row[field] === 'boolean') ||
+      !(row.since === null || typeof row.since === 'string')) return null;
+  const { id, name, status, runtime, delivered, total, asks, parked, since } = row;
+  return { id, name, status, runtime, delivered, total, asks, parked, since };
+}
+
+async function fetchLiveAgentsFor(entry, { url, fetchImpl, signal }) {
+  const res = await fetchImpl(url, {
+    headers: { Authorization: `Bearer ${entry.fleetToken}`, 'User-Agent': USER_AGENT },
+    signal,
+  });
+  if (!res.ok) return { error: `HTTP ${res.status}` };
+  const body = await res.json();
+  const data = body?.data ?? body;
+  if (!data || !Array.isArray(data.agents)) return { error: 'unexpected answer shape' };
+  const pressure = data.pressure;
+  return {
+    agents: data.agents.map(liveAgent).filter(Boolean),
+    pressure: pressure && typeof pressure.reason === 'string' && typeof pressure.at === 'string'
+      ? { reason: pressure.reason, at: pressure.at } : null,
+  };
+}
+
+export async function desktopStatusRemote({ entries = listStoredProjects(), runtimes = detectRuntimes(),
+  runningFor = daemonRunningFor, stateFor = readState, pidFor = lockPid,
+  fetchImpl = fetch, envpub = readStoredPubB64(), fleetUrl = FLEET_URL, host = MACHINE_HOST,
+  now = () => new Date().toISOString(), timeoutMs = REMOTE_TIMEOUT_MS, log = console.error } = {}) {
+  const status = desktopStatus({ entries, runtimes, runningFor, stateFor, pidFor });
+  const boxesUrl = boxesUrlFrom(fleetUrl);
+  const liveUrl = String(fleetUrl).replace(/\/agents\/?$/, '/live-agents');
+  const remotes = await Promise.all(entries.map(async (entry) => {
+    if (!entry.fleetToken) return null;
+    const [boxes, live] = await Promise.all([
+      remoteRead((signal) => fetchBoxesFor(entry, { url: boxesUrl, envpub, fetchImpl, signal }), timeoutMs),
+      remoteRead((signal) => fetchLiveAgentsFor(entry, { url: liveUrl, fetchImpl, signal }), timeoutMs),
+    ]);
+    const boxesOk = Array.isArray(boxes.boxes);
+    const liveOk = Array.isArray(live.agents);
+    if (!boxesOk) {
+      const reason = boxes.error ?? (boxes.unsupported ? 'HTTP 404' : boxes.rejected ? 'credential rejected' : 'unexpected answer shape');
+      log(`status --remote ${entry.projectId} boxes: ${reason}`);
+    }
+    if (!liveOk) log(`status --remote ${entry.projectId} live-agents: ${live.error ?? 'unexpected answer shape'}`);
+    if (!boxesOk && !liveOk) return null;
+    const mine = boxesOk ? boxes.boxes.find((box) => box?.boxId === boxes.me) : null;
+    const serving = boxesOk ? boxes.boxes.find((box) => box?.role === 'serving') : null;
+    return {
+      at: now(),
+      boxName: boxesOk ? (typeof mine?.boxName === 'string' && mine.boxName ? mine.boxName : host || null) : null,
+      role: mine?.role === 'serving' || mine?.role === 'inactive' ? mine.role : null,
+      servingBoxName: typeof serving?.boxName === 'string' ? serving.boxName : null,
+      daemonVersion: typeof mine?.daemonVersion === 'string' ? mine.daemonVersion : null,
+      latest: boxesOk ? boxes.latest : null,
+      agents: liveOk ? live.agents : null,
+      pressure: liveOk ? live.pressure : null,
+    };
+  }));
+  status.projects.forEach((project, index) => { project.remote = remotes[index]; });
+  return status;
+}
+
+function lockPid(token) {
+  try {
+    const hash = createHash('sha256').update(String(token || 'anon')).digest('hex').slice(0, 12);
+    return JSON.parse(readFileSync(join(store(), `daemon-${hash}.lock`), 'utf8')).pid;
+  } catch { return null; }
+}
+
+let events = false;
+let eventWriter = process.stdout.write.bind(process.stdout);
+export function enableMachineEvents(write = eventWriter) { events = true; eventWriter = write; }
+export function emitMachineEvent(value) {
+  if (events) eventWriter(`${JSON.stringify(value)}\n`);
+}
+
+/** All human output stays on its existing stream in terminal mode. In desktop
+ * mode stdout is reserved for JSONL and those same lines go to stderr. */
+export function installDaemonLogging(projectId, { jsonEvents = false } = {}) {
+  if (!projectId) return;
+  if (jsonEvents) {
+    enableMachineEvents();
+    process.stdout.write = (...args) => process.stderr.write(...args);
+  }
+  const original = { log: console.log, info: console.info, warn: console.warn, error: console.error };
+  const logPath = daemonLogPath(projectId);
+  for (const method of Object.keys(original)) {
+    console[method] = (...args) => {
+      const line = format(...args);
+      try {
+        mkdirSync(store(), { recursive: true });
+        const encoded = Buffer.from(`${line}\n`);
+        const tail = Buffer.from('\n[truncated]\n');
+        const chunk = encoded.length > MAX_DAEMON_LOG_BYTES
+          ? Buffer.concat([encoded.subarray(0, MAX_DAEMON_LOG_BYTES - tail.length), tail])
+          : encoded;
+        let size = 0;
+        try { size = statSync(logPath).size; } catch { /* new file */ }
+        if (size + chunk.length > MAX_DAEMON_LOG_BYTES) {
+          try { renameSync(logPath, `${logPath}.1`); } catch { /* no old log */ }
+        }
+        appendFileSync(logPath, chunk, { mode: 0o600 });
+      } catch { /* logging must never stop service */ }
+      if (jsonEvents) process.stderr.write(`${line}\n`);
+      else original[method](...args);
+    };
+  }
+}