flowviant 0.26.0 → 0.27.1

package/bin/cli.mjs

@@ -101,6 +101,15 @@ if (process.argv[2] === 'clean') {
   process.exit(0);
 }
 
+// `flowviant env <import|set|show>` — the CLI half of team env sync. Values
+// are sealed to the project pubkey ON THIS MACHINE (same write-only crypto as
+// the browser); `show` decrypts locally — it only works on an ENROLLED machine.
+if (process.argv[2] === 'env') {
+  const { runEnvCommand } = await import('./lib/env-cli.mjs');
+  await runEnvCommand(process.argv.slice(3));
+  process.exit(0);
+}
+
 if (!FLEET_TOKEN && tokens.length === 0) {
   console.error(
     'error: no credential found. Easiest:\n' +

package/bin/lib/claude.mjs

@@ -35,7 +35,10 @@ Operate this loop:
 5. Return to step 1.
 
 Keep every change scoped to the claimed intent. If a tool errors, report_progress with
-the error, then retry or report_blocker.`;
+the error, then retry or report_blocker.
+SECRETS: env files (.env, .dev.vars, …) hold the team's synced secrets. Their VALUES
+must NEVER appear in evidence, progress, summaries, commits, or PRs — reference keys
+by NAME only. Never commit an env file.`;
 
 // Single-task turn (FLEET mode): claim EXACTLY ONE intent, then stop. The daemon
 // owns the loop so it can reset the worktree + start a fresh conversation per task.
@@ -63,7 +66,10 @@ Do EXACTLY ONE task this turn:
 
 Do NOT claim a second intent — exactly one per turn. Keep every change scoped to the
 claimed intent. If a tool errors, report_progress with the error, then retry or
-report_blocker.`;
+report_blocker.
+SECRETS: env files (.env, .dev.vars, …) hold the team's synced secrets. Their VALUES
+must NEVER appear in evidence, progress, summaries, commits, or PRs — reference keys
+by NAME only. Never commit an env file.`;
 
 export const KICKOFF =
   'Begin the loop: claim and complete all dispatched Flowviant intents per your instructions.';

package/bin/lib/config.mjs

@@ -4,7 +4,7 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 
-export const VERSION = '0.26.0';
+export const VERSION = '0.27.1';
 
 // The model EVERY daemon Claude turn runs on — pinned so autonomous work never
 // inherits your interactive `~/.claude/settings.json` default. That matters: a

package/bin/lib/env-cli.mjs

@@ -0,0 +1,212 @@
+/**
+ * `flowviant env <import|set|show>` — the CLI half of team env sync.
+ *
+ * import <file> [--file <targetFile>]  seed the synced bundle from an existing
+ *                                      env file (KEY=value lines; comments and
+ *                                      blank lines skipped). The onboarding
+ *                                      moment: one command, whole team synced.
+ * set <KEY> [--file <targetFile>]      set/rotate one value (prompted on stdin,
+ *                                      never argv — argv leaks into shell
+ *                                      history and `ps`).
+ * show [KEY]                           decrypt locally and print — only works
+ *                                      on an ENROLLED machine (this is the
+ *                                      only place values are ever readable).
+ *
+ * Writes are sealed to the project pubkey on this machine (same write-only
+ * crypto as the browser) and pushed via the fleet-token endpoint; every
+ * enrolled daemon resyncs within seconds via the push channel.
+ */
+
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { createInterface } from 'node:readline';
+import sodium from 'libsodium-wrappers';
+import { FLEET_URL, FLEET_TOKEN, USER_AGENT } from './config.mjs';
+import { ensureKeypair, myPubB64, fetchBundle } from './env.mjs';
+
+const B64 = () => sodium.base64_variants.ORIGINAL;
+const KEYS_URL = FLEET_URL.replace(/\/agents\/?$/, '/env/keys');
+
+const die = (msg) => {
+  console.error(`error: ${msg}`);
+  process.exit(1);
+};
+
+const fingerprint = (value) => (value ? `${value.slice(0, 4)}…(${value.length})` : '');
+
+async function postKey({ name, targetFile, value, keyEpoch, baseVersion, projectPub }) {
+  const ciphertext = sodium.to_base64(
+    sodium.crypto_box_seal(sodium.from_string(value), sodium.from_base64(projectPub, B64())),
+    B64()
+  );
+  const res = await fetch(KEYS_URL, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${FLEET_TOKEN}`,
+      'User-Agent': USER_AGENT,
+      'Content-Type': 'application/json',
+    },
+    signal: AbortSignal.timeout(30_000),
+    body: JSON.stringify({
+      pubkey: myPubB64(),
+      name,
+      env: 'dev',
+      targetFile,
+      ciphertext,
+      fingerprint: fingerprint(value),
+      keyEpoch,
+      baseVersion: baseVersion ?? null,
+    }),
+  });
+  const json = await res.json().catch(() => ({}));
+  if (!res.ok || json?.success === false) {
+    throw new Error(`${name}: ${json?.error ?? `HTTP ${res.status}`}`);
+  }
+}
+
+function parseEnvFile(text) {
+  const out = [];
+  for (const raw of text.split('\n')) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const eq = line.indexOf('=');
+    if (eq <= 0) continue;
+    const name = line.slice(0, eq).trim().replace(/^export\s+/, '');
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) continue;
+    let value = line.slice(eq + 1).trim();
+    // Strip one layer of matching quotes — the convention .env parsers follow.
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    if (value) out.push({ name, value });
+  }
+  return out;
+}
+
+function argAfter(args, flag) {
+  const i = args.indexOf(flag);
+  return i >= 0 && args[i + 1] ? args[i + 1] : null;
+}
+
+async function readSecretFromStdin(promptText) {
+  // Muted input — the typed secret must NOT echo to the terminal (a shoulder-
+  // surf / screen-share leak). We write the prompt ourselves, then swallow ALL
+  // readline output while reading. Keying the mute on "does this write contain
+  // the prompt?" is unsafe: readline's line-refresh (backspace, mid-line edit,
+  // paste, resize) re-emits `prompt + buffer` as ONE string, which would sail
+  // through such a check and echo the secret. So: mute EVERYTHING.
+  process.stderr.write(promptText);
+  const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+  rl._writeToOutput = () => {}; // swallow every echo/refresh unconditionally
+  const value = await new Promise((resolve) => rl.question('', resolve));
+  process.stderr.write('\n');
+  rl.close();
+  return value.trim();
+}
+
+export async function runEnvCommand(args) {
+  if (!FLEET_TOKEN) die('no fleet credential — run `flowviant login` first.');
+  await sodium.ready;
+  await ensureKeypair();
+  const cmd = args[0];
+
+  if (cmd === 'import') {
+    const file = args[1];
+    if (!file) die('usage: flowviant env import <path/to/.env> [--file <targetFile>]');
+    let text;
+    try {
+      text = readFileSync(file, 'utf8');
+    } catch (e) {
+      die(`could not read ${file}: ${e.message}`);
+    }
+    const entries = parseEnvFile(text);
+    if (!entries.length) die(`no KEY=value lines found in ${file}.`);
+    // Default target: the file's repo-relative-looking path as given (minus
+    // leading ./) — `flowviant env import apps/api/.dev.vars` targets exactly
+    // that file in every worktree.
+    const targetFile = argAfter(args, '--file') ?? file.replace(/^\.\//, '');
+    const bundle = await fetchBundle();
+    if (bundle.status !== 'enrolled') die('this machine is not enrolled — approve it in Settings → Environment first.');
+    if (!bundle.projectPub) die('no project env keypair yet — start the daemon once to bootstrap it.');
+    const existing = new Map(bundle.keys.map((k) => [k.name, k]));
+    let added = 0;
+    let updated = 0;
+    for (const e of entries) {
+      const prior = existing.get(e.name);
+      try {
+        await postKey({
+          name: e.name,
+          targetFile,
+          value: e.value,
+          keyEpoch: bundle.keyEpoch,
+          baseVersion: prior?.version ?? null,
+          projectPub: bundle.projectPub,
+        });
+        prior ? updated++ : added++;
+      } catch (err) {
+        console.error(`  skip ${err.message}`);
+      }
+    }
+    console.log(`imported ${basename(file)} → ${targetFile}: ${added} added, ${updated} updated. Every daemon syncs in seconds.`);
+    return;
+  }
+
+  if (cmd === 'set') {
+    const name = args[1];
+    if (!name || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) die('usage: flowviant env set <KEY> [--file <targetFile>]');
+    const bundle = await fetchBundle();
+    if (bundle.status !== 'enrolled') die('this machine is not enrolled — approve it in Settings → Environment first.');
+    if (!bundle.projectPub) die('no project env keypair yet — start the daemon once to bootstrap it.');
+    const prior = bundle.keys.find((k) => k.name === name);
+    const targetFile = argAfter(args, '--file') ?? prior?.targetFile ?? '.env';
+    const value = await readSecretFromStdin(`value for ${name} (hidden): `);
+    if (!value) die('empty value — nothing set.');
+    await postKey({
+      name,
+      targetFile,
+      value,
+      keyEpoch: bundle.keyEpoch,
+      baseVersion: prior?.version ?? null,
+      projectPub: bundle.projectPub,
+    });
+    console.log(`${name} ${prior ? `rotated (v${prior.version + 1})` : 'added'} → ${targetFile}. Every daemon syncs in seconds.`);
+    return;
+  }
+
+  if (cmd === 'show') {
+    const bundle = await fetchBundle();
+    if (bundle.status !== 'enrolled') die('this machine is not enrolled — approve it in Settings → Environment first.');
+    if (!bundle.wrappedPriv) die('no key material for this machine yet.');
+    const kp = await ensureKeypair();
+    const priv = sodium.crypto_box_seal_open(
+      sodium.from_base64(bundle.wrappedPriv, B64()),
+      kp.publicKey,
+      kp.privateKey
+    );
+    const pub = sodium.from_base64(bundle.projectPub, B64());
+    const filter = args[1];
+    let shown = 0;
+    for (const k of bundle.keys) {
+      if (filter && k.name !== filter) continue;
+      try {
+        const plain = sodium.to_string(sodium.crypto_box_seal_open(sodium.from_base64(k.ciphertext, B64()), pub, priv));
+        console.log(`${k.name}=${plain}`);
+        shown++;
+      } catch {
+        console.error(`# ${k.name}: cannot open (stale epoch — a rotation should heal it)`);
+      }
+    }
+    if (filter && !shown) die(`no key named ${filter}.`);
+    return;
+  }
+
+  console.log(
+    [
+      'flowviant env — team-synced, end-to-end-encrypted dev secrets',
+      '',
+      '  flowviant env import <file> [--file <targetFile>]   seed from an existing env file',
+      '  flowviant env set <KEY> [--file <targetFile>]       set/rotate one value (stdin)',
+      '  flowviant env show [KEY]                            decrypt locally (enrolled machines only)',
+    ].join('\n')
+  );
+}

package/bin/lib/env.mjs

@@ -0,0 +1,547 @@
+/**
+ * Team env sync — the daemon is the CRYPTO ANCHOR. This machine holds a
+ * persistent X25519 keypair (~/.flowviant/env-keypair.json, 0600); the
+ * project's private key reaches it only sealed to that pubkey. Everything the
+ * server stores is ciphertext it cannot open.
+ *
+ * Duties per roster tick (handleRosterEnv):
+ *  - register this machine's pubkey (once) → an admin approves in Settings.
+ *  - bootstrap the project keypair when none exists (first machine): generate
+ *    it + a standing RECOVERY keypair wrapped under a one-time passphrase
+ *    printed exactly once — rotations re-seal to the same recovery pub, so
+ *    that passphrase survives forever.
+ *  - sync: on a bundle version change, unwrap the priv, open every sealed
+ *    value, cache (encrypted under a key derived from our own priv), and
+ *    rematerialize env files into the agent worktrees.
+ *  - execute wrap jobs (admin approved a new machine → seal the priv to it).
+ *  - execute rotations (a machine was revoked → new keypair, re-seal all
+ *    values, re-wrap every enrolled machine, re-seal recovery).
+ *
+ * Materialization writes per-targetFile KEY=value files into a worktree and
+ * registers each path in the worktree's git info/exclude — untracked AND
+ * unstageable, so an agent can never commit them. The WIKI worktree never
+ * gets env (the cartographer doesn't need secrets).
+ *
+ * scrub() redacts every known plaintext value from daemon-posted uplinks
+ * (turn streams, wiki progress, vault sync). Agent-MCP-direct payloads
+ * (evidence, progress, complete) never pass through the daemon — those are
+ * covered by the prompt contract, not here.
+ */
+
+import {
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  existsSync,
+  appendFileSync,
+  rmSync,
+} from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { homedir, hostname } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+import sodium from 'libsodium-wrappers';
+import { FLEET_URL, FLEET_TOKEN, USER_AGENT } from './config.mjs';
+import { c, info, note, ok, warn } from './ui.mjs';
+
+const B64 = () => sodium.base64_variants.ORIGINAL;
+const KEYPAIR_PATH = join(homedir(), '.flowviant', 'env-keypair.json');
+const CACHE_DIR = join(homedir(), '.flowviant', 'env-cache');
+const SCRUB_MIN_LENGTH = 6; // mirrors shared ENV_SCRUB_MIN_LENGTH
+const envUrl = (tail) => FLEET_URL.replace(/\/agents\/?$/, `/env/${tail}`);
+
+// ── Module state (one project per daemon, same as the vault) ───────────────
+let keypair = null; // { publicKey: Uint8Array, privateKey: Uint8Array }
+let registeredOnce = false;
+let projectPriv = null; // Uint8Array — unwrapped project private key
+let bundleVersion = -1; // last materialized bundle version (-1 = never)
+let values = []; // [{ name, targetFile, value }]
+let cachedProjectId = null;
+
+export async function sodiumReady() {
+  await sodium.ready;
+}
+
+/** 6-emoji key fingerprint — algorithm MUST match the web's pubkeyEmoji
+ *  (EnvironmentSettings.tsx) so the human can compare terminal ↔ approve card. */
+// MUST stay byte-identical to the web's pubkeyEmoji (EnvironmentSettings.tsx) —
+// the human compares the two strings. 32 glyphs × 8 positions, effective ~40
+// bits. Two FNV-1a rolling hashes over the whole key + a murmur3 finalizer per
+// glyph (a plain additive sum collapsed the space to ~10 bits — grindable).
+const FP_EMOJI = ['🦊','🐙','🦕','🐝','🦉','🐬','🦁','🐸','🦄','🐢','🦋','🐺','🦜','🐳','🦔','🐌','🦩','🐿️','🦥','🐨','🦦','🐇','🦡','🦂','🦨','🐜','🦢','🐋','🦭','🐞','🦚','🐊'];
+export function pubkeyEmoji(pubkeyB64) {
+  let h1 = 0x811c9dc5 >>> 0;
+  let h2 = 0xc2b2ae35 >>> 0;
+  for (let i = 0; i < pubkeyB64.length; i++) {
+    const ch = pubkeyB64.charCodeAt(i);
+    h1 = Math.imul(h1 ^ ch, 0x01000193) >>> 0;
+    h2 = Math.imul(h2 ^ ch, 0x85ebca6b) >>> 0;
+  }
+  let out = '';
+  for (let i = 0; i < 8; i++) {
+    let x = (((i < 4 ? h1 : h2) + i * 0x9e3779b1) >>> 0);
+    x ^= x >>> 16;
+    x = Math.imul(x, 0x7feb352d) >>> 0;
+    x ^= x >>> 15;
+    x = Math.imul(x, 0x846ca68b) >>> 0;
+    x ^= x >>> 16;
+    out += FP_EMOJI[x & 31];
+  }
+  return out;
+}
+
+/** This machine's persistent keypair (created on first use, 0600). */
+export async function ensureKeypair() {
+  await sodium.ready;
+  if (keypair) return keypair;
+  try {
+    const stored = JSON.parse(readFileSync(KEYPAIR_PATH, 'utf8'));
+    keypair = {
+      publicKey: sodium.from_base64(stored.pub, B64()),
+      privateKey: sodium.from_base64(stored.priv, B64()),
+    };
+    return keypair;
+  } catch {
+    /* first run */
+  }
+  keypair = sodium.crypto_box_keypair();
+  mkdirSync(dirname(KEYPAIR_PATH), { recursive: true });
+  writeFileSync(
+    KEYPAIR_PATH,
+    JSON.stringify({
+      pub: sodium.to_base64(keypair.publicKey, B64()),
+      priv: sodium.to_base64(keypair.privateKey, B64()),
+    }),
+    { mode: 0o600 }
+  );
+  return keypair;
+}
+
+export function myPubB64() {
+  return keypair ? sodium.to_base64(keypair.publicKey, B64()) : null;
+}
+
+/** Query params the roster poll carries: identity + materialized version. */
+export async function envQueryParams() {
+  await ensureKeypair();
+  const params = { envpub: myPubB64() };
+  if (bundleVersion >= 0) params.envv = String(bundleVersion);
+  return params;
+}
+
+// ── HTTP helpers ───────────────────────────────────────────────────────────
+async function post(tail, body) {
+  const res = await fetch(envUrl(tail), {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${FLEET_TOKEN}`,
+      'User-Agent': USER_AGENT,
+      'Content-Type': 'application/json',
+    },
+    signal: AbortSignal.timeout(30_000),
+    body: JSON.stringify(body),
+  });
+  const json = await res.json().catch(() => ({}));
+  if (!res.ok || json?.success === false) {
+    throw new Error(`env ${tail} failed (${res.status}${json?.error ? `: ${json.error}` : ''})`);
+  }
+  return json?.data;
+}
+
+export async function fetchBundle() {
+  const res = await fetch(`${envUrl('bundle')}?pubkey=${encodeURIComponent(myPubB64())}`, {
+    headers: { Authorization: `Bearer ${FLEET_TOKEN}`, 'User-Agent': USER_AGENT },
+    signal: AbortSignal.timeout(30_000),
+  });
+  const json = await res.json().catch(() => ({}));
+  if (!res.ok || !json?.data) throw new Error(`env bundle fetch failed (${res.status})`);
+  return json.data;
+}
+
+// ── Crypto ─────────────────────────────────────────────────────────────────
+const seal = (bytes, pubB64) => sodium.to_base64(sodium.crypto_box_seal(bytes, sodium.from_base64(pubB64, B64())), B64());
+const openSealed = (b64, pub, priv) => sodium.crypto_box_seal_open(sodium.from_base64(b64, B64()), pub, priv);
+
+/** Cache the decrypted bundle at rest, encrypted under a key derived from our
+ *  own priv — the worktrees hold the same plaintext anyway; this just keeps
+ *  the cache from being a SECOND, tidier copy. */
+function cacheKey() {
+  return sodium.crypto_generichash(sodium.crypto_secretbox_KEYBYTES, keypair.privateKey);
+}
+function writeCache(projectId, payload) {
+  try {
+    mkdirSync(CACHE_DIR, { recursive: true });
+    const nonce = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);
+    const box = sodium.crypto_secretbox_easy(sodium.from_string(JSON.stringify(payload)), nonce, cacheKey());
+    writeFileSync(
+      join(CACHE_DIR, `${projectId}.json`),
+      JSON.stringify({ nonce: sodium.to_base64(nonce, B64()), box: sodium.to_base64(box, B64()) }),
+      { mode: 0o600 }
+    );
+  } catch {
+    /* cache is best-effort */
+  }
+}
+function readCache(projectId) {
+  try {
+    const { nonce, box } = JSON.parse(readFileSync(join(CACHE_DIR, `${projectId}.json`), 'utf8'));
+    const plain = sodium.crypto_secretbox_open_easy(
+      sodium.from_base64(box, B64()),
+      sodium.from_base64(nonce, B64()),
+      cacheKey()
+    );
+    return JSON.parse(sodium.to_string(plain));
+  } catch {
+    return null;
+  }
+}
+
+/** Offline start: materialize from the encrypted cache before the first poll.
+ *  Also seeds knownTargetFiles so stale-file cleanup survives a restart. */
+export async function loadCachedEnv(projectId) {
+  await ensureKeypair();
+  const cached = readCache(projectId);
+  if (!cached) return false;
+  values = cached.values ?? [];
+  bundleVersion = cached.bundleVersion ?? -1;
+  knownTargetFiles = new Set(cached.knownFiles ?? values.map((v) => v.targetFile));
+  cachedProjectId = projectId;
+  return values.length > 0;
+}
+
+// ── Materialization ────────────────────────────────────────────────────────
+
+/** Per-worktree git exclude — untracked AND unstageable. A git worktree's
+ *  `.git` is a FILE pointing at its private gitdir; info/exclude there applies
+ *  to that worktree only and never touches the user's repo. */
+function excludeInWorktree(wt, relPaths) {
+  try {
+    const dotGit = join(wt, '.git');
+    let gitdir = dotGit;
+    try {
+      const content = readFileSync(dotGit, 'utf8');
+      const m = content.match(/^gitdir:\s*(.+)\s*$/m);
+      if (m) gitdir = resolve(wt, m[1].trim());
+    } catch {
+      /* .git is a directory (main checkout) — use it directly */
+    }
+    const excludePath = join(gitdir, 'info', 'exclude');
+    mkdirSync(dirname(excludePath), { recursive: true });
+    let existing = '';
+    try {
+      existing = readFileSync(excludePath, 'utf8');
+    } catch {
+      /* fresh */
+    }
+    const missing = relPaths.filter((p) => !existing.split('\n').includes(`/${p}`));
+    if (missing.length) {
+      appendFileSync(excludePath, `${existing.endsWith('\n') || !existing ? '' : '\n'}${missing.map((p) => `/${p}`).join('\n')}\n`);
+    }
+  } catch {
+    /* best-effort — the agent prompt still forbids committing secrets */
+  }
+}
+
+const isSafeTarget = (p) =>
+  p &&
+  p.length <= 200 &&
+  !p.includes('\\') &&
+  !p.includes('\0') &&
+  !p.startsWith('/') &&
+  p.split('/').every((s) => s.length > 0 && s !== '.' && s !== '..');
+
+/** Is this path TRACKED in the repo? info/exclude only hides UNTRACKED files —
+ *  materializing secrets into a tracked file would make them stageable and
+ *  committable. We refuse those paths entirely. */
+function isTrackedInGit(wt, relPath) {
+  try {
+    execFileSync('git', ['ls-files', '--error-unmatch', '--', relPath], {
+      cwd: wt,
+      stdio: 'ignore',
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Per-worktree: the target files we last materialized THIS SESSION.
+const lastFilesByWorktree = new Map();
+// Project-global union of every target file we've ever materialized — PERSISTED
+// in the cache and seeded on load, so a file whose key was deleted while the
+// daemon was down still gets its stale plaintext copy cleaned on the next
+// materialize (lastFilesByWorktree alone is empty after a restart, and
+// `git clean -fd` never removes an info/exclude'd file).
+let knownTargetFiles = new Set();
+
+const MATERIALIZE_HEADER = '# Materialized by flowviant env sync';
+
+/** Render KEY=value with values that contain newlines/= safely quoted so one
+ *  value can't fabricate another key line. */
+function renderEnvFile(list) {
+  const lines = list.map((v) => {
+    const needsQuote = /[\n\r"'`$\\ ]/.test(v.value) || v.value === '';
+    if (!needsQuote) return `${v.name}=${v.value}`;
+    const esc = v.value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n').replace(/\r/g, '');
+    return `${v.name}="${esc}"`;
+  });
+  return `${MATERIALIZE_HEADER} — DO NOT COMMIT.\n${lines.join('\n')}\n`;
+}
+
+/** Delete a materialized file from a worktree, but ONLY if it's ours (carries
+ *  our header) and not git-tracked — never touch a file we didn't write. */
+function removeStaleEnvFile(wt, rel) {
+  if (isTrackedInGit(wt, rel)) return;
+  const abs = join(wt, rel);
+  try {
+    if (existsSync(abs) && readFileSync(abs, 'utf8').startsWith(MATERIALIZE_HEADER)) {
+      rmSync(abs, { force: true });
+    }
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** Write the decrypted env into ONE worktree. Never call on the wiki worktree. */
+export function materializeInto(wt) {
+  if (!wt || !existsSync(wt)) return;
+  const byFile = new Map();
+  for (const v of values) {
+    if (!isSafeTarget(v.targetFile)) continue;
+    const list = byFile.get(v.targetFile) ?? [];
+    list.push(v);
+    byFile.set(v.targetFile, list);
+  }
+
+  const written = [];
+  for (const [file, list] of byFile) {
+    if (isTrackedInGit(wt, file)) {
+      warn(`env: "${file}" is tracked in git — refusing to write secrets there (gitignore it). Its keys are NOT materialized.`);
+      continue;
+    }
+    try {
+      const abs = join(wt, file);
+      mkdirSync(dirname(abs), { recursive: true });
+      const body = renderEnvFile(list);
+      // Skip an identical rewrite — otherwise every bundle bump touches the
+      // file mtime and hot-restarts a running preview dev-server mid-review.
+      let prior = null;
+      try {
+        prior = readFileSync(abs, 'utf8');
+      } catch {
+        /* new file */
+      }
+      if (prior !== body) writeFileSync(abs, body, { mode: 0o600 });
+      written.push(file);
+    } catch (e) {
+      warn(`env: could not write ${file} into worktree: ${e.message}`);
+    }
+  }
+
+  // Remove any file we ever materialized (this session OR a prior one, via the
+  // persisted knownTargetFiles) that has no keys now — a deleted secret's
+  // plaintext file must not linger, even across a daemon restart.
+  const writtenSet = new Set(written);
+  const candidates = new Set([...(lastFilesByWorktree.get(wt) ?? []), ...knownTargetFiles]);
+  for (const stale of candidates) {
+    if (!writtenSet.has(stale)) removeStaleEnvFile(wt, stale);
+  }
+  for (const f of written) knownTargetFiles.add(f);
+  lastFilesByWorktree.set(wt, written);
+  if (written.length) excludeInWorktree(wt, written);
+}
+
+// ── Uplink scrubbing ───────────────────────────────────────────────────────
+
+/** Redact every known secret value from daemon-posted text. Values shorter
+ *  than the floor ("1", "true") would redact half the stream — skipped. */
+export function scrub(text) {
+  if (typeof text !== 'string' || !text || !values.length) return text;
+  let out = text;
+  for (const v of values) {
+    if (typeof v.value === 'string' && v.value.length >= SCRUB_MIN_LENGTH) {
+      out = out.split(v.value).join(`[REDACTED:${v.name}]`);
+    }
+  }
+  return out;
+}
+
+// ── Roster tick ────────────────────────────────────────────────────────────
+
+let busy = false; // one env operation at a time — ticks are cheap to skip
+
+/**
+ * React to the roster's env block. Returns { changed } — true when the bundle
+ * was (re)materialized so the caller refreshes its worktrees.
+ */
+export async function handleRosterEnv(env, { projectId } = {}) {
+  if (!env || busy) return { changed: false };
+  busy = true;
+  try {
+    await ensureKeypair();
+    if (projectId) cachedProjectId = projectId;
+    // First tick after a restart: warm from the encrypted cache so worktrees
+    // can materialize even if the bundle fetch below fails transiently.
+    if (bundleVersion < 0 && cachedProjectId) await loadCachedEnv(cachedProjectId);
+
+    // 1. Introduce this machine (idempotent server-side). registeredOnce is set
+    // only AFTER the POST lands — a transient failure must retry next poll, not
+    // wedge registration until restart.
+    if (env.status === 'none' && !registeredOnce) {
+      const label = hostname() || 'daemon';
+      try {
+        await post('register', { pubkey: myPubB64(), label });
+      } catch (e) {
+        // A 429 = the project is at its machine cap; retrying every poll would
+        // just hammer it. Stop for this session (a restart re-tries).
+        if (/\(429/.test(e.message)) {
+          registeredOnce = true;
+          warn('env: this project is at its machine limit — env access not requested. Ask an admin to remove an old machine.');
+          return { changed: false };
+        }
+        throw e; // transient — retry next poll (registeredOnce still false)
+      }
+      registeredOnce = true;
+      const fp = pubkeyEmoji(myPubB64());
+      info(`${c.cyan('env')}    · this machine requested env access as ${c.bold(label)}`);
+      note(`  fingerprint ${fp} — an admin approves it in Settings → Environment (compare the emoji).`);
+      return { changed: false };
+    }
+    if (env.status === 'pending') return { changed: false }; // waiting on the admin
+    if (env.status === 'revoked') return { changed: false };
+
+    // 2. Bootstrap: no project keypair exists — this machine creates it.
+    if (env.bootstrapNeeded && (env.status === 'approved' || env.status === 'enrolled' || env.status === 'none')) {
+      if (env.status === 'none') return { changed: false }; // register first, next tick
+      await bootstrapProject();
+      return { changed: false }; // next tick syncs as enrolled
+    }
+    if (env.status !== 'enrolled') return { changed: false };
+
+    // 3. Wrap jobs + rotation + sync — all need the bundle.
+    const needSync = env.bundleVersion !== bundleVersion;
+    if (!needSync && !env.pendingWraps && !env.rotationPending) return { changed: false };
+    const bundle = await fetchBundle();
+    if (!bundle.wrappedPriv || !bundle.projectPub) return { changed: false };
+    projectPriv = openSealed(bundle.wrappedPriv, keypair.publicKey, keypair.privateKey);
+    const projectPub = sodium.from_base64(bundle.projectPub, B64());
+
+    // Execute approved enrollments: seal the priv to each new machine. The
+    // wrap's epoch rides along — the server rejects (stale) if a rotation moved
+    // it since we fetched, so nobody enrolls with a dead key.
+    if (bundle.pendingWraps.length) {
+      const wraps = bundle.pendingWraps.map((p) => ({
+        daemonId: p.daemonId,
+        wrappedPriv: seal(projectPriv, p.pubkey),
+      }));
+      const res = await post('wraps', { pubkey: myPubB64(), keyEpoch: bundle.keyEpoch, wraps });
+      if (res?.stale) note(`${c.cyan('env')} ${c.dim('— wraps raced a rotation; retrying next poll')}`);
+      else ok(`${c.cyan('env')} ${c.dim(`— delivered the key to ${wraps.length} newly approved machine${wraps.length === 1 ? '' : 's'}`)}`);
+    }
+
+    // Decrypt the values we have — carrying each key's VERSION so a rotation can
+    // prove it re-sealed the current value (not one a concurrent write moved).
+    const opened = [];
+    let allOpened = true;
+    for (const k of bundle.keys) {
+      try {
+        const plain = openSealed(k.ciphertext, projectPub, projectPriv);
+        opened.push({ name: k.name, env: k.env, targetFile: k.targetFile, value: sodium.to_string(plain), version: k.version });
+      } catch {
+        allOpened = false;
+        warn(`env: could not open ${k.name} (epoch ${k.keyEpoch}) — skipping; a rotation should heal it`);
+      }
+    }
+
+    // Execute a pending rotation: new keypair, full coverage, all wraps. If we
+    // couldn't open every value, DON'T attempt — a partial rotate would fail
+    // the server's coverage check; let another enrolled daemon (which can open
+    // them) do it. Server serializes concurrent executors via a claim lock.
+    if (bundle.rotationPending) {
+      if (!allOpened) {
+        warn(`env: skipping rotation — this machine can't open every value; another daemon will rotate`);
+        return { changed: false };
+      }
+      const next = sodium.crypto_box_keypair();
+      const nextPubB64 = sodium.to_base64(next.publicKey, B64());
+      const res = await post('rotate', {
+        pubkey: myPubB64(),
+        fromEpoch: bundle.keyEpoch,
+        projectPub: nextPubB64,
+        values: opened.map((v) => ({ name: v.name, env: v.env, ciphertext: seal(sodium.from_string(v.value), nextPubB64), version: v.version })),
+        wraps: bundle.enrolledDaemons.map((d) => ({ daemonId: d.daemonId, wrappedPriv: seal(next.privateKey, d.pubkey) })),
+        ...(bundle.recoveryPub ? { recoverySealed: seal(next.privateKey, bundle.recoveryPub) } : {}),
+      }).catch((e) => {
+        // epoch_stale / value_moved / coverage → a concurrent change; the next
+        // poll re-fetches and retries. Not fatal.
+        note(`${c.cyan('env')} ${c.dim(`— rotation deferred (${e.message}); retrying next poll`)}`);
+        return null;
+      });
+      if (res) ok(`${c.cyan('env')} ${c.dim('— project key rotated (a machine was revoked); next poll syncs the new epoch')}`);
+      return { changed: false }; // resync on the next tick at the new version
+    }
+
+    if (needSync) {
+      values = opened;
+      bundleVersion = bundle.bundleVersion;
+      // Fold the current target files into the persisted known set so stale
+      // cleanup survives a restart (a key deleted while down still gets swept).
+      for (const v of values) knownTargetFiles.add(v.targetFile);
+      if (cachedProjectId) writeCache(cachedProjectId, { values, bundleVersion, knownFiles: [...knownTargetFiles] });
+      ok(`${c.cyan('env')} ${c.dim(`— synced ${values.length} secret${values.length === 1 ? '' : 's'} (env v${bundleVersion})`)}`);
+      return { changed: true };
+    }
+    return { changed: false };
+  } catch (e) {
+    warn(`env sync: ${e.message} — will retry next poll`);
+    return { changed: false };
+  } finally {
+    busy = false;
+  }
+}
+
+/** First machine creates the project keypair + the standing recovery target.
+ *  The recovery passphrase prints ONCE — rotations re-seal to the same
+ *  recovery pub, so this passphrase works forever. */
+async function bootstrapProject() {
+  const project = sodium.crypto_box_keypair();
+  const recovery = sodium.crypto_box_keypair();
+  // Human-typable passphrase: 6 groups of 4 from an unambiguous alphabet.
+  const ALPHA = 'abcdefghjkmnpqrstuvwxyz23456789';
+  const raw = sodium.randombytes_buf(24);
+  const passphrase = Array.from(raw, (b, i) => ALPHA[b % ALPHA.length] + ((i + 1) % 4 === 0 && i < 23 ? '-' : '')).join('');
+  const salt = sodium.randombytes_buf(sodium.crypto_pwhash_SALTBYTES);
+  const kdfKey = sodium.crypto_pwhash(
+    sodium.crypto_secretbox_KEYBYTES,
+    passphrase,
+    salt,
+    sodium.crypto_pwhash_OPSLIMIT_MODERATE,
+    sodium.crypto_pwhash_MEMLIMIT_MODERATE,
+    sodium.crypto_pwhash_ALG_DEFAULT
+  );
+  const nonce = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);
+  const recoverySecret = JSON.stringify({
+    pub: sodium.to_base64(recovery.publicKey, B64()),
+    priv: sodium.to_base64(recovery.privateKey, B64()),
+  });
+  const recoveryBlob = [
+    sodium.to_base64(salt, B64()),
+    sodium.to_base64(nonce, B64()),
+    sodium.to_base64(sodium.crypto_secretbox_easy(sodium.from_string(recoverySecret), nonce, kdfKey), B64()),
+  ].join(':');
+
+  await post('bootstrap', {
+    pubkey: myPubB64(),
+    projectPub: sodium.to_base64(project.publicKey, B64()),
+    selfWrap: seal(project.privateKey, myPubB64()),
+    recoveryPub: sodium.to_base64(recovery.publicKey, B64()),
+    recoveryBlob,
+    recoverySealed: seal(project.privateKey, sodium.to_base64(recovery.publicKey, B64())),
+  });
+
+  console.log('');
+  ok(`${c.cyan('env')} — this machine created the project's env keypair.`);
+  console.log(`  ${c.bold('RECOVERY CODE')} ${c.dim('(shown ONCE — save it in a password manager):')}`);
+  console.log(`  ${c.bold(c.yellow(passphrase))}`);
+  note('  If every enrolled machine is ever lost, this code is the only way back into the secrets.');
+  console.log('');
+}

package/bin/lib/fleet.mjs

@@ -55,10 +55,24 @@ import { reapOrphanPreviews } from './preview.mjs';
 import { preflight } from './preflight.mjs';
 import { connectStream } from './stream.mjs';
 import { ensureVault, syncVault } from './vault.mjs';
+import {
+  envQueryParams,
+  handleRosterEnv,
+  materializeInto,
+  scrub as envScrub,
+} from './env.mjs';
 
 async function fetchRoster(haveIds) {
   const url = new URL(FLEET_URL);
   if (haveIds.length) url.searchParams.set('have', haveIds.join(','));
+  // Env-sync identity + materialized version (the Settings "env vN" chip).
+  try {
+    for (const [k, v] of Object.entries(await envQueryParams())) {
+      if (v) url.searchParams.set(k, v);
+    }
+  } catch {
+    /* env identity is best-effort — the poll must never fail on it */
+  }
   // An explicit User-Agent is required: Node's default ("node"/empty) trips
   // Cloudflare Bot Fight Mode (403). A descriptive product UA passes.
   const res = await fetch(url, {
@@ -117,6 +131,7 @@ async function runFleetWorker({ agentId, label, cwd, baseRef, getToken, getHasWo
     }
     if (!resuming && needsReset) {
       resetWorktree(cwd, baseRef); // clean slate for a new task
+      materializeInto(cwd); // reset wiped the env files (git clean -fd) — rewrite
       needsReset = false;
     }
     const { dir, path: mcpConfig } = mcpConfigFor(token, getMcpUrl());
@@ -441,6 +456,14 @@ export async function runFleetDaemon() {
     const now = Date.now();
     if (!force && now - lastProgressAt < 600) return;
     lastProgressAt = now;
+    // Uplink scrub: narration/labels can quote repo content, and repo content
+    // can contain a synced secret — redact known values before anything leaves
+    // this machine.
+    const safe = {
+      ...body,
+      ...(typeof body.activity === 'string' ? { activity: envScrub(body.activity) } : {}),
+      ...(Array.isArray(body.recent) ? { recent: body.recent.map((s) => envScrub(s)) } : {}),
+    };
     try {
       await fetch(WIKI_PROGRESS_URL, {
         method: 'POST',
@@ -450,7 +473,7 @@ export async function runFleetDaemon() {
           'Content-Type': 'application/json',
         },
         signal: AbortSignal.timeout(15_000),
-        body: JSON.stringify(body),
+        body: JSON.stringify(safe),
       });
     } catch {
       /* best-effort — a dropped frame is harmless, the next one supersedes it */
@@ -575,6 +598,8 @@ export async function runFleetDaemon() {
                 // Powers the GitHub blob links behind every cited file path.
                 repoFullName: originSlug(repoRoot) || undefined,
                 warn,
+                // Redact synced secrets a page may have quoted from the repo.
+                scrub: envScrub,
               });
               if (r.skipped) note(`${c.cyan('wiki')} ${c.dim('— vault unchanged, nothing to sync')}`);
               else
@@ -815,6 +840,11 @@ export async function runFleetDaemon() {
           fail(`could not create worktree for "${a.name}": ${e.message}`);
           continue;
         }
+        try {
+          materializeInto(wt); // synced env into the fresh worktree
+        } catch {
+          /* best-effort */
+        }
         const colorFn = LABEL_COLORS[joinCount++ % LABEL_COLORS.length];
         const label = colorFn(`[${a.name}]`);
         const state = { alive: true, child: null };
@@ -860,6 +890,21 @@ export async function runFleetDaemon() {
     for (const j of roster.regroundJobs ?? []) enqueueReground(j.intentId, j.prUrl, j.title);
     void drainWiki();
 
+    // Env sync tick: register/bootstrap/wrap/rotate/sync as the roster block
+    // dictates (self-guarded — one operation at a time, errors retry next
+    // poll). A fresh bundle rematerializes every AGENT worktree; the wiki
+    // worktree NEVER gets env (the cartographer doesn't need secrets).
+    void handleRosterEnv(roster.env, { projectId: roster.project?.id }).then(({ changed }) => {
+      if (!changed) return;
+      for (const [, w] of workers) {
+        try {
+          materializeInto(w.wt);
+        } catch {
+          /* best-effort */
+        }
+      }
+    });
+
     // Stop workers whose agent left the roster (removed in the app).
     for (const [id, w] of [...workers]) {
       if (!rosterIds.has(id)) {

package/bin/lib/live.mjs

@@ -34,6 +34,7 @@ import { c, info, ok, warn } from './ui.mjs';
 import { sleep } from './claude.mjs';
 import { git, resetWorktree, isValidBranch } from './git.mjs';
 import { loadPreviewConfig, startPreview } from './preview.mjs';
+import { materializeInto, scrub as envScrub } from './env.mjs';
 
 // Register a branch preview's tunnel URL with Flowviant (fleet-authed). The
 // reviewer then drives it via "Open live preview" in the node.
@@ -92,7 +93,9 @@ function postPreviewNote(intentId, text) {
       'Content-Type': 'application/json',
     },
     signal: AbortSignal.timeout(10_000),
-    body: JSON.stringify({ intentId, text }),
+    // Scrub: preview failure reasons can quote dev-server output, which can
+    // echo env values.
+    body: JSON.stringify({ intentId, text: envScrub(text) }),
   }).catch(() => {});
 }
 
@@ -143,7 +146,12 @@ self-report becomes your DELIVERY CARD in the task thread — it's what the team
 reads to confirm done, so write it for them, not for a log. A live preview of
 your branch is started for you automatically — you do NOT need to open a tunnel
 or register a live target. NEVER merge — a human confirms done in the thread
-(the merge card) and the merge runs separately.`;
+(the merge card) and the merge runs separately.
+SECRETS: env files (.env, .dev.vars, …) in your worktree hold the team's synced
+secrets. Their VALUES must NEVER appear in evidence, progress reports, blocker
+questions, delivery summaries, commits, or PRs — reference keys by NAME only
+(e.g. "set STRIPE_KEY"). Never screenshot a terminal or page that displays a
+credential, and never commit an env file.`;
 
 function seedPrompt(runId, brief, transcript, resumedInPlace) {
   return [
@@ -383,6 +391,7 @@ export async function runLiveTask({ mcpUrl, token, cwd, baseRef, isAlive, resume
   } else if (!resuming && !resumedInPlace) {
     resetWorktree(cwd, baseRef);
   }
+  materializeInto(cwd); // resets wipe the synced env files — rewrite them
   writeTaskMarker(cwd, intentId);
 
   if (resumedInPlace) {
@@ -480,7 +489,9 @@ export async function runLiveTask({ mcpUrl, token, cwd, baseRef, isAlive, resume
       await mcpCall(mcpUrl, token, 'stream_turn', {
         runId,
         turnId,
-        text: turnText.trim(),
+        // Uplink scrub: the model's narration can quote file contents, and a
+        // file can contain a synced secret — redact before it leaves the box.
+        text: envScrub(turnText.trim()),
         createdAt: turnAt,
       }).catch(() => {});
     }

package/bin/lib/vault.mjs

@@ -108,7 +108,7 @@ function commitVault(dir, message) {
  * upload (the sync state is only advanced after EVERY request lands, so a
  * partial failure re-uploads next time — server upserts are idempotent).
  */
-export async function syncVault({ dir, url, token, userAgent, finalize, groundedAtSha, repoFullName, warn = () => {} }) {
+export async function syncVault({ dir, url, token, userAgent, finalize, groundedAtSha, repoFullName, warn = () => {}, scrub = (t) => t }) {
   const walkErrors = { count: 0 };
   const found = walkMd(dir, dir, [], walkErrors).sort();
   if (walkErrors.count > 0 && found.length === 0) {
@@ -155,6 +155,10 @@ export async function syncVault({ dir, url, token, userAgent, finalize, grounded
       carry(p, 'unreadable');
       continue;
     }
+    // Uplink scrub: the cartographer quotes real repo files, and a repo file
+    // can contain a synced secret — redact known values before upload. The
+    // hash is computed on the SCRUBBED text so the diff state stays coherent.
+    text = scrub(text);
     if (Buffer.byteLength(text) > MAX_FILE_BYTES) {
       carry(p, 'exceeds 256KB');
       continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.26.0",
+  "version": "0.27.1",
   "description": "Run your own Claude Code as headless build agents for Flowviant — on your own credentials. Claims dispatched work, opens PRs, captures review evidence, and routes questions back to you.",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.0",
+    "libsodium-wrappers": "^0.8.4",
     "ws": "^8.18.0"
   },
   "keywords": [