@cat-factory/orchestration 0.296.0 → 0.298.0

package/dist/modules/bootstrap/monorepoSurvey.js

@@ -1,26 +1,41 @@
-import { getErrorMessage } from '@cat-factory/kernel';
+import { MAX_ADOPTION_READ_PATH, MAX_ADOPTION_READS } from '@cat-factory/contracts';
+import { getErrorMessage, redactSecrets } from '@cat-factory/kernel';
 // ---------------------------------------------------------------------------
-// The DETERMINISTIC half of a monorepo bootstrap's survey: what the two sides actually
-// contain, read through the checkout-free `RepoFiles` port.
+// A monorepo bootstrap's SURVEY: what the two sides actually contain, read through the
+// checkout-free `RepoFiles` port.
 //
-// The platform computes this and the model only JUDGES it. That split is the whole reason the
-// suggestion is worth reviewing: a recommendation is checkable against a named file a human can
-// open, and a claim about a convention that cites nothing the survey read is dropped upstream
-// (`parseAdoptionDecisions`) rather than shown as if the platform had verified it.
+// The read is in two halves, and the split is the whole design. The platform SEEDS an opening
+// context (each side's root listing and the convention files it really holds, whichever CI
+// declaration its provider uses, and the listing of every sibling that looks like a service),
+// because there is no reason to spend model calls rediscovering `package.json` and it keeps the
+// cheap case cheap. The MODEL then widens it: it asks for the CI workflow that will actually gate
+// the pull request, follows a dependency into the shared package that says what adopting it
+// entails, and opens a second and a third sibling when the first two disagree. None of that is
+// enumerable in advance, which is why the previous declared list decided what the survey could
+// not see before it looked.
 //
-// Two rules shape the reads. Everything probed is a BOUNDED, declared list (no crawl, no
-// recursive walk), so the cost of a survey does not scale with the size of the monorepo it is
-// landing in. And every read that FAILS is recorded as unreadable rather than skipped, because a
-// plan built without the monorepo's CI is materially weaker than one built with it, and only the
-// survey can say which of the two a reviewer is looking at.
+// What the platform keeps is the BOOKKEEPING. Every read, seeded or model-chosen, is budgeted,
+// scrubbed and appended to ONE transcript, and that transcript is what the plan carries, so a
+// recommendation stays checkable against a record the model could not write
+// (`parseAdoptionDecisions` drops a citation naming anything the transcript does not hold as
+// READ). The bound is a call ceiling plus a character ceiling rather than a declared path list,
+// so the cost of a survey still does not scale with the size of the monorepo it lands in.
+//
+// Every read that FAILS is recorded as unreadable rather than skipped, and one the platform
+// declines is recorded as refused: a plan built without the monorepo's CI is materially weaker
+// than one built with it, and only the transcript can say which of the two a reviewer has.
 // ---------------------------------------------------------------------------
 /**
  * The root-level files that carry a repository's conventions, in priority order.
  *
  * Cross-ecosystem on purpose: the flow is not JS-specific, and a Go or JVM monorepo whose
- * conventions this list cannot see would produce a survey that silently found "nothing", the
+ * conventions this list cannot see would produce a seed that silently found "nothing", the
  * failure mode this whole module exists to avoid. Probed by INTERSECTION with a directory
  * listing, so naming a file no repository has costs nothing.
+ *
+ * Still a declared list, and deliberately so: it is the OPENING context and the test a candidate
+ * directory has to pass to count as a service, not the boundary of what the survey can see.
+ * Anything it misses, the model can go and read.
  */
 const CONVENTION_FILES = [
     'package.json',
@@ -58,41 +73,156 @@ const CONVENTION_FILES = [
     'CONTRIBUTING.md',
     'README.md',
 ];
-/** Directory listings probed on the monorepo root for its CI wiring. */
-const CI_DIRECTORIES = ['.github/workflows', '.gitlab-ci.yml', '.circleci'];
 /**
- * How many candidate siblings are examined before one is chosen as the worked example.
+ * The CI directories the seed LISTS (never reads), each gated on the root entry that holds it.
+ *
+ * Listing rather than reading is the correction the tool loop makes possible: a monorepo with
+ * reusable workflows plus thirty per-service ones used to contribute an arbitrary two, and what
+ * a new directory is actually REQUIRED to satisfy (a path filter, a required check) was likely
+ * in one of the twenty-eight nobody read. The listing is the menu; the model picks off it.
+ *
+ * Every provider the platform pushes to is named, for the same reason {@link CONVENTION_FILES}
+ * is cross-ecosystem: a GitLab-hosted monorepo has no `.github` at all, so a seed that knows
+ * only GitHub hands the model an opening context with NO CI in it and leaves the `ci` area with
+ * nothing citable on exactly the deployments this platform supports as first-class. Probed by
+ * intersection with the root listing, so naming a provider no repository here uses costs nothing.
+ */
+const CI_DIRECTORIES = [
+    { rootEntry: '.github', path: '.github/workflows' },
+    { rootEntry: '.circleci', path: '.circleci' },
+];
+/**
+ * CI declarations that are a single root FILE, so there is no directory to offer as a menu.
+ *
+ * Read outside the {@link MAX_ROOT_FILES} convention cap deliberately: this is the whole of what
+ * its provider says about CI, and losing it to fourteen manifests would leave the `ci` area
+ * unevidenced on a repository that states its pipeline perfectly clearly.
+ */
+const CI_FILES = ['.gitlab-ci.yml'];
+/**
+ * How many sibling directories are probed as candidate worked examples.
  *
- * Bounded like every other read here, and >1 because the FIRST entry of a services directory is
- * not a service in any repository that also keeps tooling there: an alphabetical pick lands on
- * `.github`, `.changeset` or a `docs/` folder and then reports CI config to the reviewer as what
- * a service in this monorepo looks like. Dot-entries are excluded outright (below) and the rest
- * are probed in order until one holds a convention file of its own.
+ * Higher than the old pick-one probe because the seed no longer reads their files: a candidate
+ * costs one listing, and offering several is what makes a monorepo whose services DISAGREE
+ * representable at all. Dot-entries are excluded outright, and a candidate qualifies only by
+ * holding a convention file of its own.
+ */
+const MAX_SIBLING_CANDIDATES = 6;
+/**
+ * Per-BODY content cap, on a directory listing as much as on a file.
+ *
+ * A convention is legible from its opening and a lockfile-sized read is not, and the same bound
+ * has to reach a listing: a generated or vendored directory with five thousand entries renders a
+ * body two budgets wide, which the exploration charge can only answer by refusing, latching
+ * `exhausted` and reporting a survey that spent almost nothing as one that ran out of content.
  */
-const MAX_SIBLING_CANDIDATES = 4;
-/** Per-file content cap. A convention is legible from its opening; a lockfile-sized read is not. */
 const MAX_FILE_CHARS = 6_000;
-/** How many root files one side contributes, most-conventional first. */
+/** How many root files one side contributes to the opening context, most-conventional first. */
 const MAX_ROOT_FILES = 14;
-/** How many files the worked-example sibling service contributes. */
-const MAX_SIBLING_FILES = 10;
-/** How many CI workflow files are read (they repeat heavily past the first couple). */
-const MAX_CI_FILES = 2;
+/**
+ * The opening context's TOTAL character budget, split into an equal reservation per side.
+ *
+ * Spent in key order it would not be a bound at all but a handover to whichever side sorts
+ * first, and `monorepo:` sorts before `template:` for every key: a large monorepo would spend
+ * the whole allowance and the template would land entirely refused, which is exactly the
+ * crowding-out this exists to prevent. So a run with no template reserves all of it for the
+ * monorepo and a run with one gives each side half, spent in its own priority order; whatever a
+ * side leaves unspent carries to the next, which makes the reservation a floor rather than a cap.
+ */
+const MAX_SEED_CHARS = 36_000;
+/** How many reads the MODEL may ask for. The loop's hard ceiling; see {@link AdoptionExploration}. */
+const MAX_EXPLORATION_CALLS = 24;
+/** How many characters the model's own reads may spend, on top of the seed's reservation. */
+const MAX_EXPLORATION_CHARS = 54_000;
+const DEFAULT_LIMITS = {
+    maxExplorationCalls: MAX_EXPLORATION_CALLS,
+    maxExplorationChars: MAX_EXPLORATION_CHARS,
+    maxSeedChars: MAX_SEED_CHARS,
+    maxFileChars: MAX_FILE_CHARS,
+};
 /** The parent directory a new service's siblings live in, or `''` for a root-level service. */
 export function parentDirectoryOf(directory) {
     const segments = directory.split('/').filter(Boolean);
     return segments.slice(0, -1).join('/');
 }
+/**
+ * The longest raw path a model may ask for.
+ *
+ * Derived from the contract rather than restated: what the transcript records is the PREFIXED
+ * key, so the longest side name and a listing's trailing slash both have to fit inside
+ * {@link MAX_ADOPTION_READ_PATH} beside the path itself. Restating 400 here emitted a row the
+ * schema calls too long for any path over 390.
+ */
+const MAX_SURVEY_PATH = MAX_ADOPTION_READ_PATH - 'template:'.length - 1;
+/**
+ * A repository-relative path the platform is willing to fetch, or the reason it will not.
+ *
+ * The path is MODEL-AUTHORED and is interpolated into the VCS contents API's URL, so it is
+ * validated for magic rather than only for traversal, and both halves of that bite:
+ *
+ *  - a control character or a backslash means the model is guessing at a shell or a Windows
+ *    path, and answering "not found" would tell it the repository lacks a file it never actually
+ *    asked for;
+ *  - `?`, `#` and `%` are the URL's own syntax, and the caller appends its `?ref=` AFTER this
+ *    path. A `#` truncates the request to a DIFFERENT file while the transcript records the whole
+ *    string as read, so a citation lands on the plan pointing at a path no reviewer can open; a
+ *    `?ref=` of the model's own is honoured over the branch the survey believes it is reading;
+ *    and a percent escape puts the traversal check below on the wrong side of the decoding the
+ *    host, not this process, performs.
+ *
+ * A refusal is REPORTED (it lands on the transcript and the model is told), never a silent
+ * shortening.
+ */
+export function normalizeSurveyPath(raw) {
+    const trimmed = raw.trim().replace(/^\.\//, '').replace(/^\/+/, '').replace(/\/+$/, '');
+    if (trimmed.length > MAX_SURVEY_PATH) {
+        return { refused: 'the path is too long to be a repository path' };
+    }
+    if (trimmed.includes('\\') || [...trimmed].some((ch) => ch.charCodeAt(0) < 0x20)) {
+        return { refused: 'the path contains characters that are not part of a repository path' };
+    }
+    if (/[?#%]/.test(trimmed)) {
+        return {
+            refused: 'the path contains URL syntax (? # or %), which is not part of a repository path',
+        };
+    }
+    const segments = trimmed.split('/');
+    if (segments.some((segment) => segment === '..')) {
+        return { refused: 'the path leaves the repository; give a path relative to its root' };
+    }
+    return { path: segments.filter((segment) => segment !== '.').join('/') };
+}
+/** The citable key one read produces: `<side>:<path>`, with a trailing `/` marking a listing. */
+function keyFor(side, kind, path) {
+    if (kind === 'read')
+        return `${side}:${path}`;
+    // `./` for the root, so a listing always reads as one and no key ends in a bare colon.
+    return `${side}:${path ? `${path}/` : './'}`;
+}
 /** Clip one file's content to the per-file cap, stating the clip rather than hiding it. */
-function clip(content) {
-    if (content.length <= MAX_FILE_CHARS)
+function clip(content, max) {
+    if (content.length <= max)
         return content;
-    return `${content.slice(0, MAX_FILE_CHARS)}\n…[truncated: ${content.length - MAX_FILE_CHARS} more characters not shown]`;
+    return `${content.slice(0, max)}\n…[truncated: ${content.length - max} more characters not shown]`;
+}
+/**
+ * Render a directory's entries as the body a decision can cite for layout, under the same
+ * per-body cap a file read answers to.
+ *
+ * Uncapped, one listing of a generated directory could be wider than the whole exploration
+ * budget, and the only answer a charge has to a body it cannot fit is to refuse it and latch
+ * `exhausted`, reporting a content budget that ran out when nothing had been spent.
+ */
+function renderListing(entries, max) {
+    return clip(entries
+        .map((entry) => `${entry.name}${entry.type === 'dir' ? '/' : ''}`)
+        .sort()
+        .join('\n'), max);
 }
 /**
- * One side's reader, accumulating what it read and what it could not.
+ * One side's raw reader: performs the IO, hands bodies and failures to the ledger.
  *
- * `unreadable` is the load-bearing half. A `getFile` that THROWS is a provider failure (a
+ * `unreadable` is the load-bearing distinction. A `getFile` that THROWS is a provider failure (a
  * revoked token, a rate limit, an outage), and it is not the same fact as the file being absent
  * (which `getFile` reports as `null`). Collapsing the two would let a survey blinded by an
  * expired installation token present itself as a monorepo with no conventions.
@@ -100,190 +230,513 @@ function clip(content) {
 class SideReader {
     side;
     prefix;
-    logger;
-    read = [];
-    unreadable = [];
-    contents = {};
-    constructor(side, prefix, logger) {
+    constructor(side, prefix) {
         this.side = side;
         this.prefix = prefix;
-        this.logger = logger;
     }
-    /** Entry names of a directory, or null when it could not be listed (recorded as unreadable). */
+    /** Entry names of a directory, or the failure that stopped the listing. */
     async list(path) {
         try {
-            return await this.side.files.listDirectory(path, this.side.gitRef);
+            return { entries: await this.side.files.listDirectory(path, this.side.gitRef) };
         }
         catch (error) {
-            this.unreadable.push(`${path || '.'}/`);
-            this.logger?.warn('monorepo survey: directory listing failed', {
-                side: this.prefix,
-                path,
-                err: getErrorMessage(error),
-            });
-            return null;
+            return { failed: getErrorMessage(error) };
         }
     }
-    /** Read one file into the survey; absent is silent, unreadable is recorded. */
-    async take(path) {
+    /** One file's content, `null` when it is simply absent, or the failure that stopped the read. */
+    async read(path) {
         try {
             const file = await this.side.files.getFile(path, this.side.gitRef);
-            if (!file)
-                return;
-            this.read.push(path);
-            this.contents[`${this.prefix}:${path}`] = clip(file.content);
+            return { content: file ? file.content : null };
         }
         catch (error) {
-            this.unreadable.push(path);
-            this.logger?.warn('monorepo survey: file read failed', {
-                side: this.prefix,
-                path,
-                err: getErrorMessage(error),
+            return { failed: getErrorMessage(error) };
+        }
+    }
+}
+/**
+ * A monorepo survey in progress: the transcript, the budgets, and the reader the model widens it
+ * through.
+ *
+ * Created before the model is asked anything, seeded once, then handed to the advisor. The
+ * caller re-reads {@link survey} AFTER the advisor returns, because the transcript is what the
+ * model actually fetched rather than what the platform predicted it would need.
+ */
+export class MonorepoSurveySession {
+    request;
+    limits;
+    readers;
+    log;
+    reads = [];
+    bodies = {};
+    /**
+     * Seed bodies that were FETCHED but did not fit the opening context's reservation.
+     *
+     * Held rather than dropped: the prompt names them and tells the model to ask, so throwing the
+     * bytes away buys a second contents-API round trip for content this process is already
+     * holding. Kept OUT of {@link bodies} so nothing is citable before it has actually been served,
+     * and out of {@link seedKeys} so it stays out of the opening prompt.
+     */
+    withheld = {};
+    seedKeys = new Set();
+    siblings = [];
+    calls = 0;
+    explorationChars = 0;
+    recordsDropped = 0;
+    exhausted = null;
+    constructor(request) {
+        this.request = request;
+        this.limits = { ...DEFAULT_LIMITS, ...request.limits };
+        this.log = request.logger;
+        this.readers = {
+            monorepo: new SideReader(request.monorepo, 'monorepo'),
+            ...(request.template ? { template: new SideReader(request.template, 'template') } : {}),
+        };
+    }
+    get sides() {
+        return Object.keys(this.readers);
+    }
+    /** The transcript, the siblings offered, and what the exploration spent, as of right now. */
+    survey() {
+        return {
+            reads: [...this.reads],
+            siblingServices: [...this.siblings],
+            exploration: {
+                calls: this.calls,
+                maxCalls: this.limits.maxExplorationCalls,
+                chars: this.explorationChars,
+                maxChars: this.limits.maxExplorationChars,
+                exhausted: this.exhausted,
+                recordsDropped: this.recordsDropped,
+            },
+        };
+    }
+    /**
+     * The bodies rendered into the model's OPENING prompt.
+     *
+     * Only the seeded ones: everything the model fetches afterwards reaches it as that tool call's
+     * own result, and folding those into the prompt too would send each body twice.
+     */
+    seedFiles() {
+        const seeded = {};
+        for (const key of this.seedKeys) {
+            const body = this.bodies[key];
+            if (body !== undefined)
+                seeded[key] = body;
+        }
+        return seeded;
+    }
+    /**
+     * Record something the platform could not even attempt, so it does not read as an absence.
+     *
+     * The one caller is a reference template the workspace has not LINKED: unreadable from here
+     * even though the apply phase's container can still clone it. "The template ships nothing for
+     * this area" and "nobody looked at the template" lead a reviewer to opposite conclusions.
+     */
+    noteUnavailable(side, path, note) {
+        this.record({ path: `${side}:${path}`, origin: 'seed', outcome: 'unreadable', chars: 0, note });
+    }
+    /**
+     * Read the opening context: each side's root, the CI directory, and every sibling that looks
+     * like a service.
+     *
+     * The sibling probe is the read no root file can stand in for, and it is a LIST rather than a
+     * pick. One sibling is a sample of size one, so a monorepo with a six-year-old Java service
+     * beside three new TypeScript ones has no single house convention, and naming whichever
+     * directory sorted first reports a disagreement as though it were the answer. Dot-entries are
+     * excluded (`.github` sorts below every letter, so an alphabetical pick landed on a workflows
+     * folder for any root-level target) and a candidate qualifies only by holding a convention file
+     * of its own.
+     */
+    async seed() {
+        const harvests = [];
+        const mono = this.readers.monorepo;
+        if (mono)
+            harvests.push({ reader: mono, harvest: await this.seedMonorepo(mono) });
+        const template = this.readers.template;
+        if (template)
+            harvests.push({ reader: template, harvest: await this.seedTemplate(template) });
+        this.commitSeed(harvests.map((entry) => entry.harvest));
+    }
+    async seedMonorepo(reader) {
+        const candidates = [];
+        const root = await this.seedRoot(reader, candidates);
+        const parent = parentDirectoryOf(this.request.directory);
+        // Re-uses the root listing for a root-level target rather than asking for it twice. The
+        // parent's own listing contributes no citable entry (the empty candidate sink): it is the
+        // MENU the sibling probe reads, and each qualifying sibling's listing carries the layout
+        // evidence. A failure to list it is still recorded, because "no siblings" and "could not see
+        // whether there are siblings" are opposite facts.
+        const siblingEntries = parent === '' ? root : await this.listInto(reader, parent, []);
+        const siblings = await this.probeSiblings(reader, siblingEntries, candidates);
+        return { candidates, siblings };
+    }
+    async seedTemplate(reader) {
+        const candidates = [];
+        await this.seedRoot(reader, candidates);
+        return { candidates, siblings: [] };
+    }
+    /**
+     * What BOTH sides contribute: the root listing, the conventions it holds, and its CI.
+     *
+     * Shared rather than the monorepo's alone, because `ci` is a decision BETWEEN the two sides and
+     * a seed that evidences only one of them biases it in the direction the prompt spends a
+     * paragraph forbidding: an area nothing was read about is not an area the other side wins.
+     */
+    async seedRoot(reader, candidates) {
+        const root = await this.listInto(reader, '', candidates);
+        if (!root)
+            return null;
+        await this.takeRootFiles(reader, root, candidates);
+        for (const ci of CI_DIRECTORIES) {
+            if (root.some((entry) => entry.name === ci.rootEntry)) {
+                await this.listInto(reader, ci.path, candidates);
+            }
+        }
+        return root;
+    }
+    /**
+     * List a directory, recording the listing as a citable seed entry.
+     *
+     * The listing costs no extra request (it is the one the seed already needed) and it is the only
+     * evidence either side offers about source layout and module structure: no root manifest states
+     * where a service puts its code, its tests or its entry point. Without it, a `source-layout`
+     * recommendation cites nothing and is dropped upstream as invention, so `template` was the only
+     * answer the model could legitimately give for that area on every monorepo.
+     */
+    async listInto(reader, path, candidates) {
+        const key = keyFor(reader.prefix, 'list', path);
+        const result = await reader.list(path);
+        if ('failed' in result) {
+            this.noteListingFailure(reader, path, result.failed);
+            return null;
+        }
+        if (result.entries.length === 0) {
+            this.record({
+                path: key,
+                origin: 'seed',
+                outcome: 'absent',
+                chars: 0,
+                note: 'the directory is empty or does not exist',
             });
+            return result.entries;
         }
+        candidates.push({ key, body: renderListing(result.entries, this.limits.maxFileChars) });
+        return result.entries;
     }
     /**
-     * Record a directory's SHAPE as a citable survey entry.
+     * A seed listing that FAILED: warned and recorded as unreadable, never skipped.
      *
-     * The listing is already in hand (nothing is re-read), and it is the only evidence the survey
-     * has for `source-layout` and module structure: no root manifest states where a service puts
-     * its code, its tests or its entry point, and the sibling's own config files do not either. A
-     * recommendation about layout that cites nothing is dropped upstream as invention, so without
-     * this the model can only ever answer `template` for one of the twelve areas it is asked
-     * about. Recorded under the directory path with a trailing slash, so the key a decision cites
-     * is visibly a listing rather than a file.
+     * Shared with the sibling probe, which is the read where skipping costs the most. "No sibling
+     * service" is the strongest claim the opening context makes about a monorepo (it tells the
+     * model there is no worked example and it tells the reviewer the survey saw root conventions
+     * only), so a probe blinded by a revoked token or a rate limit has to say so rather than
+     * produce the sentence a genuinely flat repository produces.
      */
-    noteLayout(dir, entries) {
-        if (entries.length === 0)
-            return;
-        // `./` for the root, matching how `list` names an unreadable root, so no key is a bare slash.
-        const path = dir ? `${dir}/` : './';
-        this.read.push(path);
-        this.contents[`${this.prefix}:${path}`] = entries
-            .map((entry) => `${entry.name}${entry.type === 'dir' ? '/' : ''}`)
-            .sort()
-            .join('\n');
+    noteListingFailure(reader, path, cause) {
+        this.log?.warn('monorepo survey: directory listing failed', {
+            side: reader.prefix,
+            path,
+            err: cause,
+        });
+        this.record({
+            path: keyFor(reader.prefix, 'list', path),
+            origin: 'seed',
+            outcome: 'unreadable',
+            chars: 0,
+            note: cause,
+        });
     }
     /**
-     * Read the convention files a listed directory actually holds, in the declared priority order
-     * and capped. Reads run concurrently: the set is bounded and declared, so this is one fixed
-     * fan-out rather than a loop that grows with the repository.
+     * The root files one side contributes: its conventions, capped in priority order, plus any
+     * single-file CI declaration.
+     *
+     * The two lists are read together but capped apart. A CI file competing for the convention cap
+     * would be crowded out by fourteen manifests on exactly the repositories whose CI is a single
+     * file, which is the `ci` area losing its only evidence to a tie-break nobody chose.
      */
-    async takeConventionFiles(dir, entries, limit) {
+    async takeRootFiles(reader, entries, candidates) {
         const present = new Set(entries.filter((entry) => entry.type === 'file').map((entry) => entry.name));
-        const wanted = CONVENTION_FILES.filter((name) => present.has(name)).slice(0, limit);
-        await Promise.all(wanted.map((name) => this.take(dir ? `${dir}/${name}` : name)));
+        await this.takeFiles(reader, '', [
+            ...CONVENTION_FILES.filter((name) => present.has(name)).slice(0, MAX_ROOT_FILES),
+            ...CI_FILES.filter((name) => present.has(name)),
+        ], candidates);
     }
-}
-/**
- * Entries of `parent` that could plausibly be a sibling SERVICE, in probe order.
- *
- * Excludes the target itself, every dot-entry, and the CI directories the survey has already
- * read: `.github` sorts below every letter, so an alphabetical pick over a raw listing returns
- * it for any root-level target, and the reviewer is then told a workflows folder is "the best
- * available statement of what a service in this monorepo looks like".
- */
-function siblingCandidates(entries, directory) {
-    const excluded = new Set(CI_DIRECTORIES);
-    return entries
-        .filter((entry) => entry.type === 'dir' &&
-        entry.path !== directory &&
-        !entry.name.startsWith('.') &&
-        !excluded.has(entry.path))
-        .map((entry) => entry.path)
-        .sort()
-        .slice(0, MAX_SIBLING_CANDIDATES);
-}
-/**
- * Choose one existing sibling as the monorepo's worked example, read it, and return its path.
- *
- * A candidate has to actually look like a service: a directory holding no convention file of its
- * own says nothing about how a service here is built, and presenting it as the example is worse
- * than presenting none, because "no sibling" is a fact the plan REPORTS while a bad sibling is
- * one it asserts. Returns null when nothing qualifies, which the survey carries through as
- * `siblingService: null` and the prompt states outright.
- */
-async function pickSiblingService(mono, entries, directory) {
-    if (!entries)
-        return null;
-    for (const candidate of siblingCandidates(entries, directory)) {
-        const own = await mono.list(candidate);
-        if (!own)
-            continue;
-        const names = new Set(own.filter((entry) => entry.type === 'file').map((entry) => entry.name));
-        if (!CONVENTION_FILES.some((name) => names.has(name)))
-            continue;
-        // The SHAPE first (it is the only evidence for layout), then the files themselves.
-        mono.noteLayout(candidate, own);
-        await mono.takeConventionFiles(candidate, own, MAX_SIBLING_FILES);
-        return candidate;
+    /** Read a named set of files a directory actually holds, in the order they were named. */
+    async takeFiles(reader, dir, wanted, candidates) {
+        // One fixed fan-out: the set is bounded and declared, so this never grows with the repository.
+        const results = await Promise.all(wanted.map(async (name) => {
+            const path = dir ? `${dir}/${name}` : name;
+            return { path, result: await reader.read(path) };
+        }));
+        for (const { path, result } of results) {
+            const key = keyFor(reader.prefix, 'read', path);
+            if ('failed' in result) {
+                this.log?.warn('monorepo survey: file read failed', {
+                    side: reader.prefix,
+                    path,
+                    err: result.failed,
+                });
+                this.record({
+                    path: key,
+                    origin: 'seed',
+                    outcome: 'unreadable',
+                    chars: 0,
+                    note: result.failed,
+                });
+                continue;
+            }
+            // Absent is silent here: the set was intersected with a real listing, so a null means the
+            // entry vanished between the two calls, which says nothing a reviewer needs.
+            if (result.content === null)
+                continue;
+            candidates.push({ key, body: clip(this.scrub(result.content), this.limits.maxFileChars) });
+        }
+    }
+    /**
+     * List every plausible sibling service, keeping the ones that hold a convention file.
+     *
+     * Excludes the target itself and every dot-entry (which is also what keeps the CI folder out,
+     * since a listing's entries are one level deep): a directory that says nothing about how a
+     * service here is built is worse than no example, because "no sibling" is a fact the plan
+     * REPORTS while a bad sibling is one it asserts.
+     *
+     * One bounded fan-out rather than a loop of awaits, the shape {@link takeFiles} already uses:
+     * the candidate set is capped above, so six sequential round trips to the VCS host sat in the
+     * opening context's critical path for nothing.
+     */
+    async probeSiblings(reader, entries, candidates) {
+        if (!entries)
+            return [];
+        const target = this.request.directory;
+        const probes = entries
+            .filter((entry) => entry.type === 'dir' && entry.path !== target && !entry.name.startsWith('.'))
+            .map((entry) => entry.path)
+            .sort()
+            .slice(0, MAX_SIBLING_CANDIDATES);
+        const listings = await Promise.all(probes.map(async (path) => ({ path, result: await reader.list(path) })));
+        const qualifying = [];
+        for (const { path, result } of listings) {
+            if ('failed' in result) {
+                this.noteListingFailure(reader, path, result.failed);
+                continue;
+            }
+            const names = new Set(result.entries.filter((e) => e.type === 'file').map((e) => e.name));
+            if (!CONVENTION_FILES.some((name) => names.has(name)))
+                continue;
+            qualifying.push(path);
+            candidates.push({
+                key: keyFor(reader.prefix, 'list', path),
+                body: renderListing(result.entries, this.limits.maxFileChars),
+            });
+        }
+        return qualifying;
+    }
+    /**
+     * Apply the per-side reservation to everything the seed fetched, and record the result.
+     *
+     * A body that does not fit is recorded `refused` rather than dropped, for the same reason the
+     * survey reports what it could not read: the model must not treat a file it was never shown as
+     * a file that does not exist, and the reviewer sees the same list. The BYTES are kept even so
+     * (see {@link withheld}), because the note invites the model to ask for them and re-fetching
+     * what is already in memory is a round trip for nothing. Whatever an earlier side leaves
+     * unspent carries forward, so the reservation is a floor rather than a ceiling.
+     */
+    commitSeed(harvests) {
+        const share = Math.floor(this.limits.maxSeedChars / Math.max(1, harvests.length));
+        let spare = this.limits.maxSeedChars - share * harvests.length;
+        for (const harvest of harvests) {
+            this.siblings = [...this.siblings, ...harvest.siblings];
+            let budget = share + spare;
+            for (const candidate of harvest.candidates) {
+                if (candidate.body.length > budget) {
+                    this.withheld[candidate.key] = candidate.body;
+                    this.record({
+                        path: candidate.key,
+                        origin: 'seed',
+                        outcome: 'refused',
+                        chars: 0,
+                        note: 'read, but it did not fit the opening context; ask for it if you need it',
+                    });
+                    continue;
+                }
+                budget -= candidate.body.length;
+                this.bodies[candidate.key] = candidate.body;
+                this.seedKeys.add(candidate.key);
+                this.record({
+                    path: candidate.key,
+                    origin: 'seed',
+                    outcome: 'read',
+                    chars: candidate.body.length,
+                    note: null,
+                });
+            }
+            spare = budget;
+        }
+    }
+    /**
+     * One model-chosen read, charged against the exploration budget.
+     *
+     * The call is counted BEFORE anything else, refusals included: a model emitting nonsense paths
+     * would otherwise loop until the step cap fired, having read nothing. Budget exhaustion is
+     * answered rather than thrown, so the model is told what it has left and can produce a plan
+     * that says which areas it ran short on, instead of the loop ending with no reply at all.
+     */
+    async explore(request) {
+        this.calls += 1;
+        const reader = this.readers[request.side];
+        if (!reader) {
+            return this.refuse(request, `there is no ${request.side} repository in this run to read`);
+        }
+        if (this.calls > this.limits.maxExplorationCalls) {
+            this.exhausted = 'calls';
+            return this.refuse(request, `the exploration budget is spent (${this.limits.maxExplorationCalls} reads). Answer from ` +
+                `what you have already seen, and say in the rationale which areas you could not check`);
+        }
+        const normalized = normalizeSurveyPath(request.path);
+        if ('refused' in normalized)
+            return this.refuse(request, normalized.refused);
+        const path = normalized.path;
+        if (request.kind === 'read' && path === '') {
+            return this.refuse(request, 'name the file to read, relative to the repository root');
+        }
+        // The new service does not exist yet, but a RETRY surveying after a partial run would find
+        // whatever the previous attempt left there. Reading it back as the monorepo's established
+        // convention is the platform citing its own draft to itself.
+        if (request.side === 'monorepo' && this.isInsideTarget(path)) {
+            return this.refuse(request, `${this.request.directory} is the service being created, not an existing one; read a sibling instead`);
+        }
+        const key = keyFor(request.side, request.kind, path);
+        const cached = this.bodies[key];
+        // Already fetched (seeded, or asked for twice): answer from what was read rather than
+        // spending a second read of the same bytes on a bounded budget. No new transcript row, since
+        // it names a read already recorded; the CALL is still counted, so a model re-requesting the
+        // same file cannot buy itself an unbounded loop.
+        if (cached !== undefined) {
+            return { outcome: 'read', body: cached, note: null, key };
+        }
+        // Fetched during the seed but never shown, so the model taking the prompt's advice and asking
+        // for it costs no round trip. CHARGED all the same: the bytes enter the model's context now,
+        // which is what the exploration budget bounds, and it takes a `read` row of its own beside the
+        // seed's `refused` one, because the citation check upstream keys on the OUTCOME.
+        const withheld = this.withheld[key];
+        if (withheld !== undefined) {
+            const answer = this.charge(key, withheld);
+            // Dropped only once it is SERVED: a charge refused for an exhausted budget must leave the
+            // body where it is, so a later call with room can still answer it without a second fetch.
+            if (answer.outcome === 'read')
+                delete this.withheld[key];
+            return answer;
+        }
+        return request.kind === 'list'
+            ? await this.exploreList(reader, path, key)
+            : await this.exploreRead(reader, path, key);
+    }
+    async exploreList(reader, path, key) {
+        const result = await reader.list(path);
+        if ('failed' in result)
+            return this.fail(key, result.failed);
+        if (result.entries.length === 0) {
+            this.record({
+                path: key,
+                origin: 'model',
+                outcome: 'absent',
+                chars: 0,
+                note: 'no such directory, or it is empty',
+            });
+            return { outcome: 'absent', body: '', note: 'no such directory, or it is empty', key: null };
+        }
+        return this.charge(key, renderListing(result.entries, this.limits.maxFileChars));
+    }
+    async exploreRead(reader, path, key) {
+        const result = await reader.read(path);
+        if ('failed' in result)
+            return this.fail(key, result.failed);
+        if (result.content === null) {
+            this.record({ path: key, origin: 'model', outcome: 'absent', chars: 0, note: 'no such file' });
+            return { outcome: 'absent', body: '', note: 'no such file in this repository', key: null };
+        }
+        return this.charge(key, clip(this.scrub(result.content), this.limits.maxFileChars));
+    }
+    /** Spend a model read's characters, or refuse it because the content budget is gone. */
+    charge(key, body) {
+        const remaining = this.limits.maxExplorationChars - this.explorationChars;
+        if (body.length > remaining) {
+            this.exhausted = 'chars';
+            const note = `the exploration content budget is spent (${this.limits.maxExplorationChars} characters). ` +
+                `Answer from what you have already seen, and say in the rationale which areas you could ` +
+                `not check`;
+            this.record({ path: key, origin: 'model', outcome: 'refused', chars: 0, note });
+            return { outcome: 'refused', body: '', note, key: null };
+        }
+        this.explorationChars += body.length;
+        this.bodies[key] = body;
+        this.record({ path: key, origin: 'model', outcome: 'read', chars: body.length, note: null });
+        return { outcome: 'read', body, note: null, key };
+    }
+    /** A provider failure on a model read: recorded, and stated to the model as UNKNOWN. */
+    fail(key, cause) {
+        this.log?.warn('monorepo survey: model-requested read failed', { key, err: cause });
+        this.record({ path: key, origin: 'model', outcome: 'unreadable', chars: 0, note: cause });
+        return {
+            outcome: 'unreadable',
+            body: '',
+            note: `that read failed (${cause}); treat what it would have said as UNKNOWN, not as absent`,
+            key: null,
+        };
+    }
+    /** A read the platform declines: recorded on the transcript, and the reason given to the model. */
+    refuse(request, note) {
+        this.record({
+            path: keyFor(request.side, request.kind, request.path.slice(0, 200) || '.'),
+            origin: 'model',
+            outcome: 'refused',
+            chars: 0,
+            note,
+        });
+        return { outcome: 'refused', body: '', note, key: null };
+    }
+    /** Whether a path is the new service's own directory or something under it. */
+    isInsideTarget(path) {
+        const target = this.request.directory.replace(/\/+$/, '');
+        return target !== '' && (path === target || path.startsWith(`${target}/`));
+    }
+    /**
+     * Scrub at READ time, so every body is scrubbed once and nothing can reach a model through a
+     * path that forgot to. A prompt built from an unscrubbed body is strictly more exposed than the
+     * transcript, and the exploration half has no compose step a caller could scrub at.
+     */
+    scrub(body) {
+        return redactSecrets(body) ?? '';
+    }
+    /**
+     * Append to the transcript, up to the cap.
+     *
+     * Past {@link MAX_ADOPTION_READS} the entry is COUNTED and not recorded: one model turn can emit
+     * any number of tool calls, so the array needs a bound the call budget does not give it, and
+     * that count is what states the truncation to the reviewer. The gap between `calls` and the
+     * array's length cannot: the seed adds rows without adding calls, and a call answered from what
+     * was already read adds a call without a row.
+     */
+    record(read) {
+        if (this.reads.length >= MAX_ADOPTION_READS) {
+            this.recordsDropped += 1;
+            return;
+        }
+        this.reads.push(read);
     }
-    return null;
 }
 /**
- * Survey both sides of a monorepo bootstrap: the house conventions the new service is landing
- * among, and what the reference template ships for the same areas.
+ * Open a survey of both sides of a monorepo bootstrap and read its opening context.
  *
- * Three reads make up the monorepo half, and the third is the one that matters most: the root
- * config says what the repository declares, the CI workflows say what it enforces, and the
- * nearest EXISTING SIBLING service says what a service in this repository actually looks like,
- * which is the thing a new service has to match and the thing no root file states. When nothing
- * beside the target qualifies as a sibling service, that is reported (`siblingService: null`)
- * rather than filled with the first directory found, which is a claim the survey cannot support.
- *
- * Each side also contributes its own SHAPE (`noteLayout`), because the shape is the only evidence
- * either side offers about source layout and module structure. Both are read off listings the
- * survey already needed, so neither costs a request.
+ * Two reads make up the monorepo half and the second is the one that matters most: the root
+ * config says what the repository declares, and the sibling services beside the target say what a
+ * service in this repository actually looks like, which is the thing a new service has to match
+ * and the thing no root file states. Everything past that is the model's to ask for.
  */
 export async function surveyMonorepo(request) {
-    const { directory, logger } = request;
-    const mono = new SideReader(request.monorepo, 'monorepo', logger);
-    const template = request.template
-        ? new SideReader(request.template, 'template', logger)
-        : undefined;
-    // ---- the monorepo's root conventions -------------------------------------
-    const rootEntries = await mono.list('');
-    if (rootEntries)
-        await mono.takeConventionFiles('', rootEntries, MAX_ROOT_FILES);
-    // ---- what it enforces in CI ---------------------------------------------
-    for (const ciPath of CI_DIRECTORIES) {
-        if (ciPath.endsWith('.yml')) {
-            await mono.take(ciPath);
-            continue;
-        }
-        const entries = await mono.list(ciPath);
-        if (!entries)
-            continue;
-        const workflows = entries
-            .filter((entry) => entry.type === 'file')
-            .slice(0, MAX_CI_FILES)
-            .map((entry) => entry.path);
-        await Promise.all(workflows.map((path) => mono.take(path)));
-    }
-    // ---- the nearest existing sibling service (the worked example) -----------
-    const parent = parentDirectoryOf(directory);
-    // Re-uses the root listing for a root-level target rather than asking for it twice.
-    const siblingEntries = parent === '' ? rootEntries : await mono.list(parent);
-    const sibling = await pickSiblingService(mono, siblingEntries, directory);
-    // ---- the reference template ---------------------------------------------
-    // Its SHAPE is recorded beside its files for the same reason the sibling's is: a layout
-    // recommendation needs evidence on both sides, or the one side that has any wins by default.
-    if (template) {
-        const entries = await template.list('');
-        if (entries) {
-            template.noteLayout('', entries);
-            await template.takeConventionFiles('', entries, MAX_ROOT_FILES);
-        }
-    }
-    const survey = {
-        monorepoPaths: mono.read,
-        templatePaths: template?.read ?? [],
-        unreadablePaths: [
-            ...mono.unreadable.map((path) => `monorepo:${path}`),
-            ...(template?.unreadable ?? []).map((path) => `template:${path}`),
-        ],
-        siblingService: sibling,
-    };
-    return { survey, files: { ...mono.contents, ...template?.contents } };
+    const session = new MonorepoSurveySession(request);
+    await session.seed();
+    return session;
 }
 //# sourceMappingURL=monorepoSurvey.js.map