flowviant 0.116.0 → 0.117.0

package/bin/lib/fleetReports.mjs

@@ -6,18 +6,20 @@
  *
  * Split out of fleet.mjs (SOLID audit 2026-09-26, F038). Each lane is its own
  * throttle, its own dedup against the last ACCEPTED payload, and its own
- * "the server refused for good — quiet until restart" flag; all of that is
- * module state, and none of it is the reconcile loop's business. The loop
- * fires each one and forgets it (`void`), which is the one contract they all
- * keep: a readout must never throw into, or delay, the poll.
+ * "the server refused for good — quiet until restart" flag; since 2026-10-10
+ * (F087) that state lives in one `createReportLane` closure per lane rather
+ * than four hand-kept sets of module `let`s, and none of it is the reconcile
+ * loop's business. The loop fires each one and forgets it (`void`), which is
+ * the one contract they all keep: a readout must never throw into, or delay,
+ * the poll.
  *
  * Every lane is a DAEMON→SERVER report, so none needs a floor: an older server
  * 404s once and the lane goes quiet; an older daemon simply never posts.
  */
 
-import { FLEET_URL, FLEET_TOKEN, USER_AGENT } from './config.mjs';
+import { FLEET_URL } from './config.mjs';
 import { fleetEndpoint } from './fleetWire.mjs';
-import { postToFleet } from './fleetPost.mjs';
+import { fleetRequest, postToFleet } from './fleetPost.mjs';
 import { myPubB64 } from './boxIdentity.mjs';
 import { scanEnvForScrub } from './env.mjs';
 import { machineSnapshot } from './resources.mjs';
@@ -28,6 +30,78 @@ import { claudeAuthContext } from './claudeAuth.mjs';
 import { readBaseTools, toolReadout } from './projectTools.mjs';
 import { runnerToolCapabilities } from './projectToolRuntimes.mjs';
 
+/**
+ * ONE READOUT LANE (audit 2026-10-10, F087/F752). The four readouts below —
+ * local sessions, repo state, env and tools — were four hand copies of one
+ * state machine over module-level `let`s, and their gate orders and refusal
+ * rules had drifted without a word. The machine, once:
+ *
+ *   1. latched quiet? say nothing (`scanBeforeGate` moves this AFTER the
+ *      build — the env lane, whose scan feeds the scrubber and must run
+ *      whether or not anything can be posted);
+ *   2. scanned less than `scanMs` ago? say nothing, else stamp the scan;
+ *   3. build the payload STRING — a throw says nothing (a readout must never
+ *      throw into the poll), and null means there is nothing to say;
+ *   4. equal to the last payload the server ACCEPTED (and, with `resendMs`,
+ *      accepted inside that window)? say nothing;
+ *   5. POST it with the machine credential;
+ *   6. a status `isPermanent` names latches the lane quiet until restart;
+ *   7. remember the payload only on a 2xx — anything else forgets it, so the
+ *      next scan retries rather than dedup-suppressing a report nobody got.
+ *
+ * Each lane's real differences are PARAMETERS, kept exactly as they were:
+ * only local sessions has a resend window; local sessions and repo state
+ * latch on a 404 alone, env and tools on `envReportIsPermanent`. Unifying the
+ * latch rule (wire.md's one "a permanent 4xx is delivered") stays an open
+ * call: a 400 latch would silence repo-state for the life of the process
+ * after one bad payload.
+ *
+ * Returns the lane's verdict — 'quiet' | 'throttled' | 'scan-failed' |
+ * 'nothing' | 'deduped' | 'accepted' | 'retry' | 'stopped' — which the
+ * daemon ignores (every caller is a bare `void`) and the tests drive.
+ */
+function createReportLane({
+  endpoint,
+  scanMs = 60_000,
+  resendMs = null,
+  timeoutMs = 15_000,
+  isPermanent = (status) => status === 404,
+  scanBeforeGate = false,
+}) {
+  const url = fleetEndpoint(endpoint, FLEET_URL);
+  let unsupported = false; // the server refused for good — quiet until restart
+  let scanAt = 0;
+  let sent = null; // the last payload the server ACCEPTED, stringified
+  let sentAt = 0;
+  const report = async (build) => {
+    if (!scanBeforeGate && unsupported) return 'quiet';
+    if (Date.now() - scanAt < scanMs) return 'throttled';
+    scanAt = Date.now();
+    let payload;
+    try {
+      payload = build();
+    } catch {
+      return 'scan-failed';
+    }
+    if (scanBeforeGate && unsupported) return 'quiet';
+    if (payload == null) return 'nothing';
+    if (payload === sent && (resendMs == null || Date.now() - sentAt < resendMs)) return 'deduped';
+    const r = await fleetRequest(url, { body: payload, timeoutMs });
+    if (isPermanent(r.status)) {
+      unsupported = true;
+      return 'stopped';
+    }
+    sent = r.ok ? payload : null;
+    sentAt = r.ok ? Date.now() : 0;
+    return r.ok ? 'accepted' : 'retry';
+  };
+  /** "Look again on the next beat" — clears the throttle, nothing else. */
+  report.rescan = () => {
+    scanAt = 0;
+  };
+  return report;
+}
+
 /**
  * Terminal-session presence: tell the server which Claude sessions exist in
  * this repo (localSessions.mjs reads them off Claude's own on-disk state), so
@@ -40,57 +114,17 @@ import { runnerToolCapabilities } from './projectToolRuntimes.mjs';
  * process stops asking (a deploy that adds it also restarts nothing on this
  * machine, so silence-until-restart costs one daemon restart, not a feature).
  */
-const LOCAL_SESSIONS_URL = fleetEndpoint('local-sessions', FLEET_URL);
-const LOCAL_SESSIONS_SCAN_MS = 60_000;
 // The web hides a report older than 10 minutes (presence must not linger as
 // fact after the machine dies), so an UNCHANGED report is re-sent inside that
 // window anyway — the re-send is the machine's heartbeat on this fact, and
 // suppressing it entirely would blank the strip while everything still holds.
-const LOCAL_SESSIONS_RESEND_MS = 5 * 60_000;
-let localSessionsUnsupported = false; // the server 404'd — quiet until restart
-let localSessionsScanAt = 0;
-let localSessionsSent = null; // last payload the server ACCEPTED, stringified
-let localSessionsSentAt = 0;
-export async function maybeReportLocalSessions({ repoRoot, excludeDirs, excludeIds }) {
-  if (localSessionsUnsupported) return;
-  if (Date.now() - localSessionsScanAt < LOCAL_SESSIONS_SCAN_MS) return;
-  localSessionsScanAt = Date.now();
-  let payload;
-  try {
-    // scanLocalSessions orders deterministically, so this string only changes
-    // when the facts on disk do — the dedup below compares whole payloads.
-    payload = JSON.stringify({
-      sessions: scanLocalSessions({ repoRoot, excludeDirs, excludeIds }),
-    });
-  } catch {
-    return; // presence must never throw into the poll loop
-  }
-  if (payload === localSessionsSent && Date.now() - localSessionsSentAt < LOCAL_SESSIONS_RESEND_MS)
-    return;
-  try {
-    const res = await fetch(LOCAL_SESSIONS_URL, {
-      method: 'POST',
-      headers: {
-        Authorization: `Bearer ${FLEET_TOKEN}`,
-        'User-Agent': USER_AGENT,
-        'Content-Type': 'application/json',
-      },
-      signal: AbortSignal.timeout(15_000),
-      body: payload,
-    });
-    if (res.status === 404) {
-      localSessionsUnsupported = true; // older server — it REPLACED nothing here
-      return;
-    }
-    // Only an accepted report counts as sent; anything else forgets the
-    // last-sent payload so the next pass retries instead of dedup-suppressing
-    // a report the server never received.
-    localSessionsSent = res.ok ? payload : null;
-    localSessionsSentAt = res.ok ? Date.now() : 0;
-  } catch {
-    localSessionsSent = null;
-    localSessionsSentAt = 0;
-  }
+const localSessionsLane = createReportLane({ endpoint: 'local-sessions', resendMs: 5 * 60_000 });
+export function maybeReportLocalSessions({ repoRoot, excludeDirs, excludeIds }) {
+  // scanLocalSessions orders deterministically, so this string only changes
+  // when the facts on disk do — the dedup compares whole payloads.
+  return localSessionsLane(() =>
+    JSON.stringify({ sessions: scanLocalSessions({ repoRoot, excludeDirs, excludeIds }) })
+  );
 }
 
 /**
@@ -108,32 +142,24 @@ export async function maybeReportLocalSessions({ repoRoot, excludeDirs, excludeI
  * exists — so re-posting an unchanged list would be a write per machine per
  * five minutes to say nothing at all.
  */
-const REPO_STATE_URL = fleetEndpoint('repo-state', FLEET_URL);
-const REPO_STATE_SCAN_MS = 60_000;
-let repoStateUnsupported = false; // the server 404'd — quiet until restart
-let repoStateScanAt = 0;
-let repoStateSent = null; // last payload the server ACCEPTED, stringified
-export async function maybeReportRepoState({ repoRoot, baseRef }) {
-  if (repoStateUnsupported) return;
-  if (Date.now() - repoStateScanAt < REPO_STATE_SCAN_MS) return;
-  repoStateScanAt = Date.now();
-  let payload;
-  try {
+const repoStateLane = createReportLane({ endpoint: 'repo-state' });
+export function maybeReportRepoState({ repoRoot, baseRef }) {
+  return repoStateLane(() => {
     // The PARAM, and nothing else: this function sits at MODULE scope, where
     // runFleetDaemon's `getBaseRef` closure does not exist. An earlier version
-    // reached for it anyway, the ReferenceError landed in the catch below —
-    // written for an unreadable repo, silent by design — and this endpoint was
-    // never once posted to. The caller reads the loop's live `baseRef` at call
-    // time, so the value here is always current.
+    // reached for it anyway, the ReferenceError landed in the lane's build
+    // catch — written for an unreadable repo, silent by design — and this
+    // endpoint was never once posted to. The caller reads the loop's live
+    // `baseRef` at call time, so the value here is always current.
     const state = repoState(repoRoot, baseRef);
-    if (!state) return; // not readable — say nothing rather than say "none"
+    if (!state) return null; // not readable — say nothing rather than say "none"
     /**
      * WHICH CREDENTIAL THIS MACHINE'S CLI RESOLVES, on the same beat.
      *
      * It rides this report rather than getting an endpoint of its own because
      * it is the same KIND of fact — something only the machine can see, pushed
      * because a pull client can never be asked — and it inherits this
-     * function's three economies for free: scanned once a minute, deduped
+     * lane's three economies for free: scanned once a minute, deduped
      * against the last ACCEPTED payload, and silent forever once an older
      * server 404s.
      *
@@ -149,32 +175,8 @@ export async function maybeReportRepoState({ repoRoot, baseRef }) {
      * report, and an older SERVER strips the unknown key in its zod parse and
      * stores the rest exactly as before.
      */
-    payload = JSON.stringify({ ...state, auth: claudeAuthContext() });
-  } catch {
-    return; // a readout must never throw into the poll loop
-  }
-  if (payload === repoStateSent) return;
-  try {
-    const res = await fetch(REPO_STATE_URL, {
-      method: 'POST',
-      headers: {
-        Authorization: `Bearer ${FLEET_TOKEN}`,
-        'User-Agent': USER_AGENT,
-        'Content-Type': 'application/json',
-      },
-      signal: AbortSignal.timeout(15_000),
-      body: payload,
-    });
-    if (res.status === 404) {
-      repoStateUnsupported = true; // older server — nothing was replaced here
-      return;
-    }
-    // Only an ACCEPTED report counts: anything else forgets it so the next
-    // pass retries rather than dedup-suppressing a report nobody received.
-    repoStateSent = res.ok ? payload : null;
-  } catch {
-    repoStateSent = null;
-  }
+    return JSON.stringify({ ...state, auth: claudeAuthContext() });
+  });
 }
 
 /**
@@ -247,16 +249,24 @@ export async function maybeReportRepoState({ repoRoot, baseRef }) {
  * Pure and exported so the decision can be proved without a credential, a
  * server or a poll — the same shape `shouldStop` and `createHolderWatch` keep
  * in holder.mjs.
+ *
+ * DELIBERATELY NARROWER than fleetWire.mjs's `isConsideredRefusal` (every 4xx
+ * but 408/429), which the settle lanes read: a settle that treats a 401 as
+ * decided loses one body, a readout that latches on it goes dark for the life
+ * of the process. Two vocabularies, each named, never folded together.
  */
 export function envReportIsPermanent(status) {
   return status === 400 || status === 404 || status === 422;
 }
 
-const ENV_REPORT_URL = fleetEndpoint('env-report', FLEET_URL);
-const ENV_REPORT_SCAN_MS = 60_000;
-let envReportUnsupported = false; // the server refused permanently — quiet until restart
-let envReportScanAt = 0;
-let envReportSent = null; // the last report the server ACCEPTED, stringified
+// Scans BEFORE the latch: the scrubber has no dedup and must reflect the
+// newest read every time, so a server that cannot take the report never costs
+// this box its redaction (see the docblock above `envReportIsPermanent`).
+const envLane = createReportLane({
+  endpoint: 'env-report',
+  isPermanent: envReportIsPermanent,
+  scanBeforeGate: true,
+});
 /**
  * Returns a one-word VERDICT — 'throttled' | 'scan-failed' | 'quiet' |
  * 'deduped' | 'accepted' | 'retry' | 'stopped'. The daemon ignores it (the
@@ -265,83 +275,33 @@ let envReportSent = null; // the last report the server ACCEPTED, stringified
  * readout whose only proof is that its source LOOKS right is the inert-pin
  * class this repo has caught five times.
  */
-export async function maybeReportEnv(repoRoot) {
-  if (Date.now() - envReportScanAt < ENV_REPORT_SCAN_MS) return 'throttled';
-  envReportScanAt = Date.now();
-  let report;
-  try {
+export function maybeReportEnv(repoRoot) {
+  return envLane(() => {
     // The SCAN happens even when the POST cannot — see the docblock: the
     // scrubber has no dedup and must reflect the newest read every time.
-    report = scanEnvForScrub(repoRoot);
-  } catch {
-    return 'scan-failed'; // a readout must never throw into the poll loop
-  }
-  if (envReportUnsupported) return 'quiet';
-  const payload = JSON.stringify({
-    pubkey: myPubB64(),
-    files: report.files,
-    filesTotal: report.filesTotal,
-    varsTotal: report.varsTotal,
-  });
-  if (payload === envReportSent) return 'deduped';
-  try {
-    const res = await fetch(ENV_REPORT_URL, {
-      method: 'POST',
-      headers: {
-        Authorization: `Bearer ${FLEET_TOKEN}`,
-        'User-Agent': USER_AGENT,
-        'Content-Type': 'application/json',
-      },
-      signal: AbortSignal.timeout(15_000),
-      body: payload,
+    const report = scanEnvForScrub(repoRoot);
+    return JSON.stringify({
+      pubkey: myPubB64(),
+      files: report.files,
+      filesTotal: report.filesTotal,
+      varsTotal: report.varsTotal,
     });
-    // Only a refusal that cannot change stops the lane — see
-    // `envReportIsPermanent`. A 429 or a 401 during a credential blip is a
-    // "later", and treating it as a "never" killed env reporting for the life
-    // of the process with nothing anywhere saying so.
-    if (envReportIsPermanent(res.status)) {
-      envReportUnsupported = true;
-      return 'stopped';
-    }
-    // Only an ACCEPTED report counts, the rule `maybeReportRepoState` keeps:
-    // anything else forgets it so the next pass retries rather than
-    // dedup-suppressing a report nobody received.
-    envReportSent = res.ok ? payload : null;
-    return res.ok ? 'accepted' : 'retry';
-  } catch {
-    envReportSent = null;
-    return 'retry';
-  }
+  });
 }
 
-const TOOLS_REPORT_URL = fleetEndpoint('tools-report', FLEET_URL);
-let toolsReportSent = null;
-let toolsReportUnsupported = false;
-let toolsReportAt = 0;
+// Latches on the env lane's short list for the same reason: a 401 or a 429 is
+// a "later", and a lane that dies invisibly must not die for one.
+const toolsLane = createReportLane({ endpoint: 'tools-report', isPermanent: envReportIsPermanent });
 /** Repo tool readiness is a per-box daemon report. Never include env values. */
-export async function maybeReportTools(repoRoot, baseRef) {
-  if (Date.now() - toolsReportAt < 60_000) return;
-  toolsReportAt = Date.now();
-  if (toolsReportUnsupported) return;
-  const pubkey = myPubB64();
-  if (!pubkey) return;
-  let payload;
-  try {
+export function maybeReportTools(repoRoot, baseRef) {
+  return toolsLane(() => {
+    const pubkey = myPubB64();
+    if (!pubkey) return null;
     const snapshot = readBaseTools(repoRoot, baseRef);
     const installed = detectRuntimes().filter((r) => r.installed);
     const runner = installed.find((r) => runnerToolCapabilities(r.id).mcp)?.id ?? installed[0]?.id ?? 'none';
-    payload = JSON.stringify({ pubkey, tools: toolReadout(snapshot, runner) });
-  } catch { return; }
-  if (payload === toolsReportSent) return;
-  try {
-    const res = await fetch(TOOLS_REPORT_URL, {
-      method: 'POST',
-      headers: { Authorization: `Bearer ${FLEET_TOKEN}`, 'User-Agent': USER_AGENT, 'Content-Type': 'application/json' },
-      signal: AbortSignal.timeout(15_000), body: payload,
-    });
-    if (envReportIsPermanent(res.status)) toolsReportUnsupported = true;
-    toolsReportSent = res.ok ? payload : null;
-  } catch { toolsReportSent = null; }
+    return JSON.stringify({ pubkey, tools: toolReadout(snapshot, runner) });
+  });
 }
 
 /**
@@ -350,7 +310,7 @@ export async function maybeReportTools(repoRoot, baseRef) {
  * it (through fleet.mjs's `onRepoChanged`) after a ship, a retirement or a cut.
  */
 export function repoStateChanged() {
-  repoStateScanAt = 0;
+  repoStateLane.rescan();
 }
 
 const MACHINE_URL = fleetEndpoint('machine', FLEET_URL);

package/bin/lib/fleetStartup.mjs

@@ -11,14 +11,13 @@
 
 import { mkdirSync, readdirSync, statSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import { homedir } from 'node:os';
-import { join, basename } from 'node:path';
+import { join } from 'node:path';
 import { FLEET_TOKEN } from './config.mjs';
 import { git } from './git.mjs';
 import { info, note, warn, fail } from './ui.mjs';
 import { acquireInstanceLock } from './instance.mjs';
 import { emitMachineEvent } from './daemonLogging.mjs';
+import { worktreeHomeDir, worktreeHomeKey } from './statePaths.mjs';
 
 /** Takes the lock, or says why not and exits 1. Returns only on success. */
 export function takeInstanceLockOrExit(repoRoot) {
@@ -90,9 +89,10 @@ export function takeInstanceLockOrExit(repoRoot) {
  */
 export function worktreeHome(repoRoot) {
   // Persistent worktree home (0.9.0) — survives daemon restarts AND reboots,
-  // so Ctrl+C mid-task never loses local work. Keyed per repo path.
-  const repoKey = `${basename(repoRoot)}-${createHash('sha256').update(repoRoot).digest('hex').slice(0, 8)}`;
-  const baseDir = join(homedir(), '.flowviant', 'worktrees', repoKey);
+  // so Ctrl+C mid-task never loses local work. Keyed per repo path, by the
+  // one derivation deploy checkouts and `flowviant clean` share (statePaths.mjs).
+  const repoKey = worktreeHomeKey(repoRoot);
+  const baseDir = worktreeHomeDir(repoRoot);
   mkdirSync(baseDir, { recursive: true });
   return { repoKey, baseDir };
 }

package/bin/lib/fleetWire.mjs

@@ -44,3 +44,45 @@ export function fleetEndpoint(name, rosterUrl) {
   }
   return String(rosterUrl).replace(ROSTER_TAIL, `/${name}`);
 }
+
+/*
+ * ── WHAT A STATUS SAYS (audit 2026-10-10, F139/F155) ───────────────────────
+ *
+ * Whether a failed settle is retried or treated as decided is a correctness
+ * rule: wrong one way and a side-effecting turn re-runs (workReportQueue's
+ * 'reject' history, workAgentTurnReports' six-hour loop); wrong the other way
+ * and a refused body is hammered forever. It was spelled as the literal
+ * expression below five times and re-derived twice more as if-chains, so a
+ * new "later" status (425, say) was seven edits. These are the vocabulary;
+ * each lane still chooses its own POLICY over them (held and backed off,
+ * counted as delivered, latched quiet), and `envReportIsPermanent`
+ * (fleetReports.mjs) is deliberately NARROWER and stays its own rule.
+ *
+ * Pure and config-free like `fleetEndpoint`, so a module handed URLs rather
+ * than config (the artifact reporter) can read them too.
+ */
+
+/** "Not now": a timeout or a rate limit wearing a 4xx. Nothing was decided. */
+export function isNotNow(status) {
+  return status === 408 || status === 429;
+}
+
+/** The server's CONSIDERED answer: a 4xx other than 408/429. Retrying it
+ *  only spends the same refusal again. A missing status (a network error)
+ *  is never a refusal. */
+export function isConsideredRefusal(status) {
+  return status >= 400 && status < 500 && status !== 408 && status !== 429;
+}
+
+/** Retry-After, in ms — seconds or an HTTP-date — capped so one bad or
+ *  hostile header cannot stall a caller for an hour. Falls back to the
+ *  caller's own backoff when the header is absent or unparseable. (Moved
+ *  verbatim from workReportQueue.mjs, 2026-10-10.) */
+export function retryAfterMs(res, fallbackMs) {
+  const h = res?.headers?.get?.('retry-after');
+  if (h == null) return fallbackMs;
+  const secs = Number(h);
+  if (Number.isFinite(secs)) return Math.max(0, Math.min(secs * 1000, 60_000));
+  const at = Date.parse(h);
+  return Number.isFinite(at) ? Math.max(0, Math.min(at - Date.now(), 60_000)) : fallbackMs;
+}