flowviant 0.102.2 → 0.104.0

package/bin/lib/fleetWake.mjs

@@ -0,0 +1,45 @@
+/**
+ * THE RECONCILE WAIT — idle until the next poll deadline OR a push wake,
+ * whichever comes first.
+ *
+ * Split out of fleet.mjs (SOLID audit 2026-09-26, F038): a small piece of
+ * timing state (the pending resolver, and a wake that landed mid-reconcile)
+ * that the loop only ever touches through these two functions. The socket
+ * itself is stream.mjs's; this is what a wake DOES to the loop.
+ */
+
+import { RECONCILE_SECONDS } from './config.mjs';
+
+export function createReconcileWait() {
+  // ── Push channel: a server wake short-circuits the reconcile sleep so a job is
+  // picked up in ~a round trip instead of on the next poll. The socket only
+  // nudges — we still fetch the roster below — so it's pure latency, and the
+  // poll stays the fallback whenever the socket is down. `waitReconcile()`
+  // resolves on either a wake or the RECONCILE_SECONDS timeout, whichever first.
+  let wakeSignal = null; // { resolve, timer } while the loop is idling
+  let pendingWake = false; // a wake that landed mid-reconcile — honored next wait
+  const fireWake = () => {
+    if (wakeSignal) {
+      clearTimeout(wakeSignal.timer);
+      const { resolve } = wakeSignal;
+      wakeSignal = null;
+      resolve();
+    } else {
+      pendingWake = true; // not idling right now; don't lose the wake
+    }
+  };
+  const waitReconcile = () => {
+    if (pendingWake) {
+      pendingWake = false;
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        wakeSignal = null;
+        resolve();
+      }, RECONCILE_SECONDS * 1000);
+      wakeSignal = { resolve, timer };
+    });
+  };
+  return { fireWake, waitReconcile };
+}

package/bin/lib/fleetWire.mjs

@@ -0,0 +1,46 @@
+/**
+ * EVERY `/fleet/*` ENDPOINT, derived from the one roster URL.
+ *
+ * One place configures the API base (`FLEET_URL`, overridable by
+ * `FLOWVIANT_FLEET_URL`, ending in `/fleet/agents`) and every other daemon
+ * endpoint is that URL with its final `agents` segment swapped — so a
+ * self-hosted server, or the `/api` → `/api/v2` alias, is honoured by every
+ * lane at once.
+ *
+ * ONE HOME (SOLID audit 2026-09-26, F166). The swap was spelled
+ * `FLEET_URL.replace(/\/agents\/?$/, '/…')` forty-nine times across eighteen
+ * files; a change to the roster URL's shape, or to what counts as a valid
+ * endpoint name, was forty-nine edits.
+ *
+ * WHAT IT VALIDATES, AND WHAT IT DELIBERATELY DOES NOT. An endpoint NAME that
+ * is not a plain lowercase path is a programming error and throws. A ROSTER
+ * URL that does not end in `/agents` is NOT refused here: endpoints are
+ * derived while modules load (fleetReports.mjs, landed.mjs, login.mjs), and a throw
+ * there took down every command — `help` and `projects` included — over a
+ * setting only the daemon's lanes use (measured while making this change). Such
+ * a URL comes back unchanged, exactly as the forty-nine copies answered, and
+ * the roster poll against it is the first thing to fail and say so.
+ *
+ * The push channel (`STREAM_URL` in config.mjs) is the one derivation kept
+ * apart: it switches the scheme to ws and keeps a trailing slash.
+ *
+ * A leaf on purpose: it takes the roster URL as an argument rather than
+ * importing `config.mjs`, so modules that are handed a `fleetUrl` (the
+ * artifact reporter, the knowledge fetcher, the tray's remote status) do not
+ * gain a config import to name a path.
+ */
+
+const ROSTER_TAIL = /\/agents\/?$/;
+const NAME = /^[a-z0-9-]+(\/[a-z0-9-]+)*$/;
+
+/**
+ * The `/fleet/<name>` endpoint beside the roster URL `rosterUrl`
+ * (`https://api.flowviant.com/api/fleet/agents` → `…/api/fleet/<name>`). A
+ * trailing slash on the roster URL is accepted and not carried over.
+ */
+export function fleetEndpoint(name, rosterUrl) {
+  if (typeof name !== 'string' || !NAME.test(name)) {
+    throw new TypeError(`fleetEndpoint: "${name}" is not a /fleet endpoint name`);
+  }
+  return String(rosterUrl).replace(ROSTER_TAIL, `/${name}`);
+}

package/bin/lib/git.mjs

@@ -250,12 +250,43 @@ export function detectBaseRef(repoRoot) {
     }
   }
   try {
-    return `origin/${git(['rev-parse', '--abbrev-ref', 'HEAD'], repoRoot)}`;
+    return usableBaseRef(repoRoot, `origin/${git(['rev-parse', '--abbrev-ref', 'HEAD'], repoRoot)}`);
   } catch {
     return 'HEAD';
   }
 }
 
+/**
+ * A base ref an agent's worktree can actually be cut from.
+ *
+ * `origin/<branch>` is the right base when the repo HAS an origin. A repo with
+ * no remote (a local-only project — the owner's "Death Note - Roblox",
+ * 2026-09-25) has no `origin/*` refs at all, and cutting a worktree from one
+ * fails; every agent turn then ended "nothing" in a second. So: the ref itself
+ * when it resolves to a commit, else the LOCAL branch of the same name, else
+ * the ref unchanged (and the worktree step says why in git's words).
+ */
+export function usableBaseRef(repoRoot, ref) {
+  const resolves = (r) => {
+    try { git(['rev-parse', '--verify', '--quiet', `${r}^{commit}`], repoRoot); return true; } catch { return false; }
+  };
+  if (resolves(ref)) return ref;
+  const local = String(ref).replace(/^origin\//, '');
+  if (local !== ref && resolves(local)) return local;
+  return ref;
+}
+
+/** True when the repository has at least one commit (HEAD resolves). */
+export function hasCommits(repoRoot) {
+  try { git(['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'], repoRoot); return true; } catch { return false; }
+}
+
+/** The last line git wrote to stderr for a failed call, or its message. */
+export function gitFailure(error) {
+  const stderr = String(error?.stderr ?? '').trim().split('\n').filter(Boolean);
+  return stderr.at(-1) ?? String(error?.message ?? error).split('\n')[0];
+}
+
 /**
  * The BRANCH NAME behind a base ref.
  *
@@ -292,8 +323,8 @@ export function resetWorktree(wt, baseRef) {
  * the vault is what first needed it — materialized `.env` files had to be
  * untracked AND unstageable — but it is a plain `git info/exclude` helper with
  * no crypto, no bundle and no opinion about secrets, and the vault is deleted.
- * Its one surviving caller is `work.mjs`, which hides a tab's `.flowviant/`
- * upload directory with it.
+ * Its callers are the work manager (`work.mjs`, before a turn's artifacts)
+ * and `workAttachments.mjs`, which hide a tab's `.flowviant/` paths with it.
  *
  * WHY IT IS NOT `.git/worktrees/<name>/info/exclude`: it used to resolve the
  * worktree's own gitdir and write there, on the belief that the file "applies

package/bin/lib/gitMergeIdentity.mjs

@@ -0,0 +1,51 @@
+/**
+ * THE IDENTITY A DAEMON MERGE COMMIT IS WRITTEN UNDER (2026-09-26, SOLID F165).
+ *
+ * A merge COMMIT needs a git identity and the machine may have none. Prefer the
+ * operator's own config; fall back to the daemon's, so a bare machine does not
+ * fail the fold with "Please tell me who you are".
+ *
+ * Split out because the session ship lane (workShip.mjs) and the agent merge
+ * lane (workAgentMerges.mjs) each carried a copy of the probe and the four
+ * fallback variables — an identity-policy change needed two edits. Both lanes
+ * now take their `gitMerge` from `gitMergeIn(repoRoot)`; their merge decisions
+ * are their own.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { git } from './git.mjs';
+
+export const DAEMON_GIT_IDENTITY = Object.freeze({
+  GIT_AUTHOR_NAME: 'Flowviant',
+  GIT_AUTHOR_EMAIL: 'daemon@flowviant.com',
+  GIT_COMMITTER_NAME: 'Flowviant',
+  GIT_COMMITTER_EMAIL: 'daemon@flowviant.com',
+});
+
+/** The env a merge in `repoRoot` needs: null when the operator's config names a
+ *  user.email (git uses theirs), the daemon's identity when it names none. */
+export function mergeIdentityEnv(repoRoot) {
+  try {
+    git(['config', 'user.email'], repoRoot);
+    return null;
+  } catch {
+    return DAEMON_GIT_IDENTITY;
+  }
+}
+
+/**
+ * A `gitMerge(args, cwd)` for a checkout rooted at `repoRoot`: runs `git args`
+ * in `cwd` (a throwaway worktree, usually) under the identity the probe finds.
+ * The probe runs per call, so an identity configured mid-job is heard.
+ */
+export function gitMergeIn(repoRoot) {
+  return (args, cwd) => {
+    const idEnv = mergeIdentityEnv(repoRoot);
+    return execFileSync('git', args, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      ...(idEnv ? { env: { ...process.env, ...idEnv } } : {}),
+    });
+  };
+}

package/bin/lib/grant.mjs

@@ -46,8 +46,10 @@ export const GRANT_SKEW_MS = 60_000;
 const b64url = (buf) => buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
 
 /** Constant-time over sha256 digests, so length never leaks and a missing
- *  value costs the same as a wrong one. Never `===` on a signature. */
-function sameDigest(a, b) {
+ *  value costs the same as a wrong one. Never `===` on a signature or a
+ *  password. The daemon's ONE secret comparison: the grant signature below and
+ *  the gate's Basic password (`previewGatePolicy.mjs`) both ask it. */
+export function sameSecret(a, b) {
   try {
     const da = createHash('sha256').update(String(a ?? '')).digest();
     const db = createHash('sha256').update(String(b ?? '')).digest();
@@ -80,7 +82,7 @@ export function verifyGrant(raw, { secret, shareId, nowMs, skewMs } = {}) {
   }
 
   const expected = b64url(createHmac('sha256', String(secret)).update(DOMAIN + body).digest());
-  if (!sameDigest(sig, expected)) return { ok: false, reason: 'sig' };
+  if (!sameSecret(sig, expected)) return { ok: false, reason: 'sig' };
 
   let payload;
   try {

package/bin/lib/help.mjs

@@ -9,127 +9,12 @@
  * and `<command> --help` print one entry, and an unknown word is refused with
  * the nearest command instead of being served.
  *
- * THE TABLE IS PINNED TO THE DISPATCH: help.test.mjs reads every
- * `process.argv[2] === '<name>'` in cli.mjs and fails if one is missing here
- * (or listed here and not dispatched). `hidden` rows are real commands a
- * person rarely types (an agent calls `shot`; `mcp` manages connectors from a
- * script); they answer `help <name>` but stay off the main screen.
+ * THE TABLE is commandSpecs.mjs (one list for help, the --dir checkout policy
+ * and cli.mjs's dispatch); this module renders it and answers a slip.
  */
 
 import { c } from './ui.mjs';
-
-export const COMMANDS = [
-  {
-    name: 'start',
-    usage: 'flowviant [start] [--project <name|id>]',
-    summary: "Serve this repo's project: run agents and Workbench tabs here. Plain `flowviant` does the same.",
-    details: [
-      'Run it inside the repository you connected. The first run in a new repo asks you to approve this computer.',
-      '--project <name|id>   serve that stored project instead of the one this repo is bound to',
-    ],
-    group: 'run',
-  },
-  {
-    name: 'login',
-    usage: 'flowviant login [--no-start]',
-    summary: 'Connect this repo to a project: approve the code in your browser, then start serving.',
-    details: ['--no-start   save the connection without starting the daemon'],
-    group: 'run',
-  },
-  {
-    name: 'stop',
-    usage: 'flowviant stop [--project <name|id>]',
-    summary: 'Stop every flowviant daemon on this computer (or just one project’s).',
-    group: 'run',
-  },
-  {
-    name: 'status',
-    usage: 'flowviant status',
-    summary: 'Each project connected here: its repo, whether it is running and serving, and its live agents.',
-    details: ['--json   the machine-readable form the Windows tray reads'],
-    group: 'look',
-  },
-  {
-    name: 'logs',
-    usage: 'flowviant logs [-f] [--project <name|id>]',
-    summary: "The daemon's log for this repo's project.",
-    details: ['-f, --follow   keep printing new lines as they are written', '-n <lines>     how many lines to show first (default 80)'],
-    group: 'look',
-  },
-  {
-    name: 'open',
-    usage: 'flowviant open [--project <name|id>]',
-    summary: "Open this project's board in your browser (prints the link too).",
-    group: 'look',
-  },
-  {
-    name: 'projects',
-    usage: 'flowviant projects',
-    summary: 'Every project this computer has a login for, and the repo each one serves.',
-    group: 'look',
-  },
-  {
-    name: 'machines',
-    usage: 'flowviant machines [--remove <id> | --forget <id>] [--yes]',
-    summary: 'Every computer that serves your projects. On a terminal, a menu to disconnect or forget one here.',
-    group: 'look',
-  },
-  {
-    name: 'doctor',
-    usage: 'flowviant doctor',
-    summary: 'Check what this computer needs: git, a signed-in CLI, a connection to Flowviant, a running daemon.',
-    group: 'look',
-  },
-  {
-    name: 'update',
-    usage: 'flowviant update',
-    summary: 'Install the newest flowviant now. It also updates itself when idle.',
-    group: 'manage',
-  },
-  {
-    name: 'clean',
-    usage: 'flowviant clean',
-    summary: 'Delete the kept agent worktrees under ~/.flowviant/worktrees. Stop the daemon first.',
-    group: 'manage',
-  },
-  {
-    name: 'uninstall',
-    usage: 'flowviant uninstall [--purge] [--yes]',
-    summary: 'Remove every flowviant copy on this computer. Logins are kept unless you add --purge.',
-    details: ['--purge   also disconnect this computer from its projects and delete ~/.flowviant', '--yes     do not ask first'],
-    group: 'manage',
-  },
-  {
-    name: 'gh-auth',
-    usage: 'flowviant gh-auth',
-    summary: 'Sign in the GitHub CLI flowviant uses to open pull requests.',
-    group: 'manage',
-  },
-  {
-    name: 'version',
-    usage: 'flowviant --version',
-    summary: 'Print the installed version.',
-    group: 'manage',
-  },
-  {
-    name: 'help',
-    usage: 'flowviant help [command]',
-    summary: 'This list, or one command in detail.',
-    group: 'manage',
-  },
-  {
-    name: 'shot',
-    usage: 'flowviant shot <url> [--out <file>]',
-    summary: 'Screenshot a running page with a headless browser (agents use it to see their change).',
-    hidden: true,
-  },
-  {
-    name: 'mcp',
-    usage: 'flowviant mcp <subcommand>',
-    summary: "Manage the project's MCP connectors from a script.",
-    hidden: true,
-  },
-];
+import { COMMANDS } from './commandSpecs.mjs';
 
 const GROUPS = [
   ['run', 'Run'],
@@ -137,13 +22,6 @@ const GROUPS = [
   ['manage', 'Manage'],
 ];
 
-const ALIASES = { '--version': 'version', '-v': 'version', '--help': 'help', '-h': 'help' };
-
-export function findCommand(name) {
-  const key = ALIASES[name] ?? name;
-  return COMMANDS.find((cmd) => cmd.name === key) ?? null;
-}
-
 /** The main screen: every visible command, grouped, one line each. */
 export function renderHelp(version) {
   const width = Math.max(...COMMANDS.filter((cmd) => !cmd.hidden).map((cmd) => cmd.name.length));