@cat-factory/server 0.311.3 → 0.314.0

package/dist/agents/ContainerRepoBootstrapper.js

@@ -1,5 +1,8 @@
-import { failureKindFromHarnessCause } from '@cat-factory/kernel';
+import { failureKindFromHarnessCause, runBestEffort } from '@cat-factory/kernel';
 import { isProxyableProvider } from '@cat-factory/agents';
+import { bootstrapStepIds, REPO_BOOTSTRAP_AGENT_KIND } from '@cat-factory/contracts';
+import { recordBootstrapContextSnapshot } from './agentContextRecord.js';
+import { drainToolCalls } from './toolTrajectory.js';
 import { RunnerJobClient } from './RunnerJobClient.js';
 import { logger } from '../observability/logger.js';
 /** The role prompt when adapting a cloned reference architecture. */
@@ -10,31 +13,89 @@ const ADAPT_SYSTEM_PROMPT = 'You are a repository bootstrapper. You have a fresh
     'focused, idiomatic changes that match the existing structure. Do not invent ' +
     'unrelated features.';
 /**
- * The role prompt when writing a new service INTO an existing monorepo.
+ * The role prompt when writing a new service INTO an existing monorepo, told where its work
+ * lands.
  *
- * Distinct from the two below in the thing it keeps saying: the checkout is not the new
- * service's to reshape. The agent has the monorepo (writable, at a work branch) and the
- * reference template beside it as a read-only sibling, and its whole job is confined to one
- * new subdirectory plus the minimum registration the monorepo's own tooling needs. Every
- * cross-cutting choice it might otherwise make has already been made by a human and is stated
- * in the brief, so the prompt's job is to stop it re-deciding them.
+ * Distinct from the ones below in the thing it keeps saying: the checkout is not the new
+ * service's to reshape. The agent has the monorepo (writable) and the reference template beside
+ * it as a read-only sibling, and its whole job is confined to one new subdirectory plus the
+ * minimum registration the monorepo's own tooling needs. Every cross-cutting choice it might
+ * otherwise make has already been made by a human and is stated in the brief, so the prompt's
+ * job is to stop it re-deciding them.
+ *
+ * Two of its sentences are delivery-specific, and both are the kind that changes what the agent
+ * does. WHICH BRANCH it is on is the licence to commit loosely or not: under `direct_push` the
+ * harness checkpoints every commit straight to the branch every other service is built from, and
+ * an agent told it is on a "fresh work branch" is being told the opposite of that. And WHERE a
+ * deviation goes has to be somewhere that exists: routing it to a pull request description on a
+ * run that opens no pull request is how a caveat about a settled decision is silently lost.
+ */
+function monorepoSystemPrompt(delivery) {
+    const checkout = delivery === 'pull_request'
+        ? 'Your working directory is the monorepo checkout, already on a fresh work branch. '
+        : "Your working directory is the monorepo checkout, on the monorepo's OWN DEFAULT BRANCH: " +
+            'every commit you make is pushed to the branch every other service in it is built from, ' +
+            'as you make it. So commit only work you would be willing to merge, keep the tree ' +
+            'building at every commit, and never rewrite, revert or force-push history that was ' +
+            'there before you. ';
+    const deviation = delivery === 'pull_request'
+        ? 'say so in the pull request description'
+        : 'say so in the commit message that makes the change';
+    return ('You are adding a NEW service to an existing monorepo. ' +
+        checkout +
+        'A reference template repository is ' +
+        'checked out READ-ONLY as a sibling directory beside it: read from it freely, copy from it ' +
+        'where the brief says to, and never write to it. ' +
+        'Create the new service in the subdirectory the brief names, and touch NOTHING else in the ' +
+        'monorepo except the minimum registration its own tooling requires (a workspace list, a ' +
+        'build-graph entry, a CI matrix entry). Modifying an existing service is out of scope, and ' +
+        'so is reformatting, upgrading or "tidying" anything you did not add. ' +
+        'The brief carries adoption decisions a human has already reviewed and settled: for each ' +
+        'area they say whether the new service follows the monorepo or the template. Follow them ' +
+        'exactly. Do not substitute your own preference for one of them, and if a decision cannot ' +
+        `be honoured as written, do the closest thing that respects it and ${deviation} rather than ` +
+        'quietly taking the other side. ' +
+        'Match the surrounding monorepo in everything the brief does NOT settle: its naming, its ' +
+        'file layout, its dependency versions, its lint and test conventions. Leave the new service ' +
+        'building and its tests passing.');
+}
+/**
+ * The role prompt when filling a NEW repository from a reference template, delivered as a pull
+ * request.
+ *
+ * Distinct from {@link ADAPT_SYSTEM_PROMPT} in what the checkout IS: there the agent works in a
+ * clone OF the template and reshapes it, here it works in the new repository (which holds only
+ * its initial README) with the template read-only beside it. Saying "adapt this in place" to an
+ * agent whose cwd is the empty repository is how a run ends with the template untouched and the
+ * repository still empty.
+ */
+const PR_ADAPT_SYSTEM_PROMPT = 'You are a repository bootstrapper. Your working directory is a BRAND-NEW repository, ' +
+    'holding nothing but the initial README/.gitignore/license it was created with, already on a ' +
+    'fresh work branch. A reference architecture (a base/golden-template repository) is checked ' +
+    'out READ-ONLY as a sibling directory beside it: read from it freely, copy what the new ' +
+    'service needs into your working directory, and never write to it. ' +
+    'Adapt what you copy into the new service per the instructions: rename packages/modules, ' +
+    'leave out pieces that do not apply, write the README and metadata for THIS service, and ' +
+    'leave the project building. Make focused, idiomatic changes that match the structure the ' +
+    'template establishes. Do not invent unrelated features. ' +
+    'Your work is delivered as a pull request a person reviews, so it must stand on its own: no ' +
+    'placeholder files you meant to fill in later, and no references to paths that only exist in ' +
+    'the template.';
+/**
+ * The role prompt when scaffolding a new repository from scratch, delivered as a pull request.
+ *
+ * Same job as {@link SCAFFOLD_SYSTEM_PROMPT}, said to an agent that is NOT in an empty
+ * directory: the repository already carries its initial commit, which is what the pull request
+ * is opened against.
  */
-const MONOREPO_SYSTEM_PROMPT = 'You are adding a NEW service to an existing monorepo. Your working directory is the ' +
-    'monorepo checkout, already on a fresh work branch. A reference template repository is ' +
-    'checked out READ-ONLY as a sibling directory beside it: read from it freely, copy from it ' +
-    'where the brief says to, and never write to it. ' +
-    'Create the new service in the subdirectory the brief names, and touch NOTHING else in the ' +
-    'monorepo except the minimum registration its own tooling requires (a workspace list, a ' +
-    'build-graph entry, a CI matrix entry). Modifying an existing service is out of scope, and ' +
-    'so is reformatting, upgrading or "tidying" anything you did not add. ' +
-    'The brief carries adoption decisions a human has already reviewed and settled: for each ' +
-    'area they say whether the new service follows the monorepo or the template. Follow them ' +
-    'exactly. Do not substitute your own preference for one of them, and if a decision cannot be ' +
-    'honoured as written, do the closest thing that respects it and say so in the pull request ' +
-    'description rather than quietly taking the other side. ' +
-    'Match the surrounding monorepo in everything the brief does NOT settle: its naming, its ' +
-    'file layout, its dependency versions, its lint and test conventions. Leave the new service ' +
-    'building and its tests passing.';
+const PR_SCAFFOLD_SYSTEM_PROMPT = 'You are a repository bootstrapper. Your working directory is a BRAND-NEW repository, ' +
+    'holding nothing but the initial README/.gitignore/license it was created with, already on a ' +
+    'fresh work branch. Scaffold the service described in the instructions into it: create a ' +
+    'sensible, idiomatic project layout with source files, a README, and the metadata and ' +
+    'build/config files appropriate for the stack, leaving the project building. Keep the scope ' +
+    'to what the instructions describe; do not invent unrelated features. ' +
+    'Your work is delivered as a pull request a person reviews, so it must stand on its own: no ' +
+    'placeholder files you meant to fill in later.';
 /** The role prompt when scaffolding a brand-new repository from scratch. */
 const SCAFFOLD_SYSTEM_PROMPT = 'You are a repository bootstrapper. You are working in an empty directory and ' +
     'must scaffold a brand-new repository from scratch per the instructions. Create ' +
@@ -100,6 +161,12 @@ export class ContainerRepoBootstrapper {
      * Pre-flight the target repo and dispatch the bootstrap container as a
      * background job (returns once accepted, like `/run`). Throws on a pre-flight
      * failure so the run fails fast before a board frame is created.
+     *
+     * THREE dispatch shapes, chosen by the target and the run's delivery. A new repository
+     * delivered by `direct_push` is the original one (adapt a clone, reinitialise, force-push);
+     * everything else is the ordinary coding shape (clone the writable target, template beside it
+     * read-only, work branch, pull request), because the target already holds a history nobody may
+     * reset: the monorepo's, or the initial commit a pull request has to be opened against.
      */
     async startBootstrap(request) {
         const log = logger.child({ jobId: request.jobId, workspaceId: request.workspaceId });
@@ -112,90 +179,37 @@ export class ContainerRepoBootstrapper {
                 `(Workers AI, or a direct OpenAI-compatible provider); ` +
                 `'${this.deps.model.provider}' is not supported.`);
         }
-        // A monorepo run has a completely different pre-flight and a completely different push, so
-        // it branches before the new-repo checks below: there is no repository to create, nothing to
-        // be empty, and force-pushing a fresh history would destroy the target.
+        // A monorepo run has a completely different pre-flight, so it branches before the new-repo
+        // checks below: there is no repository to create and nothing to be empty.
         if (request.monorepo) {
             return await this.startMonorepoBootstrap(request, request.monorepo, installation);
         }
-        // The target repo is created up front — by the user via GitHub's new-repo page,
-        // or, for privileged-tier orgs (ADR 0005), programmatically via the create-repo
-        // endpoint behind the modal's "Create repository" button. Resolve it under the
-        // installation account to confirm it exists, is reachable by the App, and is
-        // empty — the run pushes the bootstrapped contents as the initial commit.
+        const target = await this.preflightNewRepoTarget(request, installation, log);
+        if (request.delivery.mode === 'pull_request') {
+            return await this.startNewRepoPullRequest(request, target, installation, log);
+        }
         const owner = installation.accountLogin;
         const repoName = request.target.name;
-        const ref = { owner, repo: repoName };
-        log.info('bootstrap: pre-flighting target repo', { target: `${owner}/${repoName}` });
-        let target;
-        try {
-            target = await this.deps.githubClient.getRepo(installation.installationId, ref);
-        }
-        catch {
-            throw new Error(`Repository ${owner}/${repoName} was not found or is not accessible to the GitHub App. ` +
-                `Create a repository named "${repoName}" under ${owner} (an initial README, .gitignore ` +
-                `or license is fine), make sure the App is installed on it, then run bootstrap again.`);
-        }
-        // The repo being *readable* is not enough: bootstrapping ends in a force-push, so
-        // the installation must have write access. A public repo the App can read but is
-        // not granted (not in the App's selected-repos list, or the App lacks
-        // contents:write) reads fine above but 403s on the container's push — pre-flight
-        // it here so that case fails fast with an actionable message instead of failing
-        // deep inside the run after a board frame has been created.
-        if (!(await this.deps.githubClient.canPush(installation.installationId, ref))) {
-            throw new Error(`The GitHub App can see ${owner}/${repoName} but does not have write access to it, so the ` +
-                `bootstrapped commit cannot be pushed. Grant the App write access to this repository ` +
-                `(GitHub → Settings → Applications → the cat-factory App → Configure → Repository access — ` +
-                `add "${repoName}" or allow all repositories), or, in local mode, use a GitHub PAT that ` +
-                `can push to it. Then run bootstrap again.`);
-        }
-        // The run replaces the repo's contents with a fresh single-commit history, so
-        // the target must be empty — except that GitHub's create-repo page often
-        // prepopulates a README, .gitignore and/or license. Those are throwaway
-        // boilerplate, so tolerate a repo that holds *only* them (the push force-
-        // overwrites them); reject anything with real content to avoid clobbering work.
-        const rootEntries = await this.deps.githubClient.listRootEntries(installation.installationId, ref);
-        const realContent = rootEntries.filter((entry) => !isBootstrapBoilerplate(entry));
-        if (realContent.length > 0) {
-            const sample = realContent
-                .map((entry) => entry.path)
-                .slice(0, 5)
-                .join(', ');
-            throw new Error(`Repository ${owner}/${repoName} already has content (${sample}). Bootstrapping replaces ` +
-                `the repository's contents, so it needs an empty repository — or one prepopulated only ` +
-                `with a README, .gitignore, license and/or AGENTS.md.`);
-        }
-        // Scoped to the one repo being bootstrapped: the run clones and force-pushes exactly this
-        // target and touches nothing else, so there is no leg to widen for. `target` came from the
-        // pre-flight `getRepo` above, which is why this costs no extra read.
+        // With a reference architecture the container clones + adapts it; without one
+        // it scaffolds an empty repo from the freeform instructions alone.
+        const reference = await this.resolveReferenceTemplate(request, installation.installationId, log);
+        // Scoped to the repos this run touches: the target it force-pushes, and the template it
+        // CLONES. The template belongs on the scope even though nothing pushes to it, because the
+        // clone runs on this same token: leaving it off works only for a public reference
+        // architecture and 404s on a private one, with nothing in the failure naming the cause.
+        // `target` came from the pre-flight `getRepo` above, which is why it costs no extra read.
         const ghToken = await this.deps.mintInstallationToken(installation.installationId, {
-            executionId: request.containerJobId,
+            executionId: request.jobId,
             workspaceId: request.workspaceId,
-            repoIds: [String(target.githubId)],
+            repoIds: [String(target.githubId), ...(reference?.githubId ? [reference.githubId] : [])],
         });
         // Private-registry auth for the scaffolder's installs, exactly as the
         // implementation executor forwards it.
         const packageRegistries = (await this.deps.resolvePackageRegistries?.(request.workspaceId)) ?? [];
-        const sessionToken = await this.deps.sessionService.mint({
-            workspaceId: request.workspaceId,
-            executionId: request.containerJobId,
-            agentKind: 'architect',
-            provider: this.deps.model.provider,
-            model: this.deps.model.model,
-        });
-        const webBase = (this.deps.webBaseUrl ?? 'https://github.com').replace(/\/+$/, '');
+        const sessionToken = await this.mintSessionToken(request);
+        const webBase = this.webBase();
         const targetCloneUrl = `${webBase}/${owner}/${repoName}.git`;
-        const defaultBranch = target.defaultBranch ?? 'main';
-        // With a reference architecture the container clones + adapts it; without one
-        // it scaffolds an empty repo from the freeform instructions alone.
-        const reference = request.referenceRepo
-            ? {
-                owner: request.referenceRepo.owner,
-                name: request.referenceRepo.name,
-                cloneUrl: `${webBase}/${request.referenceRepo.owner}/${request.referenceRepo.name}.git`,
-                baseBranch: 'main',
-            }
-            : undefined;
+        const defaultBranch = defaultBranchOf(target);
         const targetSpec = { owner, name: repoName, cloneUrl: targetCloneUrl, defaultBranch };
         // The generic agent `repo` is the clone source: the reference when adapting one, or the
         // (uncloned) target placeholder when scaffolding from scratch. The real push destination
@@ -209,18 +223,18 @@ export class ContainerRepoBootstrapper {
             }
             : { owner, name: repoName, baseBranch: defaultBranch, cloneUrl: targetCloneUrl };
         // Bootstrap dispatches the generic, manifest-driven `agent` kind in `coding` mode with a
-        // `bootstrap` spec (the divergent force-push to a separate target repo) — the SAME path
+        // `bootstrap` spec (the divergent force-push to a separate target repo): the SAME path
         // every other built-in coding agent takes, with NO bespoke `/bootstrap` harness handler.
         const body = {
             jobId: request.containerJobId,
             // The run's correlation ids, so the container's own lines join to this bootstrap in the
-            // backend's logs — the same fields `buildCommonBody` puts on an execution job. A bootstrap
-            // is a first-class agent run (one `agent_runs` table, one retry surface), so it must not be
-            // the one agent-kind dispatch whose container logs cannot be joined to anything. Its run id
-            // IS its job id: a bootstrap has no separate execution row, which is exactly what
-            // `sessionService.mint` above is told.
+            // backend's logs: the same fields `buildCommonBody` puts on an execution job. A bootstrap
+            // is a first-class agent run (one `agent_runs` table, one retry surface, one observability
+            // panel), so it must not be the one agent-kind dispatch whose container logs cannot be
+            // joined to anything. The id is the RUN's, matching the session token above: a bootstrap
+            // has no separate execution row, so its run id is what every run-scoped read is keyed by.
             workspaceId: request.workspaceId,
-            executionId: request.containerJobId,
+            executionId: request.jobId,
             mode: 'coding',
             systemPrompt: reference ? ADAPT_SYSTEM_PROMPT : SCAFFOLD_SYSTEM_PROMPT,
             userPrompt: request.instructions ||
@@ -232,7 +246,7 @@ export class ContainerRepoBootstrapper {
             // select a subscription harness. The job schema tolerates `harness` (shared
             // HarnessAuthFields), but bootstrap is the one container flow that always uses
             // the deployment's proxyable model rather than a workspace's pooled subscription
-            // token — there is no per-block model selection on a not-yet-existing repo.
+            // token: there is no per-block model selection on a not-yet-existing repo.
             proxyBaseUrl: this.deps.proxyBaseUrl,
             // This backend serves the phase-tagged completions route (see `ContainerAgentExecutor`),
             // so a bootstrap's calls are attributed rather than landing in the unattributed slice.
@@ -242,9 +256,9 @@ export class ContainerRepoBootstrapper {
             ...(packageRegistries.length ? { packageRegistries } : {}),
             repo: repoSpec,
             branch: repoSpec.baseBranch,
-            // Bootstrap always resets history to a single commit and force-pushes (the fresh
-            // history shares no ancestor with the target repo's boilerplate); that is implicit
-            // in the bootstrap flow, so no per-job flags are needed.
+            // This delivery always resets history to a single commit and force-pushes (the fresh
+            // history shares no ancestor with the target repo's boilerplate); that is what the
+            // `bootstrap` spec MEANS to the harness, so no per-job flags are needed.
             bootstrap: {
                 target: targetSpec,
                 ...(reference ? {} : { fromScratch: true }),
@@ -254,7 +268,7 @@ export class ContainerRepoBootstrapper {
         // Dispatch through the shared transport (keyed by job id), exactly like the
         // implementation executor: it hits the harness `POST /jobs` (kind `agent`), starts the
         // background job and returns once accepted; we then poll via the same transport.
-        // Idempotent per job id — a replayed dispatch re-attaches rather than duplicating.
+        // Idempotent per job id: a replayed dispatch re-attaches rather than duplicating.
         log.info('bootstrap: dispatching container', {
             reference: reference ? `${reference.owner}/${reference.name}` : null,
         });
@@ -262,29 +276,129 @@ export class ContainerRepoBootstrapper {
         // equals the run id (no per-step fan-out into a shared container, and no second phase).
         await this.jobs.dispatch(request.workspaceId, { runId: request.jobId, jobId: request.containerJobId }, body, 'agent');
         log.info('bootstrap: container accepted job');
+        await this.recordDispatchContext(request, body, log);
         return {
             workspaceId: request.workspaceId,
             jobId: request.jobId,
             containerJobId: request.containerJobId,
         };
     }
+    /**
+     * Pre-flight the pre-created target repository of a NEW-REPO run: it exists, the App can
+     * write to it, and it holds no real content.
+     *
+     * The target repo is created up front: by the user via the host's new-repo page, or, for
+     * privileged-tier orgs (ADR 0005), programmatically via the create-repo endpoint behind the
+     * modal's "Create repository" button.
+     *
+     * The emptiness rule binds under both deliveries, because both WRITE a whole service into the
+     * repository: a force-push would clobber real content and a pull request would propose
+     * deleting it. What differs is the FLOOR: a pull request needs an initial commit to branch
+     * from, so that delivery also refuses a repository with none.
+     */
+    async preflightNewRepoTarget(request, installation, log) {
+        const owner = installation.accountLogin;
+        const repoName = request.target.name;
+        const ref = { owner, repo: repoName };
+        log.info('bootstrap: pre-flighting target repo', { target: `${owner}/${repoName}` });
+        let target;
+        try {
+            target = await this.deps.githubClient.getRepo(installation.installationId, ref);
+        }
+        catch {
+            throw new Error(`Repository ${owner}/${repoName} was not found or is not accessible to the GitHub App. ` +
+                `Create a repository named "${repoName}" under ${owner} (an initial README, .gitignore ` +
+                `or license is fine), make sure the App is installed on it, then run bootstrap again.`);
+        }
+        // The repo being *readable* is not enough: bootstrapping ends in a push, so the
+        // installation must have write access. A public repo the App can read but is
+        // not granted (not in the App's selected-repos list, or the App lacks
+        // contents:write) reads fine above but 403s on the container's push, so pre-flight
+        // it here: that case then fails fast with an actionable message instead of failing
+        // deep inside the run after a board frame has been created.
+        if (!(await this.deps.githubClient.canPush(installation.installationId, ref))) {
+            throw new Error(`The GitHub App can see ${owner}/${repoName} but does not have write access to it, so the ` +
+                `bootstrapped commit cannot be pushed. Grant the App write access to this repository ` +
+                `(GitHub → Settings → Applications → the cat-factory App → Configure → Repository access: ` +
+                `add "${repoName}" or allow all repositories), or, in local mode, use a GitHub PAT that ` +
+                `can push to it. Then run bootstrap again.`);
+        }
+        // The run writes a whole repository's worth of content, so the target must be
+        // empty, except that GitHub's create-repo page often prepopulates a README,
+        // .gitignore and/or license. Those are throwaway boilerplate, so tolerate a repo
+        // that holds *only* them; reject anything with real content to avoid clobbering work.
+        const rootEntries = await this.deps.githubClient.listRootEntries(installation.installationId, ref);
+        const realContent = rootEntries.filter((entry) => !isBootstrapBoilerplate(entry));
+        if (realContent.length > 0) {
+            const sample = realContent
+                .map((entry) => entry.path)
+                .slice(0, 5)
+                .join(', ');
+            throw new Error(`Repository ${owner}/${repoName} already has content (${sample}). Bootstrapping replaces ` +
+                `the repository's contents, so it needs an empty repository, or one prepopulated only ` +
+                `with a README, .gitignore, license and/or AGENTS.md.`);
+        }
+        // A pull request is opened BETWEEN two commits, so a repository holding none cannot take
+        // one: there is no default branch to clone, to branch from, or to target.
+        // `listRootEntries` answers `[]` for exactly that repository (the contents endpoint 404s
+        // where there is no commit), so an empty listing is the tell. Refused here, naming both
+        // ways out, rather than surfacing later as a clone failure that reads like an outage.
+        if (request.delivery.mode === 'pull_request' && rootEntries.length === 0) {
+            throw new Error(`Repository ${owner}/${repoName} has no commits yet, so there is no branch to open a ` +
+                `pull request against. Either create it with an initial commit (a README is enough), ` +
+                `or bootstrap it with "push directly", which writes the repository's first commit.`);
+        }
+        return target;
+    }
+    /**
+     * Dispatch a NEW-REPO run delivered as a pull request: the ordinary coding shape against the
+     * (already-initialised) target repository, with the reference template beside it as a
+     * READ-ONLY sibling checkout.
+     *
+     * Deliberately NOT the `bootstrap` spec, which is the whole reason this path exists
+     * separately: that spec reinitialises history and force-pushes, and a branch whose history
+     * shares no ancestor with the default branch is not something a pull request can be opened
+     * from. Here the target's own initial commit is the base, so the diff a reviewer reads is the
+     * service being added.
+     */
+    async startNewRepoPullRequest(request, target, installation, log) {
+        const owner = installation.accountLogin;
+        const repoName = request.target.name;
+        log.info('bootstrap(new-repo pr): dispatching container', { target: `${owner}/${repoName}` });
+        return await this.dispatchCodingShape(request, installation, log, {
+            repo: {
+                owner,
+                name: repoName,
+                baseBranch: defaultBranchOf(target),
+                cloneUrl: `${this.webBase()}/${owner}/${repoName}.git`,
+            },
+            repoGithubId: target.githubId,
+            systemPrompt: request.referenceRepo ? PR_ADAPT_SYSTEM_PROMPT : PR_SCAFFOLD_SYSTEM_PROMPT,
+            userPrompt: request.instructions ||
+                (request.referenceRepo
+                    ? 'Adapt the reference architecture for the new service.'
+                    : 'Scaffold a new repository for the service.'),
+        });
+    }
     /**
      * Dispatch a monorepo bootstrap's APPLY phase: an ordinary coding job on the monorepo, with
      * the reference template alongside it as a READ-ONLY sibling checkout.
      *
      * Deliberately the plain coding shape rather than a `bootstrap` spec, and that is the design:
-     * the harness already knows how to clone a writable primary at a work branch, clone
-     * `referenceRepos` beside it without ever branching or pushing them, and open one pull request
-     * for the primary. A bespoke bootstrap mode here would be a second implementation of that with
-     * one extra way to get the push wrong, against a repository that holds other people's code.
+     * the harness already knows how to clone a writable primary (at a work branch, or at the
+     * default branch it commits onto, per the run's delivery), clone `referenceRepos` beside it
+     * without ever branching or pushing them, and open one pull request for the primary when it
+     * was given one to open. A bespoke bootstrap mode here would be a second implementation of
+     * that with one extra way to get the push wrong, against a repository that holds other
+     * people's code.
      *
      * `repo.serviceDirectory` is what scopes the agent to the new subdirectory: the same field
      * every monorepo-service run rides, so the working-directory rule is stated in one place.
      *
      * Two pre-flights, both about the monorepo rather than about a new repo: the App must be able
      * to WRITE to it (a read-only grant reads fine and 403s on the push, after a board frame
-     * exists), and the target directory must still be absent at dispatch time, because the orchestration
-     * pre-flighted it before the survey, and a review can be settled days later.
+     * exists), and the target directory must still be absent at dispatch time, because the
+     * orchestration pre-flighted it before the survey and a review can be settled days later.
      */
     async startMonorepoBootstrap(request, monorepo, installation) {
         const log = logger.child({ jobId: request.jobId, workspaceId: request.workspaceId });
@@ -300,93 +414,171 @@ export class ContainerRepoBootstrapper {
                 `to it, so the new service cannot be pushed. Grant the App write access to this ` +
                 `repository, then retry.`);
         }
-        const existing = await this.deps.githubClient.listDirectory(installation.installationId, ref, monorepo.directory, defaultBranchOf(target));
+        const existing = await this.deps.githubClient.listDirectory(installation.installationId, ref, monorepo.directory, defaultBranch);
         if (existing.length > 0) {
             throw new Error(`\`${monorepo.directory}\` already exists in ${monorepo.owner}/${monorepo.name}. It was ` +
                 `empty when this bootstrap started; something has since created it. Pick a different ` +
                 `directory and start a new bootstrap rather than writing over it.`);
         }
-        const webBase = (this.deps.webBaseUrl ?? 'https://github.com').replace(/\/+$/, '');
-        // Scoped to the repos this run touches: the monorepo it pushes to, and the template it
-        // reads. A template outside the installation simply is not cloneable, which the harness
-        // reports as a clone failure rather than silently running without it.
-        const repoIds = [String(target.githubId)];
-        const reference = request.referenceRepo;
-        let referenceRepos = [];
-        if (reference) {
-            const templateRepo = await this.deps.githubClient
-                .getRepo(installation.installationId, { owner: reference.owner, repo: reference.name })
-                .catch(() => null);
-            if (templateRepo)
-                repoIds.push(String(templateRepo.githubId));
-            referenceRepos = [
+        log.info('bootstrap(monorepo): dispatching container', {
+            directory: monorepo.directory,
+            delivery: request.delivery.mode,
+        });
+        return await this.dispatchCodingShape(request, installation, log, {
+            repo: {
+                owner: monorepo.owner,
+                name: monorepo.name,
+                baseBranch: defaultBranch,
+                cloneUrl: `${this.webBase()}/${monorepo.owner}/${monorepo.name}.git`,
+                serviceDirectory: monorepo.directory,
+            },
+            repoGithubId: target.githubId,
+            systemPrompt: monorepoSystemPrompt(request.delivery.mode),
+            userPrompt: request.instructions,
+        });
+    }
+    /**
+     * The dispatch both non-force-push shapes share: clone the writable target, fetch the
+     * reference template beside it read-only, and either open a work branch plus a pull request
+     * or commit onto the target's own default branch.
+     *
+     * ONE builder rather than one per target, because the delivery rule is the interesting part
+     * and a second copy of it is a second place for `newBranch` and `pr` to disagree: a body
+     * carrying a branch but no PR pushes work onto a branch nobody is told about.
+     */
+    async dispatchCodingShape(request, installation, log, spec) {
+        // Scoped to the repos this run touches: the one it pushes to, and the template it reads. A
+        // template outside the installation simply is not cloneable, which the harness reports as a
+        // clone failure rather than silently running without it.
+        const reference = await this.resolveReferenceTemplate(request, installation.installationId, log);
+        const repoIds = [
+            String(spec.repoGithubId),
+            ...(reference?.githubId ? [reference.githubId] : []),
+        ];
+        const referenceRepos = reference
+            ? [
                 {
                     repo: {
                         owner: reference.owner,
                         name: reference.name,
-                        baseBranch: templateRepo?.defaultBranch ?? 'main',
-                        cloneUrl: `${webBase}/${reference.owner}/${reference.name}.git`,
+                        baseBranch: reference.baseBranch,
+                        cloneUrl: reference.cloneUrl,
                     },
                 },
-            ];
-        }
+            ]
+            : [];
         const ghToken = await this.deps.mintInstallationToken(installation.installationId, {
-            executionId: request.containerJobId,
+            executionId: request.jobId,
             workspaceId: request.workspaceId,
             repoIds,
         });
         const packageRegistries = (await this.deps.resolvePackageRegistries?.(request.workspaceId)) ?? [];
-        const sessionToken = await this.deps.sessionService.mint({
-            workspaceId: request.workspaceId,
-            executionId: request.containerJobId,
-            agentKind: 'architect',
-            provider: this.deps.model.provider,
-            model: this.deps.model.model,
-        });
+        const sessionToken = await this.mintSessionToken(request);
+        // The delivery decides the two fields TOGETHER: with `newBranch` and `pr` the harness pushes
+        // a work branch and opens one pull request; with neither it commits onto `branch`, the
+        // target's own default. Omitting only one of the pair is the bug this single site prevents.
+        const delivery = request.delivery.mode === 'pull_request'
+            ? { newBranch: request.delivery.branch, pr: request.delivery.pr }
+            : {};
         const body = {
             jobId: request.containerJobId,
             workspaceId: request.workspaceId,
-            executionId: request.containerJobId,
+            // The RUN, not this phase's drive id: see the session mint above.
+            executionId: request.jobId,
             mode: 'coding',
-            systemPrompt: MONOREPO_SYSTEM_PROMPT,
-            userPrompt: request.instructions,
+            systemPrompt: spec.systemPrompt,
+            userPrompt: spec.userPrompt,
             model: this.deps.model.model,
             proxyBaseUrl: this.deps.proxyBaseUrl,
             proxyPhasePath: true,
             sessionToken,
             ghToken,
             ...(packageRegistries.length ? { packageRegistries } : {}),
-            repo: {
-                owner: monorepo.owner,
-                name: monorepo.name,
-                baseBranch: defaultBranch,
-                cloneUrl: `${webBase}/${monorepo.owner}/${monorepo.name}.git`,
-                serviceDirectory: monorepo.directory,
-            },
-            branch: defaultBranch,
-            newBranch: monorepo.branch,
-            pr: monorepo.pr,
+            repo: spec.repo,
+            branch: spec.repo.baseBranch,
+            ...delivery,
             ...(referenceRepos.length ? { referenceRepos } : {}),
             ...(this.deps.githubApiBase ? { githubApiBase: this.deps.githubApiBase } : {}),
         };
-        log.info('bootstrap(monorepo): dispatching container', {
-            branch: monorepo.branch,
+        await this.jobs.dispatch(request.workspaceId, { runId: request.jobId, jobId: request.containerJobId }, body, 'agent');
+        // The BRANCH is the field an operator needs first when a run reports done with no pull
+        // request (the orchestration then fails it as delivered nowhere) or faults mid-way under
+        // `direct_push`: it names where the commits are. Nothing else in the backend's logs does.
+        log.info('bootstrap: container accepted job', {
+            delivery: request.delivery.mode,
+            branch: request.delivery.mode === 'pull_request' ? request.delivery.branch : spec.repo.baseBranch,
             reference: reference ? `${reference.owner}/${reference.name}` : null,
         });
-        await this.jobs.dispatch(request.workspaceId, { runId: request.jobId, jobId: request.containerJobId }, body, 'agent');
-        log.info('bootstrap(monorepo): container accepted job');
+        await this.recordDispatchContext(request, body, log);
         return {
             workspaceId: request.workspaceId,
             jobId: request.jobId,
             containerJobId: request.containerJobId,
         };
     }
+    /**
+     * Resolve the reference template a run reads from: its clone spec, plus the numeric id the
+     * run's installation token has to be scoped to.
+     *
+     * ONE resolution for both dispatch shapes, because both CLONE the template and both mint the
+     * token that clone runs on. Two copies is what left the force-push path granting only its push
+     * target while cloning the template with that same token, so a PRIVATE reference architecture
+     * 404s on clone under one delivery and works under the other, and what left it assuming the
+     * template's base branch was `main`.
+     *
+     * A template the installation cannot read resolves to no id and the conventional branch rather
+     * than refusing the run: the clone then fails inside the harness naming the repository, which
+     * is a better report than a pre-flight throw here, and the warning says which read failed.
+     */
+    async resolveReferenceTemplate(request, installationId, log) {
+        const reference = request.referenceRepo;
+        if (!reference)
+            return undefined;
+        const template = await runBestEffort(log, 'bootstrap: read reference template repo', () => this.deps.githubClient.getRepo(installationId, {
+            owner: reference.owner,
+            repo: reference.name,
+        }), { reference: `${reference.owner}/${reference.name}` });
+        return {
+            owner: reference.owner,
+            name: reference.name,
+            cloneUrl: `${this.webBase()}/${reference.owner}/${reference.name}.git`,
+            baseBranch: template ? defaultBranchOf(template) : 'main',
+            githubId: template ? String(template.githubId) : null,
+        };
+    }
+    /**
+     * The model-locked LLM-proxy session token a bootstrap container runs under.
+     *
+     * Keyed on the RUN, never on the drive: a monorepo run's apply phase is dispatched under its
+     * own container job id, so minting on that id files the apply's model calls under a key no
+     * run-scoped read asks for, and the run reports only what its survey spent.
+     */
+    mintSessionToken(request) {
+        return this.deps.sessionService.mint({
+            workspaceId: request.workspaceId,
+            executionId: request.jobId,
+            agentKind: REPO_BOOTSTRAP_AGENT_KIND,
+            provider: this.deps.model.provider,
+            model: this.deps.model.model,
+        });
+    }
+    /** The host's web base, trailing slashes stripped, for building clone URLs. */
+    webBase() {
+        return (this.deps.webBaseUrl ?? 'https://github.com').replace(/\/+$/, '');
+    }
     /** Poll a dispatched bootstrap job, mapping the runner job view into an update. */
     async pollBootstrap(handle) {
         const view = await this.jobs.poll(handle.workspaceId, {
             runId: handle.jobId,
             jobId: handle.containerJobId,
         });
+        // The tool calls the harness drained on this poll, to the same two destinations an
+        // execution step's go to. Filed under the RUN (`runId`) and grouped by the container job,
+        // so a monorepo run's apply trajectory reads under the run a person opened. Isolated +
+        // best-effort inside `drainToolCalls`: it can never affect this poll's verdict.
+        // Correlated by the same two ids every other line about this run carries, so a drain that
+        // warns (an image too old to number its calls) names the run it was about.
+        await drainToolCalls(this.deps, this.jobHandle(handle), view.spans, logger.child({ jobId: handle.jobId, workspaceId: handle.workspaceId }));
         if (view.state === 'running') {
             return view.progress ? { state: 'running', subtasks: view.progress } : { state: 'running' };
         }
@@ -420,16 +612,62 @@ export class ContainerRepoBootstrapper {
                 detail: view.detail ?? result.error,
             };
         }
-        // A MONOREPO run's product is the pull request, and NOTHING else it could report stands in
-        // for it: there is no repository it created, so building a `repoUrl` here would name one
-        // that does not exist. A `prUrl` is the shape's own tell (the new-repo flow force-pushes a
-        // default branch and never opens one), so it is reported alone, and a completed apply that
-        // opened none reports neither, leaving the ORCHESTRATION to say what that means (it fails
-        // the run: the service was delivered nowhere).
-        if (result.prUrl)
-            return { state: 'done', prUrl: result.prUrl };
-        const outcome = await this.buildOutcome(handle, result.defaultBranch);
-        return { state: 'done', outcome };
+        // What a completed run can NAME is decided by its target, never by whether a `prUrl` came
+        // back. A monorepo run created no repository, so building a `repoUrl` here would name one
+        // that does not exist; a new-repo run created one under either delivery, and under
+        // `pull_request` it has BOTH a repository and a pull request to report. Reading the record
+        // is what tells them apart: `prUrl`'s presence cannot, now that a new-repo run may carry
+        // one. A run that promised a pull request and reports none is left to the ORCHESTRATION to
+        // fail, which is where "delivered nowhere" is a statement about the run rather than about
+        // this poll.
+        const record = await this.requireRecord(handle);
+        const pr = result.prUrl ? { prUrl: result.prUrl } : {};
+        if (record.monorepo)
+            return { state: 'done', ...pr };
+        const outcome = await this.buildOutcome(handle, record.repoName, result.defaultBranch);
+        return { state: 'done', outcome, ...pr };
+    }
+    /**
+     * The dispatched container job as an {@link AgentJobHandle}, the shape the shared trajectory
+     * drain speaks. `runId` is the bootstrap RUN and `jobId` the container job it dispatched,
+     * which is the same split every execution step's handle carries.
+     */
+    jobHandle(handle) {
+        return {
+            jobId: handle.containerJobId,
+            runId: handle.jobId,
+            workspaceId: handle.workspaceId,
+            agentKind: REPO_BOOTSTRAP_AGENT_KIND,
+            model: this.resolvedModel(),
+            provider: this.deps.model.provider,
+        };
+    }
+    /**
+     * The resolved model as every OTHER producer writes it: `provider:model`, which is the format
+     * `AgentJobHandle.model` and `agentContextSnapshotSchema.model` both document. A bare model id
+     * renders beside prefixed ones on the same panel and gives nothing to a reader that splits the
+     * field to recover the provider.
+     */
+    resolvedModel() {
+        return `${this.deps.model.provider}:${this.deps.model.model}`;
+    }
+    /**
+     * File what this dispatch handed the agent, so a bootstrap's Provided-context tab answers the
+     * same question every other agent run's does.
+     *
+     * AWAITED for the reason `recordAgentContextSnapshot` states: it runs after the container has
+     * already been accepted, so it delays nothing but the handle's return, and an un-awaited insert
+     * is dropped outright on the Worker, where this runs inside a Workflow step.
+     */
+    async recordDispatchContext(request, body, log) {
+        await recordBootstrapContextSnapshot(this.deps.agentContextObservability, log, {
+            body,
+            model: this.resolvedModel(),
+            agentKind: REPO_BOOTSTRAP_AGENT_KIND,
+            workspaceId: request.workspaceId,
+            executionId: request.jobId,
+            stepIndex: dispatchStepIndex(request),
+        });
     }
     /**
      * Best-effort: reclaim the per-run container for a job. Releases through the same
@@ -474,23 +712,56 @@ export class ContainerRepoBootstrapper {
         });
         return { installationId: installation.installationId, githubId: repo.githubId };
     }
-    /** Construct the success outcome from the installation + the recorded job's repo name. */
-    async buildOutcome(handle, resultDefaultBranch) {
+    /**
+     * Construct the success outcome from the installation + the recorded job's repo name.
+     *
+     * `resultDefaultBranch` is what the HARNESS reported, and only the `bootstrap` spec reports one
+     * (it echoes back the branch it force-pushed, which it also created). The plain coding shape a
+     * `pull_request` run takes reports none, so the branch is READ off the target repository rather
+     * than defaulted to `main`: this field states which branch the work lands on, and a repository
+     * whose default is `master`, `trunk` or an org-wide choice would otherwise be recorded as a ref
+     * that does not exist. One read, on the terminal poll only. A failed read keeps the
+     * conventional fallback and says so in a warning, rather than failing a delivered run over the
+     * one field nothing reads back.
+     */
+    async buildOutcome(handle, repoName, resultDefaultBranch) {
         const installation = await this.deps.installationRepository.getByWorkspace(handle.workspaceId);
         if (!installation)
             throw new Error(`Workspace '${handle.workspaceId}' is not connected to GitHub`);
-        const record = await this.deps.bootstrapJobRepository.get(handle.workspaceId, handle.jobId);
-        if (!record)
-            throw new Error(`Bootstrap job '${handle.jobId}' not found`);
         const owner = installation.accountLogin;
-        const webBase = (this.deps.webBaseUrl ?? 'https://github.com').replace(/\/+$/, '');
+        const log = logger.child({ jobId: handle.jobId, workspaceId: handle.workspaceId });
+        const target = resultDefaultBranch
+            ? null
+            : await runBestEffort(log, 'bootstrap: read the target repo default branch', () => this.deps.githubClient.getRepo(installation.installationId, {
+                owner,
+                repo: repoName,
+            }), { repo: `${owner}/${repoName}` });
         return {
-            repoUrl: `${webBase}/${owner}/${record.repoName}`,
+            repoUrl: `${this.webBase()}/${owner}/${repoName}`,
             owner,
-            name: record.repoName,
-            defaultBranch: resultDefaultBranch ?? 'main',
+            name: repoName,
+            defaultBranch: resultDefaultBranch ?? (target ? defaultBranchOf(target) : 'main'),
         };
     }
+    /** The run's stored row, which a poll addresses only by id. */
+    async requireRecord(handle) {
+        const record = await this.deps.bootstrapJobRepository.get(handle.workspaceId, handle.jobId);
+        if (!record)
+            throw new Error(`Bootstrap job '${handle.jobId}' not found`);
+        return record;
+    }
+}
+/**
+ * Which of the RUN's own steps this dispatch is, numbered exactly as the board numbers them.
+ *
+ * The container dispatch is always the run's LAST move: a new-repo run is only `scaffold`, and a
+ * monorepo run's apply follows the survey and the human review. So it is read off the end of the
+ * shared `bootstrapStepIds` list rather than by searching it for a step NAME, which cannot
+ * answer `-1`. A snapshot filed at a step the run never had is a row every step-scoped read
+ * silently drops.
+ */
+function dispatchStepIndex(request) {
+    return bootstrapStepIds({ monorepo: request.monorepo ?? null }).length - 1;
 }
 /** A repo's default branch, or the conventional fallback when the provider reported none. */
 function defaultBranchOf(repo) {