flowviant 0.102.2 → 0.104.0

package/bin/lib/knowledgeLibrary.mjs

@@ -0,0 +1,249 @@
+/**
+ * THE KNOWLEDGE LIBRARY'S RULES, pure (2026-09-26, split out of knowledge.mjs —
+ * SOLID SRP, F049): where every manifest entry may land, under what name, at
+ * what cap, and what the generated catalog says. No disk, no network — the
+ * materialisation (knowledgeFiles.mjs), the download (knowledgeFetch.mjs) and
+ * the roster driver (knowledge.mjs) all ask these, so a change to the bundle
+ * format or the naming rule is a change here and nowhere else.
+ *
+ * ── THE KEPT LIBRARY (2026-09-23, 0.97.0) ──
+ *
+ * The manifest may carry `library: { items: [...] }` — the designs and
+ * write-ups the project KEPT when a person accepted them — and each item lands
+ * at its own relative path, `designs/<slug>-v<N>.html` or
+ * `research/<slug>-v<N>.md`, with a generated `LIBRARY.md` at the root naming
+ * every one (path, title, kind, the card that asked for it, the date, what it
+ * supersedes). So "implement design A" is an agent opening LIBRARY.md, finding
+ * design A, and reading the page. At 0.99.0 a kept design is one folder,
+ * including its original relative sidecar paths and measured preview.
+ *
+ * SUBDIRECTORIES, AND EXACTLY TWO. The safe-name rule for a knowledge file
+ * forbids every separator; a library item is the one thing allowed ONE, and
+ * only after one of the two literal prefixes, with a stem that is already
+ * safe and the extension its kind hands back. `..`, a third segment, another
+ * prefix, a leading dot — refused, never rewritten, because a rewritten path
+ * could collide with another item's real one. The two directories are OURS the
+ * way the library directory is: a symlink or a file planted there is removed
+ * (the link, never its target) and a real directory made.
+ *
+ * ABSENT MEANS "LEAVE IT ALONE", the same rule the whole key keeps: a manifest
+ * with no `library` key is an older server, and `designs/`, `research/` and
+ * `LIBRARY.md` are neither synced nor swept. `library: { items: [] }` is the
+ * emptied catalog, SAID — both directories and the catalog go.
+ */
+
+import { safeFileName } from './safeFileName.mjs';
+
+/** Relative to the checkout, under `.flowviant/` beside the turn uploads and
+ *  the artifacts — see `FLOWVIANT_OWN_PATHS` for why that is NOT one exclude
+ *  line covering all three. */
+export const KNOWLEDGE_DIR = '.flowviant/knowledge';
+
+/**
+ * THE PATHS UNDER `.flowviant/` THAT ARE OURS, and the exclude file names these
+ * and nothing wider (2026-09-23).
+ *
+ * The first cut excluded `/.flowviant/` whole, from every place a turn spawns
+ * in — the attachment fetch's line, which until this release was written only
+ * in repos somebody had attached a file in. But `.flowviant/` is not only ours:
+ * the repo DECLARES `.flowviant/check.json` and `.flowviant/deploy.json` there,
+ * committed like any other file. An exclude line never hides a TRACKED file,
+ * so an existing one was safe — and a NEW one was not: an agent asked to "add a
+ * check command" writes `.flowviant/check.json`, its `git add -A` skips it as
+ * ignored, the commit lands without it, and `git status` shows nothing to
+ * explain why. Writing that line into every worktree on every turn would have
+ * made the product's own configuration uncommittable by the product's own
+ * agents. So the exclude names the four things this daemon writes there, and a
+ * repo's own `.flowviant/*.json` stays ordinary, committable work.
+ *
+ * (A repo that already carries the old `/.flowviant/` line keeps it — it is in
+ * the user's own exclude file, and removing a line we cannot prove we alone
+ * wrote is not ours to do.)
+ */
+export const FLOWVIANT_OWN_PATHS = [
+  '.flowviant/knowledge/',
+  '.flowviant/knowledge.rev*',
+  '.flowviant/artifacts/',
+  '.flowviant/uploads/',
+];
+/** The generated catalog of the kept library, at the knowledge root. Reserved
+ *  like INSTRUCTIONS.md: a person's file of that name is suffixed, because the
+ *  prompt tells the CLI this one is the catalog. */
+export const LIBRARY_FILE = 'LIBRARY.md';
+/** The two subdirectories a kept item may live in, by kind. */
+export const LIBRARY_DIRS = { design: 'designs', research: 'research' };
+const LIBRARY_EXT = { design: ['.html', '.htm', '.gltf', '.obj', '.glb', '.bin'], research: ['.md'] };
+/** The server caps a library at 200 items; a longer manifest is cut. */
+const MAX_LIBRARY_ITEMS = 256;
+
+/** The person's standing brief, written from the manifest's `instructions`.
+ *  A RESERVED name: a library FILE called this gets a suffix, because the
+ *  prompt tells the CLI to read this one first and a stranger's file must
+ *  never be able to stand in for the person's own words. */
+export const INSTRUCTIONS_FILE = 'INSTRUCTIONS.md';
+/** The server's per-file ceiling (`KNOWLEDGE_FILE_MAX_BYTES`), re-checked here:
+ *  this is somebody's disk, and one place checking is one deploy away from
+ *  zero places — the attachment fetch's own rule. */
+export const KNOWLEDGE_FILE_MAX_BYTES = 10 * 1024 * 1024;
+export const KNOWLEDGE_BINARY_MODEL_MAX_BYTES = 20 * 1024 * 1024;
+export const knowledgeMaxFor = (name, base) => /\.(glb|bin)$/i.test(name)
+  ? Math.max(base, KNOWLEDGE_BINARY_MODEL_MAX_BYTES) : base;
+/** The manifest is capped at the server (25 files); a manifest longer than
+ *  this is not one the product produced, and is cut rather than trusted. */
+export const MAX_FILES = 64;
+
+/**
+ * `safeFileName` (bin/lib/safeFileName.mjs — the server's rule, one daemon
+ * home): drops every path separator, never starts with a dot or a dash, and
+ * THE EXTENSION SURVIVES A CUT — byte-identical to what the server computes,
+ * so a knowledge file synced under this name and one requested by name later
+ * never disagree over the cut. An empty name is `file`.
+ */
+export const safeKnowledgeName = (raw) => safeFileName(raw, 'file');
+
+/**
+ * The LOCAL name each manifest entry is written under, in manifest order.
+ * Collisions get a numeric suffix (`spec.md`, `spec-2.md`) — two files a
+ * person uploaded with one name are two files, and silently writing one over
+ * the other loses one. Deterministic in the manifest's order, so the same
+ * manifest always yields the same names and a re-sync never renames a file.
+ * `INSTRUCTIONS.md` is reserved (compared case-insensitively — macOS and
+ * Windows disks are).
+ */
+export function planKnowledgeNames(files) {
+  // The catalog's name and the two library directories are reserved beside
+  // the brief (0.97.0): a person's `LIBRARY.md` or a file called `designs`
+  // must never stand where the catalog or a directory has to.
+  const taken = new Set([
+    INSTRUCTIONS_FILE.toLowerCase(),
+    LIBRARY_FILE.toLowerCase(),
+    ...Object.values(LIBRARY_DIRS),
+  ]);
+  const out = [];
+  for (const f of files) {
+    const name = safeKnowledgeName(f.name);
+    const dot = name.lastIndexOf('.');
+    const stem = dot > 0 ? name.slice(0, dot) : name;
+    const ext = dot > 0 ? name.slice(dot) : '';
+    let candidate = name;
+    for (let n = 2; taken.has(candidate.toLowerCase()); n++) candidate = `${stem}-${n}${ext}`;
+    taken.add(candidate.toLowerCase());
+    out.push({ ...f, local: candidate });
+  }
+  return out;
+}
+
+/**
+ * A kept item's relative path, or null when it is not EXACTLY
+ * `<designs|research>/<safe stem>.<its kind's extension>` — see the header.
+ * Refused rather than rewritten: a rewritten path is one the server never
+ * named, and it could land on another item's real one.
+ */
+export function safeLibraryPath(name, kind) {
+  if (typeof name !== 'string' || !(kind in LIBRARY_DIRS)) return null;
+  const parts = name.split('/');
+  if (parts.length !== 2 && !(kind === 'design' && parts.length >= 3 && parts.length <= 7)) return null;
+  const [dir, ...rest] = parts;
+  const file = rest.at(-1);
+  if (dir !== LIBRARY_DIRS[kind]) return null;
+  if (rest.length >= 2 && !/^[a-z0-9-]+-v[1-9][0-9]*$/.test(rest[0])) return null;
+  if (rest.slice(1, -1).some((p) => !safeBundleSegment(p))) return null;
+  if (!file || (rest.length === 1 ? file !== safeKnowledgeName(file) : !safeBundleSegment(file))) return null;
+  if (!LIBRARY_EXT[kind].some((ext) => file.toLowerCase().endsWith(ext) && file.length > ext.length)) return null;
+  return name;
+}
+
+function safeBundleSegment(part) {
+  return typeof part === 'string' && part.length > 0 && part.length <= 80 &&
+    /^[A-Za-z0-9][A-Za-z0-9._ -]*$/.test(part) && !part.endsWith('.');
+}
+
+function safeBundleFile(path, rootDir) {
+  if (typeof path !== 'string' || !path.startsWith(`${rootDir}/`)) return null;
+  const relative = path.slice(rootDir.length + 1);
+  if (relative === 'preview.png') return null;
+  const parts = relative.split('/');
+  if (!parts.length || parts.some((p) => !safeBundleSegment(p))) return null;
+  if (!/\.(gltf|obj|glb|bin|png|jpg|jpeg|gif|webp|svg|json)$/i.test(relative)) return null;
+  return path;
+}
+
+/** The manifest's library items that are safe to write, in manifest order, or
+ *  null when the key is ABSENT (an older server — leave everything alone). */
+export function libraryItemsOf(manifest) {
+  const lib = manifest?.library;
+  if (lib === undefined || lib === null) return null;
+  if (typeof lib !== 'object' || !Array.isArray(lib.items)) return null;
+  const out = [];
+  const seen = new Set();
+  for (const it of lib.items.slice(0, MAX_LIBRARY_ITEMS)) {
+    if (!it || typeof it.id !== 'string' || !/^[0-9a-f-]{8,64}$/i.test(it.id)) continue;
+    const path = safeLibraryPath(it.name, it.kind);
+    if (!path || seen.has(path.toLowerCase())) continue;
+    seen.add(path.toLowerCase());
+    const bundleDir = path.split('/').length >= 3 ? path.split('/').slice(0, 2).join('/') : null;
+    const expectedPreview = bundleDir ? `${bundleDir}/preview.png` : it.name.replace(/\.html$/, '.png');
+    const previewPath = it.kind === 'design' && it.preview && it.preview.name === expectedPreview ? expectedPreview : null;
+    const files = bundleDir && Array.isArray(it.files) ? it.files.map((f, index) => ({ ...f,
+      index, path: safeBundleFile(f.name, bundleDir),
+    })).filter((f) => f.path && !seen.has(f.path.toLowerCase())) : [];
+    for (const f of files) seen.add(f.path.toLowerCase());
+    out.push({ ...it, path, files, previewPath, previewUnknown: it.kind === 'design' && path.endsWith('.html') && it.preview === undefined });
+  }
+  return out;
+}
+
+/** One line of the catalog: server strings are made single-line and capped —
+ *  they are a person's card title and an artifact's name, headed into a file
+ *  an agent reads, so they may not carry a line break that forges a second
+ *  entry. */
+const catalogText = (v, max) =>
+  String(v ?? '')
+    .replace(/[\r\n\t]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, max);
+
+/**
+ * THE CATALOG, generated whole from the manifest on every sync:
+ *
+ *   - designs/landing-v2.html — Landing mockup (design, from card "Redesign
+ *     landing page", 2026-09-23, supersedes designs/landing-v1.html)
+ *
+ * (one line per item, oldest first — the server's order — so a sync that adds
+ * one item adds one line and moves nothing). Null when there are no items, in
+ * which case the file is removed rather than written empty.
+ */
+export function renderLibraryCatalog(items) {
+  if (!items || items.length === 0) return null;
+  const lines = items.map((it) => {
+    const facts = [it.kind === 'research' ? 'research' : 'design'];
+    const card = catalogText(it.taskTitle, 200);
+    if (card) facts.push(`from card "${card.replace(/"/g, "'")}"`);
+    const day = typeof it.createdAt === 'string' ? it.createdAt.slice(0, 10) : '';
+    if (/^\d{4}-\d{2}-\d{2}$/.test(day)) facts.push(day);
+    const sup = typeof it.supersedes === 'string' ? catalogText(it.supersedes, 200) : '';
+    if (sup) facts.push(`supersedes ${sup}`);
+    const title = catalogText(it.title, 200) || it.path;
+    return `- ${it.path} — ${title} (${facts.join(', ')})`;
+  });
+  return (
+    '# Library\n\n' +
+    'The designs and research this project kept. Paths are relative to this directory;\n' +
+    'a newer version supersedes an older one of the same name.\n\n' +
+    `${lines.join('\n')}\n`
+  );
+}
+
+/** Does this manifest look like one the server produced? Anything else is
+ *  ignored whole rather than half-applied. */
+export function isKnowledgeManifest(k) {
+  return (
+    !!k &&
+    typeof k === 'object' &&
+    Number.isInteger(k.rev) &&
+    k.rev >= 0 &&
+    (k.instructions === null || k.instructions === undefined || typeof k.instructions === 'string') &&
+    Array.isArray(k.files)
+  );
+}

package/bin/lib/landed.mjs

@@ -32,8 +32,9 @@ import { git, baseBranchName } from './git.mjs';
 import { commitRecord, stripDelims, taskIdsFromMessage } from './worktreeDiff.mjs';
 import { warn } from './ui.mjs';
 import { FLEET_URL, FLEET_TOKEN, USER_AGENT } from './config.mjs';
+import { fleetEndpoint } from './fleetWire.mjs';
 
-const LANDED_URL = FLEET_URL.replace(/\/agents\/?$/, '/base-landed');
+const LANDED_URL = fleetEndpoint('base-landed', FLEET_URL);
 /** The server accepts 50 per report. A bigger range walks OLDEST-FIRST in
  *  batches: the persisted tip advances to the last commit actually walked,
  *  so the remainder is picked up on the next beat rather than skipped forever

package/bin/lib/listeners.mjs

@@ -53,10 +53,10 @@
 
 import { execFileSync } from 'node:child_process';
 import { createConnection } from 'node:net';
-import { readFileSync, readdirSync, readlinkSync, realpathSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { platform } from 'node:os';
 import { rssBytes } from './processes.mjs';
-import { sep } from 'node:path';
+import { insideDir, socketHoldersIn } from './procScan.mjs';
 
 /**
  * INFRASTRUCTURE CHILDREN ARE NOT LISTENERS. cloudflared opens its own local
@@ -78,10 +78,9 @@ export const forgetInfraPid = (pid) => {
   infraPids.delete(pid);
 };
 
-/** A box with more processes than this is not one we walk per sweep. The scan
- *  is one readlink per pid and runs every reconcile; this is the runaway
- *  bound, not a capacity statement. */
-const MAX_PIDS = 4000;
+/** A process that IS Flowviant is not a process Flowviant reports — see
+ *  `infraPids` above and the daemon's own gate in `scanLinux`. */
+const isFlowviant = (pid) => pid === process.pid || infraPids.has(pid);
 /**
  * Rows reported per session.
  *
@@ -249,64 +248,35 @@ function labelFor(pid) {
   }
 }
 
-function scanLinux(worktree) {
+/**
+ * The worktree's listening sockets, from the kernel's table and the processes
+ * standing in the worktree — `{ rows, complete }`. The walk of /proc is
+ * `procScan.mjs`'s (bounded on the processes it reads in the worktree, never
+ * on which pids are looked at); `complete: false` means it stopped with pids
+ * unread, and a listener among them is UNMEASURED, not absent.
+ *
+ * Exported with `io` ONLY so the scan-order property can be pinned without a
+ * box that runs four thousand processes. Nothing in the daemon passes it.
+ */
+export function scanLinux(worktree, io) {
   const inodes = listeningByInode();
-  if (inodes.size === 0) return [];
-
-  let root;
-  try {
-    root = realpathSync(worktree);
-  } catch {
-    return []; // the directory is gone — retired under us
-  }
-  const prefix = root.endsWith(sep) ? root : root + sep;
-  const inside = (p) => p === root || p.startsWith(prefix);
-
-  let pids;
-  try {
-    pids = readdirSync('/proc').filter((d) => /^\d+$/.test(d));
-  } catch {
-    return [];
-  }
-  if (pids.length > MAX_PIDS) pids = pids.slice(0, MAX_PIDS);
+  if (inodes.size === 0) return { rows: [], complete: true };
+
+  // NEVER THE DAEMON ITSELF. `startAuthProxy` binds a loopback port IN THIS
+  // PROCESS to gate a preview, and the daemon's own cwd is inside the
+  // checkout — so the gate was attributed to the repo place and surfaced as
+  // a listener the operator could click Stop on. Stopping it would take down
+  // the door in front of a live share, and it is not a thing anybody
+  // started: it is us. Same rule `processes.mjs` keeps by never reporting the
+  // group leader, for the same reason — a process that IS Flowviant is not a
+  // process Flowviant reports.
+  const scan = socketHoldersIn(worktree, { skip: isFlowviant, io });
+  if (scan === null) return { rows: [], complete: true };
 
   const found = new Map(); // port -> row
-  for (const pid of pids) {
-    // Cheap filter FIRST: one readlink rejects almost every process on the box,
-    // and only survivors pay for a readdir of their fd table.
-    let cwd;
-    try {
-      cwd = readlinkSync(`/proc/${pid}/cwd`);
-    } catch {
-      continue; // not ours, or gone
-    }
-    if (!inside(cwd)) continue;
-    // NEVER THE DAEMON ITSELF. `startAuthProxy` binds a loopback port IN THIS
-    // PROCESS to gate a preview, and the daemon's own cwd is inside the
-    // checkout — so the gate was attributed to the repo place and surfaced as
-    // a listener the operator could click Stop on. Stopping it would take down
-    // the door in front of a live share, and it is not a thing anybody
-    // started: it is us. Same rule `processes.mjs` keeps by never reporting the
-    // group leader, for the same reason — a process that IS Flowviant is not a
-    // process Flowviant reports.
-    if (Number(pid) === process.pid || infraPids.has(Number(pid))) continue;
-
-    let fds;
-    try {
-      fds = readdirSync(`/proc/${pid}/fd`);
-    } catch {
-      continue;
-    }
-    for (const fd of fds) {
-      let link;
-      try {
-        link = readlinkSync(`/proc/${pid}/fd/${fd}`);
-      } catch {
-        continue;
-      }
-      const m = /^socket:\[(\d+)\]$/.exec(link);
-      if (!m) continue;
-      const hit = inodes.get(m[1]);
+  for (const { pid, inodes: held } of scan.holders) {
+    for (const inode of held) {
+      const hit = inodes.get(inode);
       if (!hit) continue;
       if (found.has(hit.port)) continue;
       const chosen = chosenPort(hit.port);
@@ -319,13 +289,13 @@ function scanLinux(worktree) {
         // was thrown away the moment the row was built. Keeping it is what lets
         // a surface group nine sockets under the ONE program that opened them,
         // and it is the only thing a kill could ever be aimed at.
-        pid: Number(pid),
+        pid,
         ...(rss != null ? { rss } : {}),
         ...(chosen === undefined ? {} : { chosen }),
       });
     }
   }
-  return [...found.values()];
+  return { rows: [...found.values()], complete: scan.complete };
 }
 
 // ── macOS ──────────────────────────────────────────────────────────────────
@@ -363,12 +333,10 @@ function scanDarwin(worktree) {
   } catch {
     /* no memory on this box — rows simply carry no rss */
   }
-  const self = String(process.pid);
   for (const line of lsof(['-nP', '-iTCP', '-sTCP:LISTEN', '-F', 'pn']).split('\n')) {
     // The daemon's own preview gate is not something the driver started — see
     // the linux branch for the whole argument. Nor its cloudflared children.
-    if (line.startsWith('p'))
-      pid = line.slice(1) === self || infraPids.has(Number(line.slice(1))) ? null : line.slice(1);
+    if (line.startsWith('p')) pid = isFlowviant(Number(line.slice(1))) ? null : line.slice(1);
     else if (line.startsWith('n') && pid) {
       const m = /:(\d+)$/.exec(line.slice(1));
       if (!m) continue;
@@ -380,13 +348,8 @@ function scanDarwin(worktree) {
   }
   if (byPid.size === 0) return [];
 
-  let root;
-  try {
-    root = realpathSync(worktree);
-  } catch {
-    return [];
-  }
-  const prefix = root.endsWith(sep) ? root : root + sep;
+  const inside = insideDir(worktree);
+  if (!inside) return [];
 
   // Pass 2: the cwd of exactly those pids, in ONE batched call.
   const out = new Map();
@@ -394,8 +357,7 @@ function scanDarwin(worktree) {
   for (const line of lsof(['-a', '-d', 'cwd', '-F', 'pn', '-p', [...byPid.keys()].join(',')]).split('\n')) {
     if (line.startsWith('p')) cur = line.slice(1);
     else if (line.startsWith('n') && cur) {
-      const cwd = line.slice(1);
-      if (cwd !== root && !cwd.startsWith(prefix)) continue;
+      if (!inside(line.slice(1))) continue;
       for (const row of byPid.get(cur) || []) {
         if (out.has(row.port)) continue;
         const chosen = chosenPort(row.port);
@@ -452,17 +414,39 @@ export function byChosenThenPort(a, b) {
  * Repository block already settled that trade for branches and worktrees: the
  * capped list rides beside the count it was cut from. An empty array on an
  * unsupported platform means "we did not look" — callers must not turn it into
- * "nothing is running".
+ * "nothing is running". `incomplete: true` rides along when the /proc walk hit
+ * its work bound (`procScan.mjs`) with pids still unread.
+ *
+ * `incomplete` IS NOT RELAYED, deliberately, for now. The listener reports
+ * (`workPlaceReports.mjs`, `repoState.mjs`) send `rows`/`total` only: a new report field
+ * needs no floor, but it needs a reader on the server and a sentence on the
+ * web, and neither exists — sending it would be a field nobody reads. The cut
+ * needs thousands of processes standing in ONE worktree; the share path, where
+ * the cut would change an answer, says it in words (`originFor`). Relaying it
+ * to the Workbench is a product call, not this module's.
+ *
+ * `io` is the test seam `scanLinux` documents; nothing in the daemon passes it.
  */
-export function measureListeners(worktree) {
+export function measureListeners(worktree, io) {
   if (!worktree) return { rows: [], total: 0 };
-  let rows;
+  let scan;
   try {
-    rows = platform() === 'linux' ? scanLinux(worktree) : platform() === 'darwin' ? scanDarwin(worktree) : [];
+    scan =
+      platform() === 'linux'
+        ? scanLinux(worktree, io)
+        : { rows: platform() === 'darwin' ? scanDarwin(worktree) : [], complete: true };
   } catch {
     return { rows: [], total: 0 };
   }
-  return { rows: rows.sort(byChosenThenPort).slice(0, MAX_ROWS), total: rows.length };
+  const { rows, complete } = scan;
+  return {
+    rows: rows.sort(byChosenThenPort).slice(0, MAX_ROWS),
+    total: rows.length,
+    // SAID ONLY WHEN IT HAPPENED: the walk stopped with pids unread, so the
+    // rows are real and the total is a floor — a listener missing from them
+    // was not looked for, which is not the same fact as "not running".
+    ...(complete ? {} : { incomplete: true }),
+  };
 }
 
 /** The capped rows alone, for callers with nowhere to put a total. */
@@ -537,23 +521,36 @@ export function isListening(port, timeoutMs = 1500) {
  * file cannot measure answers the loopback it always dialled — the same
  * behaviour as before, never a refusal invented from ignorance.
  */
-export function originFor(worktree, port) {
+export function originFor(worktree, port, io) {
   if (!worktree || !Number.isInteger(port) || port <= 0 || port > 65535) {
     return { error: `nothing is listening on port ${port} in this worktree.` };
   }
-  let sockets;
+  let scan;
   try {
-    sockets =
+    scan =
       platform() === 'linux'
-        ? socketsOnPortLinux(worktree, port)
+        ? socketsOnPortLinux(worktree, port, io)
         : platform() === 'darwin'
-          ? socketsOnPortDarwin(worktree, port)
+          ? { sockets: socketsOnPortDarwin(worktree, port), complete: true }
           : null;
   } catch {
-    sockets = null;
+    scan = null;
+  }
+  if (scan == null) return { host: '127.0.0.1' };
+  const picked = pickOrigin(scan.sockets, port);
+  // A socket on this port whose holder the walk never reached is read as
+  // FOREIGN by the rule — the safe reading for a shadow check — so an
+  // unshadowed socket of ours is shared exactly as a complete walk would share
+  // it. Only when the rule would REFUSE does the cut matter: then "nothing is
+  // listening" (or "another process") may be about a socket the kernel holds
+  // for a process the walk never reached, and that is said instead (F007;
+  // review 2026-09-26: never a refusal built on the cut alone).
+  if (picked.error && !scan.complete && scan.sockets.some((s) => !s.ours)) {
+    return {
+      error: `this machine runs more processes in this worktree than one look reads, so which one holds port ${port} could not be told — it was not shared.`,
+    };
   }
-  if (sockets == null) return { host: '127.0.0.1' };
-  return pickOrigin(sockets, port);
+  return picked;
 }
 
 /**
@@ -617,7 +614,9 @@ function hexAddr(hex, family) {
   return `${head}::${tail}`;
 }
 
-function socketsOnPortLinux(worktree, port) {
+/** `{ sockets, complete }` on success, null when /proc cannot be listed.
+ *  `io` is the test seam `scanLinux` documents. */
+export function socketsOnPortLinux(worktree, port, io) {
   const byInode = new Map(); // inode -> { family, addr }
   for (const [f, family] of [
     ['/proc/net/tcp', 4],
@@ -637,51 +636,17 @@ function socketsOnPortLinux(worktree, port) {
       if (c[9] && c[9] !== '0') byInode.set(c[9], { family, addr: hexAddr(a, family) });
     }
   }
-  if (byInode.size === 0) return [];
-  let root;
-  try {
-    root = realpathSync(worktree);
-  } catch {
-    return [];
-  }
-  const prefix = root.endsWith(sep) ? root : root + sep;
+  if (byInode.size === 0) return { sockets: [], complete: true };
+  const scan = socketHoldersIn(worktree, { skip: isFlowviant, io });
+  if (scan === null) return null;
   const ours = new Set();
-  let pids;
-  try {
-    pids = readdirSync('/proc').filter((d) => /^\d+$/.test(d));
-  } catch {
-    return null;
-  }
-  if (pids.length > MAX_PIDS) pids = pids.slice(0, MAX_PIDS);
-  for (const pid of pids) {
-    let cwd;
-    try {
-      cwd = readlinkSync(`/proc/${pid}/cwd`);
-    } catch {
-      continue;
-    }
-    if (cwd !== root && !cwd.startsWith(prefix)) continue;
-    if (Number(pid) === process.pid || infraPids.has(Number(pid))) continue;
-    let fds;
-    try {
-      fds = readdirSync(`/proc/${pid}/fd`);
-    } catch {
-      continue;
-    }
-    for (const fd of fds) {
-      let link;
-      try {
-        link = readlinkSync(`/proc/${pid}/fd/${fd}`);
-      } catch {
-        continue;
-      }
-      const m = /^socket:\[(\d+)\]$/.exec(link);
-      if (m && byInode.has(m[1])) ours.add(m[1]);
-    }
-  }
+  for (const { inodes } of scan.holders) for (const inode of inodes) if (byInode.has(inode)) ours.add(inode);
   // A socket whose holder we could not read (another user's process) is
   // FOREIGN — the safe reading for a refusal check.
-  return [...byInode.entries()].map(([inode, s]) => ({ ...s, ours: ours.has(inode) }));
+  return {
+    sockets: [...byInode.entries()].map(([inode, s]) => ({ ...s, ours: ours.has(inode) })),
+    complete: scan.complete,
+  };
 }
 
 function socketsOnPortDarwin(worktree, port) {
@@ -700,22 +665,15 @@ function socketsOnPortDarwin(worktree, port) {
     }
   }
   if (!rows.length) return [];
-  let root;
-  try {
-    root = realpathSync(worktree);
-  } catch {
-    return [];
-  }
-  const prefix = root.endsWith(sep) ? root : root + sep;
+  const within = insideDir(worktree);
+  if (!within) return [];
   const inside = new Set();
-  const self = String(process.pid);
   let cur = null;
   const pids = [...new Set(rows.map((r) => r.pid))];
   for (const line of lsof(['-a', '-d', 'cwd', '-F', 'pn', '-p', pids.join(',')]).split('\n')) {
     if (line.startsWith('p')) cur = line.slice(1);
     else if (line.startsWith('n') && cur) {
-      const cwd = line.slice(1);
-      if ((cwd === root || cwd.startsWith(prefix)) && cur !== self && !infraPids.has(Number(cur))) inside.add(cur);
+      if (within(line.slice(1)) && !isFlowviant(Number(cur))) inside.add(cur);
     }
   }
   return rows.map((r) => ({ family: r.family, addr: r.addr, ours: inside.has(r.pid) }));