@cat-factory/orchestration 0.294.0 → 0.296.0

package/dist/modules/bootstrap/BootstrapService.js

@@ -1,5 +1,7 @@
-import { assertFound, ConflictError, getErrorMessage, isDispatchFailure, sameSubtasks, } from '@cat-factory/kernel';
+import { assertFound, ConflictError, getErrorMessage, isDispatchFailure, noopLogger, redactSecrets, renderAdoptionBrief, renderAdoptionPrSection, resolveAdoptionReview, runBestEffort, sameSubtasks, } from '@cat-factory/kernel';
 import { registerServiceForFrame, requireWorkspace } from '@cat-factory/kernel';
+import { monorepoBootstrapPrTitle } from '@cat-factory/agents';
+import { MonorepoBootstrapController, } from './MonorepoBootstrapController.js';
 function toReferenceArchitecture(record) {
     return {
         id: record.id,
@@ -28,18 +30,55 @@ function toBootstrapJob(record) {
         subtasks: record.subtasks,
         error: record.error,
         failure: record.failure,
+        monorepo: record.monorepo,
+        phase: record.phase,
+        adoptionPlan: record.adoptionPlan,
+        adoptionReview: record.adoptionReview,
+        prUrl: record.prUrl,
         createdAt: record.createdAt,
         updatedAt: record.updatedAt,
     };
 }
+/** The fields every new bootstrap run starts with; the monorepo half overrides what it owns. */
+function newRunDefaults(id) {
+    return {
+        monorepo: null,
+        phase: null,
+        // A single-drive run keys its driver on its own id, which is what every existing bootstrap
+        // did before the monorepo flow needed a second drive.
+        driveId: id,
+        adoptionPlan: null,
+        adoptionReview: null,
+        prUrl: null,
+    };
+}
 /** Join the reference architecture's default instructions with per-run extras. */
 function composeInstructions(defaults, extra) {
     return [defaults.trim(), extra.trim()].filter((part) => part.length > 0).join('\n\n');
 }
+/**
+ * How long a survey claim holds before another drive may take it.
+ *
+ * Sized against what the claim covers: a bounded set of checkout-free reads plus one inline model
+ * call, so minutes rather than hours. It exists because a claimer can die between taking the claim
+ * and writing the plan (an evicted isolate, a restarted worker), and a claim with no expiry would
+ * leave that run parked on nothing with no way back in.
+ */
+const SURVEY_CLAIM_TTL_MS = 10 * 60_000;
 export class BootstrapService {
     deps;
+    /** The monorepo flow's decisions; a plain new-repo run never reaches it. */
+    monorepo;
+    /** Normalised once, so the best-effort paths stay unit-testable with no logger wired. */
+    log;
     constructor(deps) {
         this.deps = deps;
+        this.log = deps.logger ?? noopLogger;
+        this.monorepo = new MonorepoBootstrapController({
+            ...deps.monorepo,
+            clock: deps.clock,
+            logger: deps.logger,
+        });
     }
     /** True when a bootstrap run can actually be performed (the bootstrapper is wired). */
     get canBootstrap() {
@@ -150,9 +189,17 @@ export class BootstrapService {
             ? assertFound(await this.deps.referenceArchitectureRepository.get(workspaceId, input.referenceArchitectureId), 'Reference architecture', input.referenceArchitectureId)
             : null;
         const instructions = composeInstructions(reference?.defaultInstructions ?? '', input.instructions);
+        // Pre-flight the monorepo BEFORE any row is written, the same ordering the new-repo path
+        // gets from dispatching before it creates a frame: a refused target (unlinked repo, a
+        // directory that already holds a service) leaves neither a job nor a board card behind.
+        const monorepo = input.monorepo
+            ? await this.monorepo.resolveTarget(bootstrapper, workspaceId, input.monorepo)
+            : null;
         const now = this.deps.clock.now();
+        const id = this.deps.idGenerator.next('boot');
         const record = {
-            id: this.deps.idGenerator.next('boot'),
+            ...newRunDefaults(id),
+            id,
             workspaceId,
             referenceArchitectureId: reference?.id ?? null,
             referenceArchitectureName: reference?.name ?? null,
@@ -165,10 +212,25 @@ export class BootstrapService {
             subtasks: null,
             error: null,
             failure: null,
+            ...(monorepo ? { monorepo: monorepo.ref, phase: 'survey' } : {}),
             createdAt: now,
             updatedAt: now,
         };
         await this.deps.bootstrapJobRepository.insert(record);
+        // A monorepo run dispatches NOTHING yet. Its first phase is the survey, which is a bounded
+        // set of checkout-free reads plus one inline model call (no container, no clone), so the
+        // durable driver runs it on its first poll and the request returns immediately, exactly as
+        // the container path does. The frame is materialised now rather than after a dispatch,
+        // because the pre-flight above has already taken every refusal this phase can raise.
+        if (monorepo) {
+            const frame = await this.createServiceFrame(workspaceId, input.repoName, input.type ?? 'service', monorepo.ref);
+            const started = { blockId: frame.id, updatedAt: this.deps.clock.now() };
+            await this.deps.bootstrapJobRepository.update(workspaceId, record.id, started);
+            const job = toBootstrapJob({ ...record, ...started });
+            await this.deps.bootstrapRunner?.startRun(workspaceId, record.id, record.driveId);
+            await this.emitBootstrap(workspaceId, job, frame);
+            return job;
+        }
         // Dispatch the container first: its pre-flight (target exists, reachable,
         // empty-or-boilerplate) is the gate that most runs fail on, so failing here
         // before creating a board frame keeps the board clean on the common errors.
@@ -176,6 +238,7 @@ export class BootstrapService {
             await bootstrapper.startBootstrap({
                 workspaceId,
                 jobId: record.id,
+                containerJobId: record.driveId,
                 referenceRepo: reference
                     ? { owner: reference.repoOwner, name: reference.repoName }
                     : undefined,
@@ -203,7 +266,7 @@ export class BootstrapService {
             };
             await this.deps.bootstrapJobRepository.update(workspaceId, record.id, patch);
             // A failed dispatch may still have spun a container up; reclaim it best-effort.
-            await this.stopContainer(workspaceId, record.id);
+            await this.stopContainer(workspaceId, record.id, record.driveId);
             const failed = toBootstrapJob({ ...record, ...patch });
             await this.emitBootstrap(workspaceId, failed, null);
             return failed;
@@ -216,7 +279,7 @@ export class BootstrapService {
         const job = toBootstrapJob({ ...record, ...started });
         // Hand off the long poll loop to the durable driver (the worker's
         // BootstrapWorkflow). Without a runner (tests) the caller polls directly.
-        await this.deps.bootstrapRunner?.startRun(workspaceId, record.id);
+        await this.deps.bootstrapRunner?.startRun(workspaceId, record.id, record.driveId);
         await this.emitBootstrap(workspaceId, job, frame);
         return job;
     }
@@ -249,8 +312,10 @@ export class BootstrapService {
             referenceRepo = { owner: reference.repoOwner, name: reference.repoName };
         }
         const now = this.deps.clock.now();
+        const id = this.deps.idGenerator.next('boot');
         const record = {
-            id: this.deps.idGenerator.next('boot'),
+            ...newRunDefaults(id),
+            id,
             workspaceId,
             referenceArchitectureId: previous.referenceArchitectureId,
             referenceArchitectureName: previous.referenceArchitectureName,
@@ -265,16 +330,51 @@ export class BootstrapService {
             subtasks: null,
             error: null,
             failure: null,
+            // A monorepo retry carries the SETTLED review forward, and the plan it was settled
+            // against with it. Re-surveying would throw away a decision a human already made and ask
+            // them for it again, which is the one thing a retry must not do: the failure being
+            // retried is a container fault, not a change of mind. The phase is preserved too: a run
+            // that failed during the survey retries the survey.
+            //
+            // A plan that is NOT ready is dropped instead, and that is what makes a retry the way out
+            // of an unavailable one: the causes are an unwired model, an unreadable repository and an
+            // exhausted budget, all of which an operator fixes OUTSIDE the run, so carrying the stale
+            // plan forward would re-park on the old failure and no state transition would ever reach
+            // the working advisor. The new row also carries no survey claim (it is a new id), so the
+            // re-survey is claimable.
+            monorepo: previous.monorepo,
+            phase: previous.phase,
+            adoptionPlan: previous.adoptionPlan?.status === 'ready' ? previous.adoptionPlan : null,
+            adoptionReview: previous.adoptionReview,
             createdAt: now,
             updatedAt: now,
         };
         await this.deps.bootstrapJobRepository.insert(record);
+        // A monorepo retry re-enters at its own phase rather than dispatching: a survey retry
+        // re-runs the reads on the next poll, and an apply retry re-dispatches through the same
+        // path the review's resume uses, so neither has a second copy of the dispatch here.
+        if (record.monorepo) {
+            const frame = previous.blockId
+                ? await this.markFrame(workspaceId, previous.blockId, 'in_progress', 'Bootstrapping into the monorepo… retrying after a failed run.')
+                : null;
+            const blockId = frame?.id ?? previous.blockId;
+            await this.deps.bootstrapJobRepository.update(workspaceId, record.id, { blockId });
+            const resumed = { ...record, blockId };
+            if (record.phase === 'apply' && record.adoptionReview) {
+                return await this.dispatchApply(workspaceId, resumed, record.adoptionReview);
+            }
+            await this.deps.bootstrapRunner?.startRun(workspaceId, record.id, record.driveId);
+            const job = toBootstrapJob(resumed);
+            await this.emitBootstrap(workspaceId, job, frame);
+            return job;
+        }
         // Dispatch a fresh container under the new job id (description/private aren't
         // forwarded — the target repo already exists — so defaults are harmless).
         try {
             await bootstrapper.startBootstrap({
                 workspaceId,
                 jobId: record.id,
+                containerJobId: record.driveId,
                 referenceRepo,
                 target: { name: record.repoName, description: '', private: true },
                 instructions: record.instructions,
@@ -290,7 +390,7 @@ export class BootstrapService {
                 updatedAt: this.deps.clock.now(),
             };
             await this.deps.bootstrapJobRepository.update(workspaceId, record.id, patch);
-            await this.stopContainer(workspaceId, record.id);
+            await this.stopContainer(workspaceId, record.id, record.driveId);
             // Re-mark the reused frame blocked (it briefly belonged to this attempt).
             const block = previous.blockId
                 ? await this.markFrame(workspaceId, previous.blockId, 'blocked', `Bootstrap failed: ${message}`)
@@ -311,7 +411,7 @@ export class BootstrapService {
         const started = { blockId, updatedAt: this.deps.clock.now() };
         await this.deps.bootstrapJobRepository.update(workspaceId, record.id, started);
         const job = toBootstrapJob({ ...record, ...started });
-        await this.deps.bootstrapRunner?.startRun(workspaceId, record.id);
+        await this.deps.bootstrapRunner?.startRun(workspaceId, record.id, record.driveId);
         await this.emitBootstrap(workspaceId, job, frame);
         return job;
     }
@@ -329,10 +429,23 @@ export class BootstrapService {
             return { state: 'done' };
         if (record.status === 'failed')
             return { state: 'failed', error: record.error ?? undefined };
+        if (record.status === 'awaiting_review')
+            return { state: 'awaiting_review' };
+        // The monorepo flow's SURVEY phase has no container to poll: it reads both repositories
+        // through the checkout-free port and asks a model to judge. Doing it here rather than in
+        // `bootstrap()` keeps the start request fast and puts the work on the durable driver, which
+        // is what makes it survive an eviction. Re-entering an already-surveyed run is a no-op
+        // (the stored plan is the claim), so the driver's retries and replays are safe.
+        if (record.phase === 'survey')
+            return await this.runSurvey(workspaceId, record);
         const bootstrapper = this.deps.repoBootstrapper;
         if (!bootstrapper)
             throw new Error('Repository bootstrapping is not configured');
-        const update = await bootstrapper.pollBootstrap({ workspaceId, jobId });
+        const update = await bootstrapper.pollBootstrap({
+            workspaceId,
+            jobId,
+            containerJobId: record.driveId,
+        });
         if (update.state === 'running') {
             // Only persist + push when the counts actually changed, to avoid a write +
             // broadcast on every idle poll.
@@ -355,11 +468,16 @@ export class BootstrapService {
             await this.deps.bootstrapJobRepository.update(workspaceId, jobId, patch);
             // Reclaim the per-run container so a faulted/leaked instance doesn't idle
             // until its sleep timer (best-effort; an evicted container is already gone).
-            await this.stopContainer(workspaceId, jobId);
+            await this.stopContainer(workspaceId, jobId, record.driveId);
             const block = await this.markFrame(workspaceId, record.blockId, 'blocked', `Bootstrap failed: ${message}`);
             await this.emitBootstrap(workspaceId, toBootstrapJob({ ...record, ...patch }), block);
             return { state: 'failed', error: message };
         }
+        // Done on a MONOREPO run: the deliverable is a pull request against a repository that
+        // already exists, so there is no repo to create, project or name: the frame is bound to the
+        // monorepo it was pre-flighted against, pinned to its directory.
+        if (record.monorepo)
+            return await this.finishMonorepoApply(workspaceId, record, update.prUrl);
         // Done: record the repo, link it to the frame (so dropped tasks target it),
         // and flip the frame to a ready, droppable service.
         const outcome = update.outcome;
@@ -375,7 +493,7 @@ export class BootstrapService {
         // Reclaim the per-run container on success too (the failure path above already
         // does): a bootstrapped repo otherwise leaves its container to idle out its
         // sleep timer. Best-effort — an evicted/auto-slept container is already gone.
-        await this.stopContainer(workspaceId, jobId);
+        await this.stopContainer(workspaceId, jobId, record.driveId);
         if (record.blockId) {
             // Best-effort: a failure to link must not flip a successful run to failed —
             // the repo is bootstrapped; the projection reconciles on the next sync. Project
@@ -392,7 +510,7 @@ export class BootstrapService {
                 }
             }
             catch {
-                // swallow — see above
+                // swallow: see above
             }
         }
         const block = await this.markFrame(workspaceId, record.blockId, 'ready', `Service bootstrapped from ${outcome.owner}/${outcome.name}. Drop tasks here to implement against it.`);
@@ -408,7 +526,7 @@ export class BootstrapService {
                 await this.deps.onBootstrapSucceeded?.(workspaceId, record.blockId);
             }
             catch {
-                // swallow — see above
+                // swallow: see above
             }
         }
         return { state: 'done' };
@@ -428,8 +546,8 @@ export class BootstrapService {
             return toBootstrapJob(record);
         // Kill the per-run container first, then the durable driver, so neither is left
         // running once the job is marked terminal. Both are best-effort/idempotent.
-        await this.stopContainer(workspaceId, jobId);
-        await this.deps.bootstrapRunner?.cancelRun(workspaceId, jobId);
+        await this.stopContainer(workspaceId, jobId, record.driveId);
+        await this.deps.bootstrapRunner?.cancelRun(workspaceId, record.driveId);
         const message = opts.reason ?? 'Stopped by the user.';
         const patch = {
             status: 'failed',
@@ -442,6 +560,259 @@ export class BootstrapService {
         await this.emitBootstrap(workspaceId, toBootstrapJob({ ...record, ...patch }), block);
         return toBootstrapJob({ ...record, ...patch });
     }
+    /**
+     * The durable-driver key a run is CURRENTLY driven under, for the stale-run sweeper.
+     *
+     * The sweeper reads `agent_runs` generically and only ever learns a run's id, but a monorepo
+     * run in its apply phase is driven under a different key, so probing and re-driving it by run
+     * id would find no instance and finalize a perfectly healthy run as an orphan. Falls back to
+     * the run id for a run it cannot read, which is the key every single-drive run uses.
+     */
+    async driveIdOf(workspaceId, jobId) {
+        const record = await this.deps.bootstrapJobRepository.get(workspaceId, jobId);
+        return record?.driveId ?? jobId;
+    }
+    // ---- the monorepo flow's three moves ------------------------------------
+    /**
+     * The SURVEY phase, run on the durable driver's first poll: read the monorepo and the
+     * reference template, ask the advisor what the new service should adopt from each, and park
+     * the run on the human decision.
+     *
+     * It never fails the run. A missing model, an unreadable repository or an unusable reply all
+     * park with a plan recorded `unavailable` and the cause, because the DECISION is the point of
+     * the phase and the suggestion is only an aid: a human bootstrapping into a monorepo on a
+     * deployment with no model still gets to make the call, unaided and told so.
+     *
+     * Guarded by an ATOMIC CLAIM taken BEFORE the model call, not by the plan written after it. A
+     * stored plan short-circuits a LATER drive, but two drives racing the FIRST one both read no
+     * plan, and the survey's cost is a vendor call plus a `park` that would replace the plan under
+     * a reviewer already looking at the other one (whose answers then 422). `claimSurvey` is one
+     * conditional UPDATE, so exactly one drive proceeds and the loser leaves the run alone.
+     */
+    async runSurvey(workspaceId, record) {
+        if (record.adoptionPlan) {
+            // A plan is already recorded. Bring the row's status in line with it (a driver that died
+            // between producing the plan and recording the park re-enters here) and stop. That holds
+            // for an `unavailable` plan too: re-surveying would spend again on a park a human can
+            // already settle, and `retry` is the deliberate re-survey (it clears a non-ready plan).
+            if (record.status !== 'awaiting_review') {
+                await this.park(workspaceId, record, record.adoptionPlan);
+            }
+            return { state: 'awaiting_review' };
+        }
+        const now = this.deps.clock.now();
+        const claimed = await this.deps.bootstrapJobRepository.claimSurvey(workspaceId, record.id, {
+            at: now,
+            staleBefore: now - SURVEY_CLAIM_TTL_MS,
+        });
+        if (!claimed) {
+            // Another drive holds the claim and will park the run. Reported as still RUNNING because
+            // that is what the row says: the next poll reads the winner's plan and parks.
+            return { state: 'running' };
+        }
+        const reference = record.referenceArchitectureId
+            ? await this.deps.referenceArchitectureRepository.get(workspaceId, record.referenceArchitectureId)
+            : null;
+        const plan = await this.monorepo.buildAdoptionPlan(workspaceId, record, reference);
+        await this.park(workspaceId, record, plan);
+        return { state: 'awaiting_review' };
+    }
+    /** Record the plan, flip the run + its frame to "waiting for you", and announce it. */
+    async park(workspaceId, record, adoptionPlan) {
+        const patch = {
+            status: 'awaiting_review',
+            adoptionPlan,
+            updatedAt: this.deps.clock.now(),
+        };
+        await this.deps.bootstrapJobRepository.update(workspaceId, record.id, patch);
+        const block = await this.markFrame(workspaceId, record.blockId, 'blocked', adoptionPlan?.status === 'ready'
+            ? `Waiting for review: which conventions this service should adopt from ${record.monorepo?.repoOwner}/${record.monorepo?.repoName} and which to keep from the template.`
+            : `Waiting for review: the platform could not produce an adoption suggestion, so the decisions are yours to make before the service is written.`);
+        await this.emitBootstrap(workspaceId, toBootstrapJob({ ...record, ...patch }), block);
+    }
+    /**
+     * Settle a parked run's adoption decisions and resume it.
+     *
+     * The refusals are the interesting half. A run that is not parked is a 409 naming where it
+     * actually is (the reviewer is looking at a stale tab, and applying their answers to a run
+     * that has moved on would build under a review given for a different proposal), and an
+     * incomplete or mismatched set of choices is a 422 from `resolveAdoptionReview`, never a
+     * silent fill from the recommendation, which would erase the difference between a human
+     * agreeing with the suggestion and never having read it.
+     */
+    async submitAdoptionReview(workspaceId, jobId, input, reviewedByUserId) {
+        await requireWorkspace(this.deps.workspaceRepository, workspaceId);
+        const record = assertFound(await this.deps.bootstrapJobRepository.get(workspaceId, jobId), 'Bootstrap job', jobId, { reason: 'bootstrap_job_not_found' });
+        if (record.status !== 'awaiting_review') {
+            throw new ConflictError(`This bootstrap is not waiting for an adoption review (it is '${record.status}').`, 'bootstrap_not_awaiting_review', { status: record.status });
+        }
+        if (!record.monorepo || !record.adoptionPlan) {
+            throw new ConflictError('This bootstrap has no adoption plan recorded, so there is nothing to approve.', 'adoption_plan_unavailable', { unavailableReason: null });
+        }
+        const resolved = resolveAdoptionReview(record.adoptionPlan, input.choices, {
+            reviewedByUserId,
+            reviewedAt: this.deps.clock.now(),
+            notes: input.notes,
+        });
+        return await this.dispatchApply(workspaceId, record, resolved);
+    }
+    /**
+     * The APPLY phase: dispatch the container that writes the service into the monorepo under the
+     * settled decisions and opens the pull request.
+     *
+     * Its own drive id, because this is the run's SECOND durable drive: the survey's already went
+     * terminal, and neither facade's driver can be re-keyed on a key that has (a Workflows
+     * instance id cannot be recreated; a pg-boss singleton would dedupe against the finished job).
+     */
+    async dispatchApply(workspaceId, record, resolved) {
+        const bootstrapper = this.deps.repoBootstrapper;
+        const monorepo = record.monorepo;
+        if (!bootstrapper || !monorepo) {
+            throw new Error('Repository bootstrapping is not configured');
+        }
+        const reference = record.referenceArchitectureId
+            ? await this.deps.referenceArchitectureRepository.get(workspaceId, record.referenceArchitectureId)
+            : null;
+        const branch = this.monorepo.branchFor(record.id);
+        // `-apply`, not `:apply`: this string becomes a Cloudflare Workflows INSTANCE ID, whose
+        // accepted character set is narrower than a run id's and does not include a colon, and a
+        // rejected `create` is swallowed by design (a duplicate start is normal), so the failure
+        // would be an approved bootstrap that silently never dispatches.
+        const driveId = `${record.id}-apply`;
+        const leg = {
+            repoGithubId: monorepo.repoGithubId,
+            owner: monorepo.repoOwner,
+            name: monorepo.repoName,
+            directory: monorepo.directory,
+            branch,
+            pr: {
+                title: monorepoBootstrapPrTitle(record.repoName, monorepo.directory),
+                // The HOST rendering (neutralised holes, scrubbed at compose time), never the agent
+                // brief: this string lands on a pull request body, where a reviewer's note reading
+                // "fixes #412" would close an unrelated issue on merge. It is the FALLBACK body; the
+                // engine also publishes the same decisions as its own marker region once the pull
+                // request exists, because the harness lets an agent-authored description replace this.
+                body: redactSecrets(renderAdoptionPrSection(resolved, monorepo.directory)) ?? '',
+            },
+        };
+        const started = { ...monorepo, branch };
+        const patch = {
+            status: 'running',
+            phase: 'apply',
+            driveId,
+            adoptionReview: resolved,
+            monorepo: started,
+            error: null,
+            failure: null,
+            updatedAt: this.deps.clock.now(),
+        };
+        // Record the settled review BEFORE dispatching. The decisions are the human's, and losing
+        // them to a dispatch failure would send them back to a review they already gave; with them
+        // committed first, a retry re-dispatches under the same decisions.
+        await this.deps.bootstrapJobRepository.update(workspaceId, record.id, patch);
+        try {
+            await bootstrapper.startBootstrap({
+                workspaceId,
+                jobId: record.id,
+                containerJobId: driveId,
+                referenceRepo: reference
+                    ? { owner: reference.repoOwner, name: reference.repoName }
+                    : undefined,
+                target: { name: record.repoName, description: '', private: true },
+                monorepo: leg,
+                // The agent's brief is the run's own instructions PLUS the settled decisions, rendered
+                // as instructions rather than as context: an agent told only what the areas are decides
+                // them again, which is precisely what the review exists to prevent.
+                instructions: `${record.instructions}\n\n${renderAdoptionBrief(resolved, monorepo.directory)}`,
+            });
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            const kind = isDispatchFailure(error) ? 'dispatch' : 'preflight';
+            const failed = {
+                status: 'failed',
+                error: message,
+                failure: this.buildFailure(kind, message, null, record.subtasks),
+                updatedAt: this.deps.clock.now(),
+            };
+            await this.deps.bootstrapJobRepository.update(workspaceId, record.id, failed);
+            await this.stopContainer(workspaceId, record.id, driveId);
+            const block = await this.markFrame(workspaceId, record.blockId, 'blocked', `Bootstrap failed: ${message}`);
+            const job = toBootstrapJob({ ...record, ...patch, ...failed });
+            await this.emitBootstrap(workspaceId, job, block);
+            return job;
+        }
+        const frame = await this.markFrame(workspaceId, record.blockId, 'in_progress', `Writing ${monorepo.directory} into ${monorepo.repoOwner}/${monorepo.repoName}…`);
+        await this.deps.bootstrapRunner?.startRun(workspaceId, record.id, driveId);
+        const job = toBootstrapJob({ ...record, ...patch });
+        await this.emitBootstrap(workspaceId, job, frame);
+        return job;
+    }
+    /**
+     * Finish a monorepo apply: bind the frame's service to the monorepo AT ITS DIRECTORY and
+     * report the pull request.
+     *
+     * A completed apply with NO pull request is a failure, not a success with a null field: the
+     * deliverable of a monorepo bootstrap is the PR (nothing is merged for the reviewer), so a run
+     * that reports done without one has left the work somewhere nobody can find it. Failing here
+     * says that, where marking the frame ready would claim a service that does not exist.
+     */
+    async finishMonorepoApply(workspaceId, record, prUrl) {
+        const monorepo = record.monorepo;
+        await this.stopContainer(workspaceId, record.id, record.driveId);
+        if (!monorepo || !prUrl) {
+            const message = 'The bootstrap agent finished without opening a pull request, so the new service was not delivered anywhere.';
+            const patch = {
+                status: 'failed',
+                error: message,
+                failure: this.buildFailure('agent', message, null, record.subtasks),
+                updatedAt: this.deps.clock.now(),
+            };
+            await this.deps.bootstrapJobRepository.update(workspaceId, record.id, patch);
+            const blocked = await this.markFrame(workspaceId, record.blockId, 'blocked', `Bootstrap failed: ${message}`);
+            await this.emitBootstrap(workspaceId, toBootstrapJob({ ...record, ...patch }), blocked);
+            return { state: 'failed', error: message };
+        }
+        const patch = {
+            status: 'succeeded',
+            repoOwner: monorepo.repoOwner,
+            // `repoUrl` stays null. It is the public API's "web URL of the created repository", and a
+            // monorepo run creates none: writing the pull request there would re-scope a released
+            // field in place, and an integration that clones `repoUrl` would clone a PR link. `prUrl`
+            // is the field this run's deliverable belongs in, and it is projected publicly beside it.
+            prUrl,
+            updatedAt: this.deps.clock.now(),
+        };
+        await this.deps.bootstrapJobRepository.update(workspaceId, record.id, patch);
+        const review = record.adoptionReview;
+        if (review) {
+            // Best-effort: the pull request is open, the decisions are on the run record the board
+            // renders, and failing the run over a description write would discard a delivered service.
+            // The warning is what makes the omission visible rather than silent.
+            await runBestEffort(this.log, 'monorepo bootstrap: publish adoption decisions onto the pull request', () => this.monorepo.publishAdoptionDecisions(workspaceId, monorepo, prUrl, review), { workspaceId, jobId: record.id, prUrl });
+        }
+        if (record.blockId) {
+            // Best-effort, as on the new-repo path: the pull request is open either way, and a
+            // linkage failure must not report the run as failed. The `directory` is what makes the
+            // linkage a monorepo one: `resolveRepoTarget` scopes every agent working on this service
+            // to that subtree, and the repo's monorepo flag was set at pre-flight so it is honoured.
+            try {
+                const service = await this.deps.serviceRepository?.getByFrameBlock(record.blockId);
+                if (service) {
+                    await this.deps.serviceRepository?.update(service.id, {
+                        repoGithubId: monorepo.repoGithubId,
+                        directory: monorepo.directory,
+                    });
+                }
+            }
+            catch {
+                // swallow: see above
+            }
+        }
+        const block = await this.markFrame(workspaceId, record.blockId, 'ready', `Service bootstrapped into ${monorepo.repoOwner}/${monorepo.repoName} at ${monorepo.directory}. Review and merge the pull request, then drop tasks here.`);
+        await this.emitBootstrap(workspaceId, toBootstrapJob({ ...record, ...patch }), block);
+        return { state: 'done' };
+    }
     // ---- helpers ------------------------------------------------------------
     /** The workspace default fragment ids a new service inherits; empty / never throws. */
     async defaultServiceFragmentIds(workspaceId) {
@@ -454,8 +825,15 @@ export class BootstrapService {
             return [];
         }
     }
-    /** Create the provisional, in-progress service frame a bootstrap run materialises. */
-    async createServiceFrame(workspaceId, repoName, frameType = 'service') {
+    /**
+     * Create the provisional, in-progress service frame a bootstrap run materialises.
+     *
+     * A monorepo run's frame carries its `directory` from the start, while the repo binding waits
+     * for the run to succeed exactly as the new-repo path's does: the directory is a fact the
+     * pre-flight already settled (and what the board card is about), whereas the linkage is a
+     * claim that there is code there, which is only true once the pull request exists.
+     */
+    async createServiceFrame(workspaceId, repoName, frameType = 'service', monorepo) {
         const blocks = await this.deps.blockRepository.listByWorkspace(workspaceId);
         const frames = blocks.filter((b) => b.level === 'frame').length;
         const type = frameType;
@@ -464,7 +842,9 @@ export class BootstrapService {
             id: this.deps.idGenerator.next('blk'),
             title: repoName,
             type,
-            description: 'Bootstrapping repository… a container is adapting and pushing the initial commit.',
+            description: monorepo
+                ? `Bootstrapping ${monorepo.directory} in ${monorepo.repoOwner}/${monorepo.repoName}… surveying the monorepo's conventions.`
+                : 'Bootstrapping repository… a container is adapting and pushing the initial commit.',
             // Stagger so a fresh frame doesn't land exactly on an existing one.
             position: { x: 80 + (frames % 5) * 48, y: 80 + (frames % 5) * 48 },
             status: 'in_progress',
@@ -483,7 +863,11 @@ export class BootstrapService {
             workspaceRepository: this.deps.workspaceRepository,
             idGenerator: this.deps.idGenerator,
             clock: this.deps.clock,
-        }, workspaceId, block);
+        }, workspaceId, block, 
+        // The repo ids stay unset until the run delivers (see the doc comment): a service
+        // pinned to a repo it has not written to yet would dispatch tasks into an empty
+        // directory. `directory` is carried now because it is what the frame IS.
+        monorepo ? { directory: monorepo.directory } : undefined);
         await this.deps.blockRepository.insert(workspaceId, block, serviceId);
         return block;
     }
@@ -510,9 +894,9 @@ export class BootstrapService {
         };
     }
     /** Best-effort: reclaim a job's per-run container (never throws). */
-    async stopContainer(workspaceId, jobId) {
+    async stopContainer(workspaceId, jobId, containerJobId) {
         try {
-            await this.deps.repoBootstrapper?.stopBootstrap({ workspaceId, jobId });
+            await this.deps.repoBootstrapper?.stopBootstrap({ workspaceId, jobId, containerJobId });
         }
         catch {
             // The container may already be gone (the common case for an eviction); the