@awebai/oats 0.31.0 → 0.32.0

package/lib/resolve.mjs

@@ -60,6 +60,7 @@ import * as defaultRemote from "./remote.mjs";
 import { BY_TEAM_REMOVED, reportRows, soulKeyOf, soulTeams, teamModel } from "./teams.mjs";
 import { bindRemote, packageProviding, readPackageManifests, validateLock } from "./packages.mjs";
 import { settingValueProblems } from "./capability-contract.mjs";
+import { memberRowByKey } from "./workspace.mjs";
 
 export const RESOLUTION_API = 1;
 export const SLOTS = Object.freeze(["knowledge", "messaging", "tasks"]);
@@ -367,14 +368,26 @@ export function composeCapabilities(workspace, soulDefinition, { offs = null } =
 
 /* ───────────────────────────── lookups ────────────────────────────────── */
 
-function memberRow(discovery, repoKey) {
-  return (discovery?.members || []).find((m) => m.key === repoKey) || null;
-}
+/** A discovery's member row by key (the first with that key; lib/workspace.mjs memberRowByKey). */
+const memberRow = (discovery, repoKey) => memberRowByKey(discovery?.members, repoKey);
 
-/** The ref the workspace lists a member under (keeps the operator's spelling: ssh vs https); else from the key. */
+/** The ref the workspace lists a member under (keeps the operator's spelling: ssh vs https); else from the key.
+ *  The key → first listed ref index is built once per members array and parseRepoRef. */
+const memberRefIndex = new WeakMap();
 export function memberRef(discovery, remote, repoKey) {
-  for (const ref of discovery?.workspace?.members || []) {
-    try { if (remote.parseRepoRef(ref).key === repoKey) return ref; } catch { /* validated upstream */ }
+  const members = discovery?.workspace?.members;
+  if (Array.isArray(members)) {
+    let byParser = memberRefIndex.get(members);
+    if (!byParser) memberRefIndex.set(members, byParser = new Map());
+    let index = byParser.get(remote.parseRepoRef);
+    if (!index) {
+      index = new Map();
+      for (const ref of members) {
+        try { const key = remote.parseRepoRef(ref).key; if (!index.has(key)) index.set(key, ref); } catch { /* validated upstream */ }
+      }
+      byParser.set(remote.parseRepoRef, index);
+    }
+    if (index.has(repoKey)) return index.get(repoKey);
   }
   return refForKey(repoKey);
 }
@@ -496,7 +509,10 @@ async function enumerateSkills({ remote, ref, commit, dir, manifest, listing, mo
       // Discovery already listed the capability directory (relative to it): project onto this entry.
       entries = listing.filter((e) => e.path === declared || e.path.startsWith(`${declared}/`)).map((e) => ({ ...e, path: e.path === declared ? "" : e.path.slice(declared.length + 1) })).filter((e) => e.path);
     } else {
-      entries = await remote.listRemoteTree(ref, commit, posix.join(dir, declared), { depth: 2 });
+      // A listing at a commit never changes: the parsed cache keeps it (lib/remote.mjs memoAtCommit).
+      const at = posix.join(dir, declared);
+      const list = () => remote.listRemoteTree(ref, commit, at, { depth: 2 });
+      entries = typeof remote.memoAtCommit === "function" ? await remote.memoAtCommit(ref, commit, `list\0${at}\0${2}`, list) : await list();
     }
     const found = skillsInListing(declared, entries);
     if (found.length === 0) throw missing(raw, "skill-missing", `declares skills entry ${show(raw)} but no SKILL.md is there (neither ${declared}/SKILL.md nor ${declared}/*/SKILL.md)`);

package/lib/servers.mjs

@@ -943,6 +943,13 @@ function launchRemoteSession(serverId, action, choices, io) {
 /** A launch definition in the host's vocabulary: `harness` for a host with the harness feature,
  *  `runtime` for one before 0.27.0. Either spelling is read here; both, disagreeing, are refused. */
 function hostLaunchDefinition(remote, definition) {
+  // `default` (0.32) never reaches a host without the feature: `true` is refused, `false` (the absence) dropped.
+  if (definition && Object.hasOwn(definition, "default") && !(remote?.features || []).includes("launch-config-default")) {
+    if (definition.default === true) throw serverError("E_REMOTE_INCOMPATIBLE", "the server's OATS does not support a default launch configuration (feature launch-config-default, OATS 0.32+); upgrade it, or set the configuration without default");
+    if (definition.default !== false) throw serverError("E_LAUNCH_CONFIG_INVALID", "default must be true or false");
+    const { default: _absent, ...without } = definition;
+    definition = without;
+  }
   const { harness, runtime, ...rest } = definition; // a disagreeing pair was refused before the probe
   if (runtime !== undefined) noteRuntimeName("runtime in the launch configuration definition (sent as the host's harness key)");
   const value = harness ?? runtime;

package/lib/workspace.mjs

@@ -12,6 +12,7 @@
  */
 import { readFileSync, existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { recordLocalInput } from "./local-inputs.mjs";
 import { parseConfigData } from "./config-data.mjs";
 import { oatsError } from "./errors.mjs";
 import * as defaultRemote from "./remote.mjs";
@@ -36,6 +37,12 @@ function remoteOf(options) {
   const remote = assertRemoteApi(options?.remote ?? defaultRemote);
   return bindRemote(remote, options?.remoteOptions);
 }
+/** The parsed cache (lib/remote.mjs memoAtCommit, optional on the remote contract): `compute()` is a pure
+ *  function of the bytes at (ref's key, commit) and this kernel. A remote without it — every in-memory fake —
+ *  just computes. */
+function atCommit(remote, ref, commit, item, compute) {
+  return typeof remote.memoAtCommit === "function" ? remote.memoAtCommit(ref, commit, item, compute) : compute();
+}
 const REQUIRED_REMOTE_API = ["parseRepoRef", "observeRemote", "readRemoteFile", "listRemoteTree"];
 function assertRemoteApi(remote) {
   for (const name of REQUIRED_REMOTE_API) {
@@ -362,10 +369,13 @@ export function loadLocal(dir) {
     const candidate = join(current, "oats-local.yaml");
     visited.push(candidate);
     if (existsSync(join(current, "oats-config.yaml"))) legacy.push(join(current, "oats-config.yaml"));
-    if (existsSync(candidate)) {
+    if (!existsSync(candidate)) recordLocalInput(candidate, null); // a closer file appearing changes the answer
+    else {
       if (legacy.length) throw fail("E_CONFIG_BROKEN", `${legacy.join(", ")}: ${LEGACY_CONFIG_MIGRATION}`, { dir: resolve(dir), deployment: current, files: legacy, reason: "legacy-config" });
       const origin = { kind: "local", path: candidate };
-      const read = readDeclaration("local", readFileSync(candidate), origin);
+      const bytes = readFileSync(candidate);
+      recordLocalInput(candidate, bytes);
+      const read = readDeclaration("local", bytes, origin);
       if (read.problems) throw schemaError("local", origin, read.problems, read.value);
       return { path: candidate, local: read.value };
     }
@@ -382,21 +392,53 @@ export async function observeWorkspace(ref, { at, remote: injected, remoteOption
   const obs = await remote.observeRemote(ref, { at });
   const path = "oats-workspace.yaml";
   const origin = { kind: "workspace", repoKey: obs.key, commit: obs.commit, path };
-  let bytes;
-  try { ({ bytes } = await remote.readRemoteFile(ref, obs.commit, path)); }
-  catch (e) {
-    // Contract: observeWorkspace throws E_REMOTE_UNREADABLE | E_WORKSPACE_SCHEMA. A repo without the
-    // file is not a workspace (the usual mistake: a member handed in as the workspace).
-    if (e?.code === "E_REMOTE_PATH_MISSING") throw fail("E_WORKSPACE_SCHEMA", `${obs.key}@${obs.commit.slice(0, 12)} has no ${path}: it is not a workspace host`, { path, notAHost: true, repoKey: obs.key, commit: obs.commit, problems: [{ path: "", message: `${path} is missing` }], cause: e.code });
-    throw e;
-  }
-  const read = readDeclaration("workspace", bytes, origin, { remote });
+  // The file at the host commit, read and validated (parsed cache item: "missing" or the declaration read).
+  const read = await atCommit(remote, ref, obs.commit, "workspace", async () => {
+    try { return readDeclaration("workspace", (await remote.readRemoteFile(ref, obs.commit, path)).bytes, origin, { remote }); }
+    catch (e) { if (e?.code === "E_REMOTE_PATH_MISSING") return { missing: e.code }; throw e; }
+  });
+  // Contract: observeWorkspace throws E_REMOTE_UNREADABLE | E_WORKSPACE_SCHEMA. A repo without the
+  // file is not a workspace (the usual mistake: a member handed in as the workspace).
+  if (read.missing) throw fail("E_WORKSPACE_SCHEMA", `${obs.key}@${obs.commit.slice(0, 12)} has no ${path}: it is not a workspace host`, { path, notAHost: true, repoKey: obs.key, commit: obs.commit, problems: [{ path: "", message: `${path} is missing` }], cause: read.missing });
   if (read.problems) throw schemaError("workspace", origin, read.problems, read.value);
+  checkedWorkspace(read.value, remote, []); // validated just now: confirmMembership need not validate it again
   return { key: obs.key, url: obs.url, ref, commit: obs.commit, workspace: read.value, observedAt: obs.observedAt };
 }
 
 const unconfirmed = (key, reason, detail, extra = {}) => ({ key, confirmed: false, reason, detail, ...extra });
 
+/** A workspace value's own checks, computed once per workspace object (and parseRepoRef): its problems
+ *  and the set of its member keys. confirmMembership runs per member; these do not change between them. */
+const workspaceChecks = new WeakMap();
+function checkedWorkspace(workspace, remote, knownProblems = null) {
+  if (workspace === null || typeof workspace !== "object") return { problems: validateWorkspace(workspace, { remote }), keys: new Set() };
+  let byParser = workspaceChecks.get(workspace);
+  if (!byParser) workspaceChecks.set(workspace, byParser = new Map());
+  let checked = byParser.get(remote.parseRepoRef);
+  if (!checked) {
+    const keys = new Set();
+    for (const m of workspace.members || []) { try { keys.add(refKey(remote, m)); } catch { /* validateWorkspace names it */ } }
+    byParser.set(remote.parseRepoRef, checked = { problems: knownProblems ?? validateWorkspace(workspace, { remote }), keys });
+  }
+  return checked;
+}
+
+/** The member's oats-membership.yaml at `commit`, read and validated — a pure function of the bytes there
+ *  (parsed cache item "membership"): { kind: "ok", value } | { kind: "invalid", problems } | { kind: "missing" }
+ *  | { kind: "unusable", code, message }. E_REMOTE_UNREADABLE (transient) is thrown, never an outcome. */
+async function membershipAt(remote, memberRef, key, commit) {
+  let bytes;
+  try { ({ bytes } = await remote.readRemoteFile(memberRef, commit, "oats-membership.yaml")); }
+  catch (e) {
+    if (e?.code === "E_REMOTE_PATH_MISSING") return { kind: "missing" };
+    if (e?.code === "E_REMOTE_UNREADABLE") throw e;
+    if (typeof e?.code === "string" && e.code.startsWith("E_REMOTE_")) return { kind: "unusable", code: e.code, message: e.message };
+    throw e;
+  }
+  const read = readDeclaration("membership", bytes, { kind: "membership", repoKey: key, commit, path: "oats-membership.yaml" });
+  return read.problems ? { kind: "invalid", problems: read.problems } : { kind: "ok", value: read.value };
+}
+
 /**
  * Read the member's oats-membership.yaml at its default branch in the same access context.
  * → { key, commit, confirmed: true } | { key, confirmed: false, reason, detail }
@@ -404,16 +446,15 @@ const unconfirmed = (key, reason, detail, extra = {}) => ({ key, confirmed: fals
 export async function confirmMembership(workspaceObs, memberRef, { remote: injected, remoteOptions } = {}) {
   const remote = remoteOf({ remote: injected, remoteOptions });
   const workspace = workspaceObs.workspace;
-  const wsProblems = validateWorkspace(workspace, { remote });
-  if (wsProblems.length) throw schemaError("workspace", { kind: "workspace", repoKey: workspaceObs.key, commit: workspaceObs.commit, path: "oats-workspace.yaml" }, wsProblems, workspace);
+  const checked = checkedWorkspace(workspace, remote);
+  if (checked.problems.length) throw schemaError("workspace", { kind: "workspace", repoKey: workspaceObs.key, commit: workspaceObs.commit, path: "oats-workspace.yaml" }, checked.problems, workspace);
   let key;
   try { key = refKey(remote, memberRef); }
   catch (e) {
     if (e?.code === "E_REPO_REF") return unconfirmed(typeof memberRef === "string" ? memberRef : String(memberRef), "not-listed", `${show(memberRef)} is not a repo ref: ${e.message}`);
     throw e;
   }
-  const listed = (workspace.members || []).some((m) => refKey(remote, m) === key);
-  if (!listed) return unconfirmed(key, "not-listed", `${key} is not in members of workspace ${workspaceObs.key}`);
+  if (!checked.keys.has(key)) return unconfirmed(key, "not-listed", `${key} is not in members of workspace ${workspaceObs.key}`);
   const cannotRead = (e) => unconfirmed(key, "cannot-read", `cannot read ${e.details?.url ?? e.provenance?.url ?? memberRef}${e.details?.reason ? ` (${e.details.reason})` : ""}`, { url: e.details?.url ?? e.provenance?.url ?? null });
   let obs;
   try { obs = await remote.observeRemote(memberRef); }
@@ -421,17 +462,17 @@ export async function confirmMembership(workspaceObs, memberRef, { remote: injec
     if (e?.code === "E_REMOTE_UNREADABLE") return cannotRead(e);
     throw e;
   }
-  let bytes;
-  try { ({ bytes } = await remote.readRemoteFile(memberRef, obs.commit, "oats-membership.yaml")); }
+  let outcome;
+  try { outcome = await atCommit(remote, memberRef, obs.commit, "membership", () => membershipAt(remote, memberRef, key, obs.commit)); }
   catch (e) {
-    if (e?.code === "E_REMOTE_PATH_MISSING") return unconfirmed(key, "no-backlink", `${key}@${obs.commit.slice(0, 12)} has no oats-membership.yaml`, { commit: obs.commit });
     if (e?.code === "E_REMOTE_UNREADABLE") return cannotRead(e);
-    // Contract: NEVER throws for an unconfirmed member. Anything else the remote refuses about the
-    // member's file (oversize, symlink, unsafe tree) means the repo has not completed the handshake.
-    if (typeof e?.code === "string" && e.code.startsWith("E_REMOTE_")) return unconfirmed(key, "no-backlink", `${key}@${obs.commit.slice(0, 12)} oats-membership.yaml cannot be used: ${e.message}`, { commit: obs.commit, cause: e.code });
     throw e;
   }
-  const read = readDeclaration("membership", bytes, { kind: "membership", repoKey: key, commit: obs.commit, path: "oats-membership.yaml" });
+  if (outcome.kind === "missing") return unconfirmed(key, "no-backlink", `${key}@${obs.commit.slice(0, 12)} has no oats-membership.yaml`, { commit: obs.commit });
+  // Contract: NEVER throws for an unconfirmed member. Anything else the remote refuses about the
+  // member's file (oversize, symlink, unsafe tree) means the repo has not completed the handshake.
+  if (outcome.kind === "unusable") return unconfirmed(key, "no-backlink", `${key}@${obs.commit.slice(0, 12)} oats-membership.yaml cannot be used: ${outcome.message}`, { commit: obs.commit, cause: outcome.code });
+  const read = outcome.kind === "invalid" ? { problems: outcome.problems } : { value: outcome.value };
   if (read.problems) return unconfirmed(key, "no-backlink", `${key}@${obs.commit.slice(0, 12)} oats-membership.yaml is invalid: ${read.problems.map((p) => `${p.path || "/"}: ${p.message}`).join("; ")}`, { commit: obs.commit, problems: read.problems });
   let backlinkKey;
   try { backlinkKey = refKey(remote, read.value.workspace); }
@@ -553,7 +594,7 @@ export async function discoverRepo(ref, { at, remote: injected, remoteOptions }
   } catch (e) {
     if (e?.code !== "E_REMOTE_PATH_MISSING") throw e;
   }
-  const items = await enumerateRepo(remote, ref, obs.key, obs.commit);
+  const items = await atCommit(remote, ref, obs.commit, "enumerate", () => enumerateRepo(remote, ref, obs.key, obs.commit));
   return { key: obs.key, commit: obs.commit, membership, ...items, problems: [...problems, ...items.problems] };
 }
 
@@ -590,13 +631,13 @@ export async function discoverPackageSouls(workspace, lock, { remote: injected,
     for (const locked of entry.souls) {
       const path = `${entry.path}/${locked.path}`;
       const file = `${path}/soul.yaml`;
-      let bytes;
-      try { ({ bytes } = await remote.readRemoteFile(ref, entry.commit, file)); }
-      catch (e) {
-        if (typeof e?.code === "string" && e.code.startsWith("E_REMOTE_")) { problem(e.code, file, e.message); continue; }
-        throw e;
-      }
-      const read = readDeclaration("soul", bytes, { kind: "soul", repoKey: key, commit: entry.commit, path: file });
+      // soul.yaml at the locked commit, read and validated (parsed cache item; a remote failure is an
+      // outcome here, and a transient one is never kept).
+      const read = await atCommit(remote, ref, entry.commit, `package-soul\0${file}`, async () => {
+        try { return readDeclaration("soul", (await remote.readRemoteFile(ref, entry.commit, file)).bytes, { kind: "soul", repoKey: key, commit: entry.commit, path: file }); }
+        catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_REMOTE_")) return { remoteError: { code: e.code, message: e.message } }; throw e; }
+      });
+      if (read.remoteError) { problem(read.remoteError.code, file, read.remoteError.message); continue; }
       if (read.problems) { for (const p of read.problems) problem("E_WORKSPACE_SCHEMA", `${file}#${p.path}`, `${p.message}${schemaHint("soul", read.value)}`); continue; }
       const definition = read.value;
       if (definition.name !== locked.name) { problem("E_WORKSPACE_SCHEMA", `${file}#/name`, `soul name ${show(definition.name)} does not match its directory ${show(locked.name)}`); continue; }
@@ -621,36 +662,68 @@ export async function discoverPackageSouls(workspace, lock, { remote: injected,
   return { souls, problems };
 }
 
+/** Members discovered at once (a fixed bound: the laptop's git and network, not the workspace's size). */
+export const DISCOVERY_CONCURRENCY = 8;
+
+/** `task(item, index)` over `items` with at most `limit` running, results in item order. Exactly the serial
+ *  loop's outcome: indices are taken in order, nothing new starts after a failure, and the failure of the
+ *  LOWEST index is thrown once everything started has settled (every earlier item had succeeded). */
+async function boundedMap(items, limit, task) {
+  const results = new Array(items.length);
+  const failures = new Map();
+  let next = 0;
+  const worker = async () => {
+    while (next < items.length && failures.size === 0) {
+      const i = next++;
+      try { results[i] = await task(items[i], i); } catch (e) { failures.set(i, e); }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+  if (failures.size) throw failures.get(Math.min(...failures.keys()));
+  return results;
+}
+
 /**
  * The whole picture in one access context.
  * → { workspace, members: [{ key, commit, confirmed, reason?, souls, capabilities, publishes }], external: [...],
  *     problems: [{ code, path, message, repoKey? }] }
  * `publishes` = { package, version } when the member carries oats-package/oats-package.json (informational:
  * the package's capabilities are NOT member capabilities — non-collapse rule), else null.
+ * Members are read DISCOVERY_CONCURRENCY at a time; rows and problems are assembled in declaration order.
  */
 export async function discoverWorkspace(ref, { at, local, lock = null, remote: injected, remoteOptions } = {}) {
   const remote = remoteOf({ remote: injected, remoteOptions });
-  const wsObs = await observeWorkspace(ref, { at, remote });
+  prefetchMembers(remote, ref, at);
+  let wsObs;
+  // The host cannot be observed: nothing will adopt the prefetches, so none still queued may run its git.
+  try { wsObs = await observeWorkspace(ref, { at, remote }); }
+  catch (e) { remote.abandonPrefetches?.(); throw e; }
   const workspace = wsObs.workspace;
   const problems = [];
   const members = [];
-  for (const memberRef of workspace.members || []) {
-    const confirmation = await confirmMembership(wsObs, memberRef, { remote });
-    const row = { key: confirmation.key, ref: memberRef, commit: confirmation.commit ?? null, confirmed: confirmation.confirmed, souls: [], capabilities: [], publishes: null };
-    if (!confirmation.confirmed) {
-      // Contract: an unconfirmed member contributes nothing but its row.
-      row.reason = confirmation.reason;
-      row.detail = confirmation.detail;
-      members.push(row);
-      continue;
-    }
-    const items = await enumerateRepo(remote, memberRef, row.key, row.commit);
-    row.souls = items.souls;
-    row.capabilities = items.capabilities;
-    row.publishes = items.publishes;
-    problems.push(...items.problems);
-    members.push(row);
+  let discovered;
+  try {
+    discovered = await boundedMap(workspace.members || [], DISCOVERY_CONCURRENCY, async (memberRef) => {
+      const confirmation = await confirmMembership(wsObs, memberRef, { remote });
+      const row = { key: confirmation.key, ref: memberRef, commit: confirmation.commit ?? null, confirmed: confirmation.confirmed, souls: [], capabilities: [], publishes: null };
+      if (!confirmation.confirmed) {
+        // Contract: an unconfirmed member contributes nothing but its row.
+        row.reason = confirmation.reason;
+        row.detail = confirmation.detail;
+        return { row, problems: [] };
+      }
+      const items = await atCommit(remote, memberRef, row.commit, "enumerate", () => enumerateRepo(remote, memberRef, row.key, row.commit));
+      row.souls = items.souls;
+      row.capabilities = items.capabilities;
+      row.publishes = items.publishes;
+      return { row, problems: items.problems };
+    });
+  } finally {
+    // Every member listed now has adopted its prefetch (or the discovery failed): the rest, members dropped
+    // since the host's last observed commit, are given up.
+    remote.abandonPrefetches?.();
   }
+  for (const d of discovered) { members.push(d.row); problems.push(...d.problems); }
   const externalRows = [];
   for (const [index, entry] of (workspace.external || []).entries()) {
     const pin = entry.source.lastIndexOf("@");
@@ -661,15 +734,13 @@ export async function discoverWorkspace(ref, { at, local, lock = null, remote: i
     let key;
     try { key = refKey(remote, sourceRef); }
     catch (e) { if (e?.code === "E_REPO_REF") { pushProblem("E_REPO_REF", "source", e.message); continue; } throw e; }
-    let bytes;
-    try {
-      // Pinned: read at the declared OID only; the remote's default branch is never consulted.
-      ({ bytes } = await remote.readRemoteFile(sourceRef, commit, file));
-    } catch (e) {
-      if (e?.code === "E_REMOTE_UNREADABLE" || e?.code === "E_REMOTE_PATH_MISSING") { pushProblem(e.code, file, e.message); continue; }
-      throw e;
-    }
-    const read = readDeclaration("soul", bytes, { kind: "soul", repoKey: key, commit, path: file });
+    // Pinned: read at the declared OID only; the remote's default branch is never consulted. The soul.yaml
+    // there, read and validated, is a parsed cache item (a transient failure is never kept).
+    const read = await atCommit(remote, sourceRef, commit, `external-soul\0${file}`, async () => {
+      try { return readDeclaration("soul", (await remote.readRemoteFile(sourceRef, commit, file)).bytes, { kind: "soul", repoKey: key, commit, path: file }); }
+      catch (e) { if (e?.code === "E_REMOTE_UNREADABLE" || e?.code === "E_REMOTE_PATH_MISSING") return { remoteError: { code: e.code, message: e.message } }; throw e; }
+    });
+    if (read.remoteError) { pushProblem(read.remoteError.code, file, read.remoteError.message); continue; }
     if (read.problems) { for (const p of read.problems) pushProblem("E_WORKSPACE_SCHEMA", `${file}#${p.path}`, `${p.message}${schemaHint("soul", read.value)}`); continue; }
     externalRows.push({ source: entry.source, key, commit, soul: { name: read.value.name, path: entry.soul, repoKey: key, commit, private: false, definition: read.value } });
   }
@@ -678,6 +749,42 @@ export async function discoverWorkspace(ref, { at, local, lock = null, remote: i
   return { workspace, key: wsObs.key, url: wsObs.url, commit: wsObs.commit, observedAt: wsObs.observedAt, local: local ?? null, members, external: externalRows, packageSouls: pkg.souls, problems, warnings: workspaceWarnings(workspace, members, externalRows, pkg.souls) };
 }
 
+/**
+ * The member prefetch (spec Addendum 3): a whole-workspace discovery starts its members' head observations
+ * together with the host's instead of one network round after it. The member list is the one at the host's
+ * LAST observed commit (its observation record, of any age) as the parsed cache holds it — no git process
+ * decides anything here; either missing or corrupt means no prefetch. The host goes first (the session's
+ * observation slots are handed out in order). Only discoverWorkspace calls this: observeWorkspace alone (the
+ * teams reads, inspect --home) never fires member observations it would not use. Truth is unchanged: the
+ * members the answer uses come from the workspace file at the host commit observed NOW, each confirmed at
+ * its own observed commit; a member no longer listed costs one unused observation and is never read.
+ */
+function prefetchMembers(remote, ref, at) {
+  if (typeof remote.lastObservedCommit !== "function" || typeof remote.peekAtCommit !== "function" || typeof remote.prefetchObservation !== "function") return;
+  const commit = remote.lastObservedCommit(ref, { at });
+  if (!commit) return;
+  const read = remote.peekAtCommit(ref, commit, "workspace");
+  if (!read || typeof read !== "object" || read.missing || read.problems || !Array.isArray(read.value?.members)) return;
+  remote.prefetchObservation(ref, { at });
+  for (const member of read.value.members) if (typeof member === "string") remote.prefetchObservation(member);
+}
+
+/** A discovery's member row by key: the FIRST row with that key, as `find` would give, from an index built
+ *  once per members array (resolve, materialize and the CLI's facts look rows up per soul, capability and
+ *  instance: a scan each was O(rows × members)). A discovery's members array is never edited after
+ *  discoverWorkspace returns it. */
+const memberRowIndex = new WeakMap();
+export function memberRowByKey(members, key) {
+  if (!Array.isArray(members)) return null;
+  let index = memberRowIndex.get(members);
+  if (!index) {
+    index = new Map();
+    for (const m of members) if (m && !index.has(m.key)) index.set(m.key, m);
+    memberRowIndex.set(members, index);
+  }
+  return index.get(key) ?? null;
+}
+
 /** The discovery's warnings: ignored `private:`, over every listed soul. (0.30 removed the
  *  `unmapped-team-label` warning: an unmapped shared team is the readiness item `team-unmapped`.) */
 const byCodepointOrder = (a, b) => (a < b ? -1 : a > b ? 1 : 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",