@cat-factory/server 0.313.0 → 0.314.1

package/dist/agents/ContainerRepoBootstrapper.d.ts

@@ -1,9 +1,10 @@
-import type { BootstrapJobHandle, BootstrapJobRepository, BootstrapJobUpdate, BootstrapRepoOutcome, BootstrapRepoRequest, GitHubClient, MonorepoTargetRepo, GitHubInstallationRepository, GitHubRepo, GroupCacheHandle, ModelRef, RepoBootstrapper, RepoProjectionRepository } from '@cat-factory/kernel';
+import type { AgentContextRecorder, BootstrapJobHandle, BootstrapJobRepository, BootstrapJobUpdate, BootstrapRepoOutcome, BootstrapRepoRequest, GitHubClient, MonorepoTargetRepo, ReferenceRepoAccess, GitHubInstallationRepository, GitHubRepo, GroupCacheHandle, ModelRef, RepoBootstrapper, RepoProjectionRepository, VcsProvider } from '@cat-factory/kernel';
 import type { ContainerSessionService } from '../containers/ContainerSessionService.js';
+import { type ToolTrajectoryDeps } from './toolTrajectory.js';
 import type { JobPackageRegistrySpec } from './ContainerAgentExecutor.js';
-import type { MintInstallationToken } from './repoTargeting.js';
+import { type MintInstallationToken } from './repoTargeting.js';
 import { type ResolveRunnerTransport } from './RunnerJobClient.js';
-export interface ContainerRepoBootstrapperDependencies {
+export interface ContainerRepoBootstrapperDependencies extends ToolTrajectoryDeps {
     /**
      * Resolve which runner backend (Cloudflare container or self-hosted pool) a
      * bootstrap job dispatches to — the same seam the implementation executor rides.
@@ -23,6 +24,18 @@ export interface ContainerRepoBootstrapperDependencies {
     repoProjectionCache?: GroupCacheHandle<GitHubRepo[]>;
     /** Resolves/validates the pre-created target repository (existence + emptiness). */
     githubClient: GitHubClient;
+    /**
+     * The provider {@link githubClient} speaks (`engineVcsProvider`), so a workspace whose
+     * connection is on ANOTHER one is refused rather than probed with the wrong client.
+     *
+     * Required rather than defaulted, for the reason `makeResolveRepoFilesForCoords` states it:
+     * a deployment serving a GitHub App beside per-workspace GitLab connections binds the App
+     * client here, and a GitLab workspace's installation id means nothing to it. Reading the
+     * template through it anyway answers 404, which this component would then report as "your
+     * reference architecture names the wrong repository" for an entry that is perfectly correct.
+     * A facade that forgets to state it must fail to typecheck rather than inherit a guess.
+     */
+    clientProvider: VcsProvider;
     /**
      * Mints a short-lived GitHub installation token for clone + push, scoped to the single repo
      * being bootstrapped. Bootstrap has no run initiator, so it names no `initiatedBy` and always
@@ -39,6 +52,12 @@ export interface ContainerRepoBootstrapperDependencies {
     githubApiBase?: string;
     /** Web base for building the created repo's URL (defaults to github.com). */
     webBaseUrl?: string;
+    /**
+     * Records the complete context each bootstrap dispatch handed its agent (best-effort, gated
+     * inside the recorder). Absent ⇒ a bootstrap's "Provided context" tab is empty, which is the
+     * shape every other agent run's would have if its executor skipped this call.
+     */
+    agentContextObservability?: AgentContextRecorder;
     /**
      * Resolve the workspace's private package-registry entries for the bootstrap
      * container (the scaffolder installs dependencies too). Same seam as
@@ -69,6 +88,43 @@ export declare class ContainerRepoBootstrapper implements RepoBootstrapper {
     constructor(deps: ContainerRepoBootstrapperDependencies);
     /** An active (non-soft-deleted) installation means the workspace is connected. */
     isWorkspaceConnected(workspaceId: string): Promise<boolean>;
+    /**
+     * Resolve the reference template through the workspace's INSTALLATION, which is the same reach
+     * the run's clone has.
+     *
+     * Deliberately NOT the workspace's repo projection (`resolveRepoFilesForCoords`), the way every
+     * other checkout-free read here is scoped. A reference architecture is an admin-managed entry
+     * naming `owner/name`, not a repository the board has linked, so the projection answers "no such
+     * repo" for a template the run then clones without trouble: the survey used to report the
+     * template as unsurveyed on every deployment whose template is not also a board service. What
+     * scopes this instead is the entry itself plus the installation's own grant, which is the pair
+     * that decides whether the clone works.
+     *
+     * A 404 is the provider's answer that this credential cannot see the repository, which on GitHub
+     * covers both "no such repo" and "the App was not granted it", and it is one verdict because
+     * they take the same fix. Any other failure is reported as UNREADABLE rather than as an absence,
+     * so an outage cannot be presented to an operator as a typo in their configuration.
+     *
+     * NEVER throws, which is a contract two callers depend on (the survey, whose whole phase is
+     * "park with what we know", and the pre-flight, which owes a 503). So the installation read sits
+     * INSIDE the try as well: on a mothership-mode node the repository read is an RPC to a process
+     * that can be a restart away, and a throw from there would arrive as a platform bug about
+     * somebody's own template.
+     */
+    resolveReferenceRepo(workspaceId: string, ref: {
+        owner: string;
+        name: string;
+    }): Promise<ReferenceRepoAccess>;
+    /**
+     * The one provider read behind every reference-template question: the pre-flight's verdict, the
+     * survey's reader and the dispatch's clone spec are all this, mapped three ways.
+     *
+     * Shared because the two callers used to ask it differently: one 404-aware and returning a
+     * verdict, the other collapsing every failure into one disposition. So the same rate limit was
+     * reported as the entry being wrong at one moment and as an outage at another. One probe, one
+     * set of causes, and each caller decides only what to DO about them.
+     */
+    private readTemplate;
     /**
      * Resolve a monorepo bootstrap target out of the WORKSPACE's own repo projection.
      *
@@ -153,23 +209,80 @@ export declare class ContainerRepoBootstrapper implements RepoBootstrapper {
      * 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
+     * ONE resolution for every dispatch shape, because they all CLONE the template and all 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.
+     * It THROWS on a template it cannot resolve, rather than dispatching with no id and the
+     * conventional branch: the container is about to clone it, so the run is over either way, and
+     * the difference is whether the report names the reference architecture and what to do about it
+     * or arrives as a git error from inside a container that had to be started first.
+     *
+     * The MESSAGE follows the cause the shared probe reported. "Point the reference architecture at
+     * a repository this workspace can reach" is the wrong instruction for a rate limit or a 500,
+     * and a monorepo apply dispatches days after a human settled its review, so the failure read
+     * here is as likely to be an outage as a typo. The provider error rides as `cause`, so a log
+     * describer walking the chain can still see which it was.
+     *
+     * Re-read rather than carried over from the run-start pre-flight, deliberately: this is the
+     * moment the clone happens, and on a monorepo run the pre-flight sits on the other side of a
+     * human review. An id plumbed through the request would be a claim about the repository as it
+     * was, dispatched against the repository as it is.
      */
     private resolveReferenceTemplate;
-    /** The model-locked LLM-proxy session token a bootstrap container runs under. */
+    /**
+     * Mint the job's clone/push token, scoped to the repos this dispatch resolved.
+     *
+     * The scope goes through the SHARED `jobTokenRepoIds` rather than a hand-built array, for the
+     * case the hand-built one got wrong: a reference architecture naming the run's own target (or
+     * its monorepo) is one repository asked for twice, and a `repository_ids` list is a set.
+     *
+     * A refusal is re-thrown NAMING the template, because a scoped mint has one failure mode this
+     * component cannot pre-flight away. GitHub narrows a token only to repositories the
+     * installation was GRANTED, while a PUBLIC repository reads perfectly well through the API
+     * without being one, so a template outside the App's repository access resolves cleanly above
+     * and is refused here. There is no read on this port that separates the two cheaply and
+     * correctly on every provider (`getRepoById` answers from a bounded listing on the GitLab
+     * adapter, so a null there is not evidence of anything), and dropping the leg would only move
+     * the failure to the clone. What is left is to make the refusal say which repository to grant.
+     */
+    private mintDispatchToken;
+    /**
+     * 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.
+     */
     private mintSessionToken;
     /** The host's web base, trailing slashes stripped, for building clone URLs. */
     private webBase;
     /** Poll a dispatched bootstrap job, mapping the runner job view into an update. */
     pollBootstrap(handle: BootstrapJobHandle): Promise<BootstrapJobUpdate>;
+    /**
+     * 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.
+     */
+    private jobHandle;
+    /**
+     * 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.
+     */
+    private resolvedModel;
+    /**
+     * 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.
+     */
+    private recordDispatchContext;
     /**
      * Best-effort: reclaim the per-run container for a job. Releases through the same
      * transport the run dispatched to (keyed by job id) — for the Cloudflare backend

package/dist/agents/ContainerRepoBootstrapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ContainerRepoBootstrapper.d.ts","sourceRoot":"","sources":["../../src/agents/ContainerRepoBootstrapper.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ContainerRepoBootstrapper.d.ts","sourceRoot":"","sources":["../../src/agents/ContainerRepoBootstrapper.ts"],"names":[],"mappings":"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"}

package/dist/agents/ContainerRepoBootstrapper.js

@@ -1,5 +1,10 @@
-import { failureKindFromHarnessCause, runBestEffort } from '@cat-factory/kernel';
+import { failureKindFromHarnessCause, getErrorMessage, runBestEffort, VcsApiError, } 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 { makeRepoFiles } from './repoFiles.js';
+import { jobTokenRepoIds } from './repoTargeting.js';
 import { RunnerJobClient } from './RunnerJobClient.js';
 import { logger } from '../observability/logger.js';
 /** The role prompt when adapting a cloned reference architecture. */
@@ -127,6 +132,87 @@ export class ContainerRepoBootstrapper {
         const installation = await this.deps.installationRepository.getByWorkspace(workspaceId);
         return !!installation && !installation.deletedAt;
     }
+    /**
+     * Resolve the reference template through the workspace's INSTALLATION, which is the same reach
+     * the run's clone has.
+     *
+     * Deliberately NOT the workspace's repo projection (`resolveRepoFilesForCoords`), the way every
+     * other checkout-free read here is scoped. A reference architecture is an admin-managed entry
+     * naming `owner/name`, not a repository the board has linked, so the projection answers "no such
+     * repo" for a template the run then clones without trouble: the survey used to report the
+     * template as unsurveyed on every deployment whose template is not also a board service. What
+     * scopes this instead is the entry itself plus the installation's own grant, which is the pair
+     * that decides whether the clone works.
+     *
+     * A 404 is the provider's answer that this credential cannot see the repository, which on GitHub
+     * covers both "no such repo" and "the App was not granted it", and it is one verdict because
+     * they take the same fix. Any other failure is reported as UNREADABLE rather than as an absence,
+     * so an outage cannot be presented to an operator as a typo in their configuration.
+     *
+     * NEVER throws, which is a contract two callers depend on (the survey, whose whole phase is
+     * "park with what we know", and the pre-flight, which owes a 503). So the installation read sits
+     * INSIDE the try as well: on a mothership-mode node the repository read is an RPC to a process
+     * that can be a restart away, and a throw from there would arrive as a platform bug about
+     * somebody's own template.
+     */
+    async resolveReferenceRepo(workspaceId, ref) {
+        let installation;
+        try {
+            installation = await this.deps.installationRepository.getByWorkspace(workspaceId);
+        }
+        catch (error) {
+            // A connection we cannot READ is not a connection we know to be absent: `not_connected`
+            // would tell the operator to install an App that may well already be installed.
+            return { status: 'unreadable', detail: getErrorMessage(error) };
+        }
+        if (!installation || installation.deletedAt)
+            return { status: 'not_connected' };
+        // The row's own provider, falling back to this client's for a row predating the column. A
+        // connection on another provider is not reachable from here whatever it holds, and reporting
+        // that as `not_found` is the misattribution the verdict split exists to prevent.
+        if ((installation.provider ?? this.deps.clientProvider) !== this.deps.clientProvider) {
+            return { status: 'not_connected' };
+        }
+        const read = await this.readTemplate(installation.installationId, ref);
+        if (read.status === 'not_found')
+            return { status: 'not_found' };
+        // Mapped field by field rather than passed through: the verdict crosses a port and becomes an
+        // HTTP `details.detail`, and the thrown value the probe kept for its own `cause` chain has no
+        // business on a wire shape.
+        if (read.status === 'unreadable')
+            return { status: 'unreadable', detail: read.detail };
+        return {
+            status: 'reachable',
+            files: makeRepoFiles(this.deps.githubClient, installation.installationId, {
+                owner: ref.owner,
+                repo: ref.name,
+            }),
+            defaultBranch: defaultBranchOf(read.repo),
+        };
+    }
+    /**
+     * The one provider read behind every reference-template question: the pre-flight's verdict, the
+     * survey's reader and the dispatch's clone spec are all this, mapped three ways.
+     *
+     * Shared because the two callers used to ask it differently: one 404-aware and returning a
+     * verdict, the other collapsing every failure into one disposition. So the same rate limit was
+     * reported as the entry being wrong at one moment and as an outage at another. One probe, one
+     * set of causes, and each caller decides only what to DO about them.
+     */
+    async readTemplate(installationId, ref) {
+        try {
+            const repo = await this.deps.githubClient.getRepo(installationId, {
+                owner: ref.owner,
+                repo: ref.name,
+            });
+            return { status: 'reachable', repo };
+        }
+        catch (error) {
+            if (error instanceof VcsApiError && error.status === 404)
+                return { status: 'not_found' };
+            return { status: 'unreadable', detail: getErrorMessage(error), cause: error };
+        }
+    }
     /**
      * Resolve a monorepo bootstrap target out of the WORKSPACE's own repo projection.
      *
@@ -190,23 +276,19 @@ export class ContainerRepoBootstrapper {
         // 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);
+        const webBase = this.webBase();
+        const targetCloneUrl = `${webBase}/${owner}/${repoName}.git`;
+        const defaultBranch = defaultBranchOf(target);
         // 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,
-            workspaceId: request.workspaceId,
-            repoIds: [String(target.githubId), ...(reference?.githubId ? [reference.githubId] : [])],
-        });
+        const ghToken = await this.mintDispatchToken(request, installation.installationId, { owner, name: repoName, repoId: String(target.githubId), baseBranch: defaultBranch }, reference);
         // 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.mintSessionToken(request);
-        const webBase = this.webBase();
-        const targetCloneUrl = `${webBase}/${owner}/${repoName}.git`;
-        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
@@ -226,12 +308,12 @@ export class ContainerRepoBootstrapper {
             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.
+            // 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 ||
@@ -273,6 +355,7 @@ 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,
@@ -443,14 +526,10 @@ export class ContainerRepoBootstrapper {
      * 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.
+        // Re-flighted here for the same reason the monorepo's target directory is: an apply dispatch
+        // can be days after the review, and a template that has since moved out of reach is a clone
+        // this run is about to fail.
         const reference = await this.resolveReferenceTemplate(request, installation.installationId, log);
-        const repoIds = [
-            String(spec.repoGithubId),
-            ...(reference?.githubId ? [reference.githubId] : []),
-        ];
         const referenceRepos = reference
             ? [
                 {
@@ -463,11 +542,13 @@ export class ContainerRepoBootstrapper {
                 },
             ]
             : [];
-        const ghToken = await this.deps.mintInstallationToken(installation.installationId, {
-            executionId: request.containerJobId,
-            workspaceId: request.workspaceId,
-            repoIds,
-        });
+        // Scoped to the repos this run touches: the one it pushes to, and the template it reads.
+        const ghToken = await this.mintDispatchToken(request, installation.installationId, {
+            owner: spec.repo.owner,
+            name: spec.repo.name,
+            repoId: String(spec.repoGithubId),
+            baseBranch: spec.repo.baseBranch,
+        }, reference);
         const packageRegistries = (await this.deps.resolvePackageRegistries?.(request.workspaceId)) ?? [];
         const sessionToken = await this.mintSessionToken(request);
         // The delivery decides the two fields TOGETHER: with `newBranch` and `pr` the harness pushes
@@ -479,7 +560,8 @@ export class ContainerRepoBootstrapper {
         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: spec.systemPrompt,
             userPrompt: spec.userPrompt,
@@ -504,6 +586,7 @@ export class ContainerRepoBootstrapper {
             branch: request.delivery.mode === 'pull_request' ? request.delivery.branch : spec.repo.baseBranch,
             reference: reference ? `${reference.owner}/${reference.name}` : null,
         });
+        await this.recordDispatchContext(request, body, log);
         return {
             workspaceId: request.workspaceId,
             jobId: request.jobId,
@@ -514,38 +597,106 @@ export class ContainerRepoBootstrapper {
      * 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
+     * ONE resolution for every dispatch shape, because they all CLONE the template and all 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.
+     * It THROWS on a template it cannot resolve, rather than dispatching with no id and the
+     * conventional branch: the container is about to clone it, so the run is over either way, and
+     * the difference is whether the report names the reference architecture and what to do about it
+     * or arrives as a git error from inside a container that had to be started first.
+     *
+     * The MESSAGE follows the cause the shared probe reported. "Point the reference architecture at
+     * a repository this workspace can reach" is the wrong instruction for a rate limit or a 500,
+     * and a monorepo apply dispatches days after a human settled its review, so the failure read
+     * here is as likely to be an outage as a typo. The provider error rides as `cause`, so a log
+     * describer walking the chain can still see which it was.
+     *
+     * Re-read rather than carried over from the run-start pre-flight, deliberately: this is the
+     * moment the clone happens, and on a monorepo run the pre-flight sits on the other side of a
+     * human review. An id plumbed through the request would be a claim about the repository as it
+     * was, dispatched against the repository as it is.
      */
     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,
-        };
+        const repo = `${reference.owner}/${reference.name}`;
+        const read = await this.readTemplate(installationId, reference);
+        if (read.status === 'reachable') {
+            return {
+                owner: reference.owner,
+                name: reference.name,
+                repoId: String(read.repo.githubId),
+                baseBranch: defaultBranchOf(read.repo),
+                cloneUrl: `${this.webBase()}/${reference.owner}/${reference.name}.git`,
+            };
+        }
+        log.warn('bootstrap: reference template could not be resolved', {
+            reference: repo,
+            verdict: read.status,
+        });
+        if (read.status === 'not_found') {
+            throw new Error(`The reference template ${repo} cannot be seen through this workspace's source-control ` +
+                `connection, so it cannot be cloned. Point the reference architecture at a repository ` +
+                `this workspace can reach, or grant the App access to it, then retry.`);
+        }
+        throw new Error(`The reference template ${repo} could not be read just now, so this run was not dispatched ` +
+            `rather than dispatched against a template it may be unable to clone. Nothing here is ` +
+            `misconfigured: retry once the source-control connection recovers. Cause: ${read.detail}`, { cause: read.cause });
+    }
+    /**
+     * Mint the job's clone/push token, scoped to the repos this dispatch resolved.
+     *
+     * The scope goes through the SHARED `jobTokenRepoIds` rather than a hand-built array, for the
+     * case the hand-built one got wrong: a reference architecture naming the run's own target (or
+     * its monorepo) is one repository asked for twice, and a `repository_ids` list is a set.
+     *
+     * A refusal is re-thrown NAMING the template, because a scoped mint has one failure mode this
+     * component cannot pre-flight away. GitHub narrows a token only to repositories the
+     * installation was GRANTED, while a PUBLIC repository reads perfectly well through the API
+     * without being one, so a template outside the App's repository access resolves cleanly above
+     * and is refused here. There is no read on this port that separates the two cheaply and
+     * correctly on every provider (`getRepoById` answers from a bounded listing on the GitLab
+     * adapter, so a null there is not evidence of anything), and dropping the leg would only move
+     * the failure to the clone. What is left is to make the refusal say which repository to grant.
+     */
+    async mintDispatchToken(request, installationId, primary, template) {
+        const asTarget = (leg) => ({ installationId, ...leg });
+        try {
+            return await this.deps.mintInstallationToken(installationId, {
+                // The RUN, not this phase's drive id: see the session mint below.
+                executionId: request.jobId,
+                workspaceId: request.workspaceId,
+                repoIds: jobTokenRepoIds(asTarget(primary), template ? [asTarget(template)] : []),
+            });
+        }
+        catch (error) {
+            if (!template)
+                throw error;
+            throw new Error(`The source-control token for this run could not be issued for both ` +
+                `${primary.owner}/${primary.name} and the reference template ` +
+                `${template.owner}/${template.name}. A GitHub App token can only cover repositories ` +
+                `the installation has been GRANTED, and a public repository reads through the API ` +
+                `without being one. Grant the App access to ${template.owner}/${template.name}, or ` +
+                `point the reference architecture at a repository it already covers, then retry. ` +
+                `Cause: ${getErrorMessage(error)}`, { cause: error });
+        }
     }
-    /** The model-locked LLM-proxy session token a bootstrap container runs under. */
+    /**
+     * 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.containerJobId,
-            agentKind: 'architect',
+            executionId: request.jobId,
+            agentKind: REPO_BOOTSTRAP_AGENT_KIND,
             provider: this.deps.model.provider,
             model: this.deps.model.model,
         });
@@ -560,6 +711,13 @@ export class ContainerRepoBootstrapper {
             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' };
         }
@@ -608,6 +766,48 @@ export class ContainerRepoBootstrapper {
         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
      * transport the run dispatched to (keyed by job id) — for the Cloudflare backend
@@ -690,6 +890,18 @@ export class ContainerRepoBootstrapper {
         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) {
     return repo.defaultBranch ?? 'main';