@awebai/oats 0.30.3 → 0.32.0

package/lib/triggers.mjs

@@ -28,7 +28,8 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { readDefinitions, writeDefinitions, stateDir, withScopeLock, childEnv, parseEnvelopeText, schedulerStatus, readRegistry } from "./schedule.mjs";
+import { readDefinitions, writeDefinitions, stateDir, withScopeLock, childEnv, parseEnvelopeText, schedulerStatus, readRegistry, definitionsPath } from "./schedule.mjs";
+import { herdrSettingRemoved } from "./errors.mjs";
 import { MODEL_RE, automationError, baseRow, localEntry, localId, parseOwner, qualifiedId, soulOriginOf } from "./automations.mjs";
 import { lockedPackageRef } from "./packages.mjs";
 
@@ -43,7 +44,6 @@ const SOUL_RE = /^(?:[a-z0-9][a-z0-9._-]*\/)?[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const HARNESSES = new Set(["pi", "claude", "codex"]);
 /** A launch configuration name (oats-local.yaml launch-configs, docs/oats-local.schema.json). */
 const LAUNCH_CONFIG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
-const BACKENDS = new Set(["tmux", "herdr"]);
 const DEFAULT_POLL = "2m";
 const POLL_MIN_MS = 60_000;
 /** A tick runs once a minute and takes a moment: a poll due within this much is taken now. */
@@ -87,8 +87,9 @@ function checkTemplate(text, field) {
   if (bad.length) throw invalid(field, `the template may name only ${TEMPLATE_FIELDS.map((f) => `{${f}}`).join(" ")} (a PR's title and body are never templated); found ${bad.map((f) => `{${f}}`).join(" ")}`);
 }
 
-/** Validate and normalize one trigger definition. */
-export function validateTrigger(def) {
+/** Validate and normalize one trigger definition. `backendSource` names the file and key that set its
+ *  spawn.backend, for the refusal of `herdr` (Herdr was removed in 0.31.0). */
+export function validateTrigger(def, { backendSource = "the trigger's spawn.backend" } = {}) {
   if (!isObject(def)) throw invalid("definition", "must be an object");
   onlyKeys(def, ["id", "enabled", "kind", "on", "spawn", "concurrency", "template", "createdAt", "updatedAt"], "");
   if (typeof def.id !== "string" || !ID_RE.test(def.id)) throw invalid("id", "lowercase letters, digits and dashes, 1 to 40 characters");
@@ -123,7 +124,8 @@ export function validateTrigger(def) {
   if (sp.harness !== undefined && !HARNESSES.has(sp.harness)) throw invalid("spawn.harness", "pi, claude or codex");
   if (sp.model !== undefined && (typeof sp.model !== "string" || !MODEL_RE.test(sp.model))) throw invalid("spawn.model", "a model id: a letter or digit, then letters, digits and . _ : / @ + - [ ] (at most 128 characters)");
   if (sp.yolo !== undefined && typeof sp.yolo !== "boolean") throw invalid("spawn.yolo", "boolean");
-  if (sp.backend !== undefined && !BACKENDS.has(sp.backend)) throw invalid("spawn.backend", "tmux or herdr");
+  if (sp.backend === "herdr") throw Object.assign(herdrSettingRemoved(`${backendSource}: herdr`), { field: "spawn.backend", details: { field: "spawn.backend" } });
+  if (sp.backend !== undefined && sp.backend !== "tmux") throw invalid("spawn.backend", "tmux");
   const cc = def.concurrency === undefined ? {} : def.concurrency;
   if (!isObject(cc)) throw invalid("concurrency", "{ max?, perKey? }");
   onlyKeys(cc, ["max", "perKey"], "concurrency.");
@@ -207,7 +209,7 @@ export function triggerKind({ lock = null, remote = null } = {}) {
     parseBody: parseTriggerBody,
     expand: async (a) => {
       const raw = a.source.from ? await packageTriggerTemplate(lock, a.source.from, a.source.set, { id: a.name, remote }) : { ...a.source.definition };
-      const def = validateTrigger({ ...raw, id: a.name, kind: "trigger", enabled: true });
+      const def = validateTrigger({ ...raw, id: a.name, kind: "trigger", enabled: true }, { backendSource: `${a.source.from ? `package template ${a.source.from}` : a.origin?.path ?? a.name} sets spawn.backend` });
       // The owner check asks gh on the OWNER's host, and the poll runs on the REPO's host: they must be
       // one GitHub host, or polling would act as whoever is logged in there (re-review B #7).
       const owner = parseOwner(a.owner), repo = parseRepo(def.on.repo);
@@ -239,7 +241,7 @@ export function triggerEntries(ws, ctx) {
   const out = [];
   for (const [id, raw] of Object.entries(triggerJobs(ws)).sort(([a], [b]) => a.localeCompare(b))) {
     let def = null, bad = null;
-    try { def = validateTrigger(raw); } catch (e) { bad = { code: e.code, message: e.message, ...(e.field ? { field: e.field } : {}) }; }
+    try { def = validateTrigger(raw, { backendSource: `${definitionsPath(ws)} sets jobs.${id}.spawn.backend` }); } catch (e) { bad = { code: e.code, message: e.message, ...(e.field ? { field: e.field } : {}) }; }
     out.push({ ...localEntry("trigger", def ?? { ...raw, id }, { invalid: bad, dep: ws }), raw });
   }
   out.push(...(ctx?.triggers || []));
@@ -577,7 +579,7 @@ export function listTriggers(ws, ctx = null, { io } = {}) {
   };
 }
 export function addTrigger(ws, spec) {
-  const def = validateTrigger({ ...spec, kind: spec?.kind ?? "trigger" });
+  const def = validateTrigger({ ...spec, kind: spec?.kind ?? "trigger" }, { backendSource: `${definitionsPath(ws)} sets jobs.${spec?.id}.spawn.backend` });
   return withScopeLock(ws, () => {
     const defs = readDefinitions(ws);
     if (defs.jobs[def.id]) throw triggerError("E_TRIGGER_EXISTS", `${defs.jobs[def.id].kind === "trigger" ? "trigger" : "a schedule"} ${def.id} already exists in ${ws}`, { details: { id: def.id } });

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-catalog.json

@@ -8,7 +8,7 @@
     },
     "oats.aweb": {
       "url": "https://github.com/awebai/oats-aweb.git",
-      "ref": "v1.17.1",
+      "ref": "v1.17.3",
       "path": "oats-package"
     },
     "oats.jira": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.30.3",
+  "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",

package/lib/herdr.mjs

@@ -1,143 +0,0 @@
-/** Herdr 0.8.x/0.9.x host-local backend (explicit protocols 20/22).
- * SSH belongs to the CLI router. A new session records the server's protocol once; a recorded
- * target is never renegotiated. */
-import { execFileSync, spawn } from "node:child_process";
-import { existsSync, mkdirSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
-
-// The legacy protocol literal; a new session records the protocol its server reports (ensureHerdr).
-export const HERDR_PROTOCOL = 20;
-export const HERDR_SUPPORTED_PROTOCOLS = Object.freeze([20, 22]);
-export const isSupportedHerdrProtocol = (value) => HERDR_SUPPORTED_PROTOCOLS.includes(value);
-function selectedHerdrProtocol(target) {
-  if (!isSupportedHerdrProtocol(target?.protocol)) throw new Error("Herdr endpoint requires explicit supported protocol 20 or 22");
-  return target.protocol;
-}
-const quote = (s) => `'${String(s).replaceAll("'", "'\\''")}'`;
-const pause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-
-export function herdrSocket(session = "oats") {
-  if (!/^[a-zA-Z0-9_-]+$/.test(session)) throw new Error("invalid Herdr session name");
-  return join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "herdr", "sessions", session, "herdr.sock");
-}
-
-/** One Herdr CLI call on the target's socket, its stdout as text. */
-function herdrOutput(target, args, { timeout = 10000, exec = execFileSync } = {}) {
-  const env = { ...process.env, HERDR_SOCKET_PATH: target.socket };
-  delete env.HERDR_SESSION;
-  return exec(target.binary || "herdr", args, { env, encoding: "utf8", timeout, maxBuffer: 8 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
-}
-
-export function herdrCommand(target, args, io) {
-  const output = herdrOutput(target, args, io);
-  // Some successful terminal mutations have no output; reads below require
-  // their documented result shape independently.
-  if (!output.trim()) return {};
-  const response = JSON.parse(output);
-  if (response.error) throw Object.assign(new Error(response.error.message), { code: response.error.code });
-  if (!response.result) throw new Error("Herdr returned no result");
-  return response.result;
-}
-
-export function herdrSnapshot(target, io) {
-  const protocol = selectedHerdrProtocol(target);
-  const snapshot = herdrCommand(target, ["api", "snapshot"], io).snapshot;
-  if (snapshot?.protocol !== protocol) throw new Error(`Herdr snapshot does not match selected protocol ${protocol}`);
-  if (!Array.isArray(snapshot.panes)) throw new Error("Herdr snapshot has no pane inventory");
-  return snapshot;
-}
-
-/** The target for a NEW session on the server at `socket`: it records the supported protocol that server
- * reports (Herdr 0.8 speaks 20, 0.9 speaks 22). Every later call checks the snapshot against that recorded
- * protocol, so a recorded target is never renegotiated. */
-function newSessionTarget(target, io) {
-  const protocol = herdrCommand(target, ["api", "snapshot"], io).snapshot?.protocol;
-  if (!isSupportedHerdrProtocol(protocol)) throw Object.assign(new Error(`Herdr server speaks protocol ${protocol ?? "unknown"}; OATS supports ${HERDR_SUPPORTED_PROTOCOLS.join(" and ")}`), { unsupportedProtocol: true });
-  const selected = { ...target, protocol };
-  herdrSnapshot(selected, io);
-  return selected;
-}
-
-export function ensureHerdr({ binary = "herdr", socket, session = "oats", io } = {}) {
-  const target = { backend: "herdr", binary, socket: resolve(socket || herdrSocket(session)) };
-  try { return newSessionTarget(target, io); }
-  catch (e) {
-    // An explicit socket belongs to an operator-managed server. Never start a
-    // different server when it cannot be inspected or is incompatible.
-    if (socket || existsSync(target.socket)) throw e;
-  }
-  mkdirSync(dirname(target.socket), { recursive: true });
-  const env = { ...process.env };
-  delete env.HERDR_SESSION; delete env.HERDR_SOCKET_PATH;
-  const child = spawn(binary, ["--session", session, "server"], { detached: true, stdio: "ignore", env });
-  child.on("error", () => {});
-  child.unref();
-  let error;
-  for (let i = 0; i < 30; i++) {
-    pause(100);
-    // A server that answers with an unsupported protocol is up: waiting longer cannot change its answer.
-    try { return newSessionTarget(target, io); } catch (e) { if (e.unsupportedProtocol) throw e; error = e; }
-  }
-  throw new Error(`Herdr did not start: ${error?.message || "no socket"}`);
-}
-
-export function allocateHerdr(target, { home, instance }, io) {
-  const protocol = selectedHerdrProtocol(target);
-  const result = herdrCommand(target, ["workspace", "create", "--cwd", home, "--label", instance, "--no-focus"], io);
-  const pane = result.root_pane;
-  if (!pane?.pane_id || !pane?.terminal_id || !pane?.workspace_id) throw new Error("Herdr allocation returned no session identity");
-  return { ...target, protocol, workspaceId: pane.workspace_id, paneId: pane.pane_id, terminalId: pane.terminal_id };
-}
-
-export function inspectHerdr(target, io) {
-  const snapshot = herdrSnapshot(target, io);
-  const matches = snapshot.panes.filter((p) => p.pane_id === target.paneId && p.terminal_id === target.terminalId);
-  if (io?.strictHerdrTarget && (matches.length > 1 || (matches.length === 1 && matches[0].workspace_id !== target.workspaceId))) throw new Error("Herdr target workspace/pane/terminal identity is ambiguous or changed");
-  const pane = matches[0];
-  const agent = pane && snapshot.agents?.find((a) => a.terminal_id === target.terminalId);
-  return { present: !!pane, pane, agent, status: agent?.agent_status || "unknown" };
-}
-
-/** Wait until a new pane's shell has drawn something (its prompt) before typing into it. Text typed
- * earlier sits in the terminal's canonical line buffer, which drops a line past 1024 bytes on macOS:
- * a launch command is longer than that, and arrived cut. Bounded; a Herdr that cannot read a pane
- * leaves the old behaviour (type at once). */
-function awaitShellReady(target, io) {
-  const deadline = Date.now() + (io?.shellReadyMs ?? 10000);
-  for (;;) {
-    let text;
-    // `pane read` answers the screen as plain text, not a JSON envelope.
-    const remaining = Math.max(100, deadline - Date.now());
-    try { text = herdrOutput(target, ["pane", "read", target.paneId, "--source", "visible"], { ...io, timeout: Math.min(2000, remaining) }); }
-    catch { return; }
-    if (typeof text === "string" && text.trim()) return;
-    if (Date.now() >= deadline) return;
-    pause(100);
-  }
-}
-
-export function launchHerdr(target, command, io) {
-  if (!inspectHerdr(target, io).present) throw new Error("Herdr launch pane disappeared");
-  awaitShellReady(target, io);
-  // This is the allocated shell's one launch command. Exec avoids a fallback
-  // shell that could accidentally consume a subsequent agent notification.
-  herdrCommand(target, ["pane", "run", target.paneId, `exec /bin/sh -c ${quote(command)}`], io);
-}
-
-export function stopHerdr(target, io) {
-  if (!inspectHerdr(target, io).present) return;
-  try { herdrCommand(target, ["pane", "close", target.paneId], io); } catch { /* inspect the effect even if the pane exited concurrently */ }
-  if (inspectHerdr(target, io).present) throw new Error(`Herdr pane ${target.paneId} is still present`);
-}
-
-export function inputHerdr(target, text, io) {
-  if (!inspectHerdr(target, io).present) throw new Error("Herdr session stopped or was replaced");
-  herdrCommand(target, ["pane", "run", target.paneId, text], io);
-}
-
-export function validHerdrTarget(value) {
-  return value?.backend === "herdr" && isSupportedHerdrProtocol(value.protocol)
-    && [value.socket, value.binary, value.workspaceId, value.paneId, value.terminalId].every((v) => typeof v === "string" && v.length > 0)
-    && value.socket === resolve(value.socket);
-}