@cat-factory/executor-harness 1.34.12 → 1.37.0

package/dist/agent.js

@@ -603,11 +603,11 @@ async function runCodingMode(job, opts) {
     // commit + push (no PR). Keyed off job DATA (`mergeBase`), not the agent kind.
     if (job.mergeBase)
         return runConflictResolution(job, opts);
-    // Multi-repo coding (service-connections phase 3): clone every connected peer repo as a
-    // sibling, run the agent once across all of them, and open one PR per changed repo. Keyed
-    // off job DATA (`peerRepos`), not the agent kind — the implementer sets it when the task
-    // has involved services in distinct repos.
-    const result = job.peerRepos?.length
+    // Multi-repo coding: clone every additional repo as a sibling and run the agent once across
+    // all of them. Keyed off job DATA, not the agent kind — set for the implementer's writable
+    // peer repos (service-connections phase 3, `peerRepos`) OR the doc-writer's READ-ONLY
+    // reference repos (`referenceRepos`, cloned but never pushed).
+    const result = job.peerRepos?.length || job.referenceRepos?.length
         ? await runMultiRepoCoding(job, opts)
         : await runSingleRepoCoding(job, opts);
     // Structured coding kind (repro-test): fold the final reply's JSON onto `custom` so the

package/dist/coding-agent.js

@@ -326,6 +326,7 @@ export async function runMultiRepoCoding(job, opts = {}) {
     const { signal } = opts;
     const logger = (opts.log ?? log).child({ kind: 'multi-repo', jobId: job.jobId });
     const peers = job.peerRepos ?? [];
+    const references = job.referenceRepos ?? [];
     const primaryWorkBranch = job.pushBranch ?? job.newBranch ?? job.branch;
     // Assign the sibling directory per repo via the shared deterministic allocator (`owner__name`,
     // matching the backend prompt's `siblingCheckoutDir`), shared with the read-only explore fan-out.
@@ -358,6 +359,21 @@ export async function runMultiRepoCoding(job, opts = {}) {
             baseSha: '',
             resumed: false,
         })),
+        // Read-only reference repos (doc-writer): cloned as siblings the agent reads but never writes.
+        // `workBranch` is set to the base only to satisfy the type — a read-only leg never branches or
+        // pushes (guarded by `readOnly` in both the clone and push phases below).
+        ...references.map((reference) => ({
+            repo: reference.repo,
+            dirName: claimDir(reference.repo),
+            dir: '',
+            cloneBranch: reference.repo.baseBranch,
+            workBranch: reference.repo.baseBranch,
+            ghToken: reference.ghToken ?? job.ghToken,
+            primary: false,
+            readOnly: true,
+            baseSha: '',
+            resumed: false,
+        })),
     ];
     return withWorkspace('multi', async (root) => {
         // Clone phase: every repo into its sibling dir under the workspace root. Resume an
@@ -366,6 +382,23 @@ export async function runMultiRepoCoding(job, opts = {}) {
         for (const leg of legs) {
             const dir = join(root, leg.dirName);
             await mkdir(dir, { recursive: true });
+            // A read-only reference leg: clone its base branch for the agent to read, and stop there —
+            // no work branch, no resume, no base-refresh. It is skipped in the push phase, so it can
+            // never be written to. (Kept in the loop so it lands in the same workspace root as siblings.)
+            if (leg.readOnly) {
+                logger.info('multi-repo: cloning read-only reference', {
+                    repo: leg.dirName,
+                    cloneBranch: leg.cloneBranch,
+                });
+                await cloneRepo({
+                    repo: { ...leg.repo, baseBranch: leg.cloneBranch },
+                    ghToken: leg.ghToken,
+                    dir,
+                    signal,
+                });
+                leg.dir = dir;
+                continue;
+            }
             leg.resumed = await remoteBranchExists(leg.repo.cloneUrl, leg.workBranch, leg.ghToken, signal);
             if (leg.resumed) {
                 logger.info('multi-repo: resuming existing branch', {
@@ -439,6 +472,10 @@ export async function runMultiRepoCoding(job, opts = {}) {
         let primaryPrUrl;
         const peerPullRequests = [];
         for (const leg of legs) {
+            // A read-only reference leg is never committed or pushed — the third layer of the read-only
+            // guarantee (the spec carries no branch/PR, and the clone phase gave it no work branch).
+            if (leg.readOnly)
+                continue;
             await commitTrackedEdits(leg.dir, job.commitMessage ?? leg.pr?.title ?? 'Agent changes', signal);
             const advanced = await branchHasCommitsSince(leg.dir, leg.baseSha, signal);
             let hasWork = advanced || leg.resumed;

package/dist/inline.js

@@ -0,0 +1,58 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runSubscriptionHarness } from './agent-runner.js';
+// The `inline` job handler: one-shot LLM completion through a subscription harness CLI
+// (Claude Code / Codex) with NO checkout. It is the container analogue of the local
+// host-CLI inline runner (runtimes/local `harnessInline.ts`) — it exists so the inline
+// LLM steps (requirements reviewer, brainstorm, task-estimator, inline document kinds) can
+// run on a subscription model even when the host has no `claude`/`codex` binary (and in
+// mothership mode without touching the host), at warm-pool latency. It reuses
+// `runSubscriptionHarness`'s credential-env setup verbatim (the single site that turns a
+// leased subscription token into `CLAUDE_CODE_OAUTH_TOKEN` / `ANTHROPIC_*` / a Codex
+// `auth.json`), so the container and coding paths can never disagree on how a credential
+// is injected.
+/**
+ * Map the harness CLI's terminal stop reason (lifted onto the last call metric) to the
+ * inline `finishReason` the reviewer keys off. Only Claude Code reports it (`max_tokens` on
+ * a `--output-format stream-json` result); Codex's thinner stream exposes none, so it reads
+ * as `stop` — the same one-shot limitation the host-CLI runner has.
+ */
+function deriveFinishReason(calls) {
+    const last = calls?.[calls.length - 1];
+    const reason = last?.finishReason?.toLowerCase() ?? '';
+    return reason === 'max_tokens' || reason === 'length' ? 'length' : 'stop';
+}
+/**
+ * Run one inline completion in a throwaway temp cwd and return the reply text + lifted
+ * usage/telemetry. The CLI clones/pushes nothing — the empty cwd only gives it a working
+ * directory. The job's watchdog (inactivity + max-duration, see {@link JobRegistry}) bounds
+ * it through `opts.signal`; `opts.onActivity` keeps the inactivity timer alive while the CLI
+ * streams. The temp cwd is always removed.
+ */
+export async function handleInline(job, opts) {
+    opts.onPhase?.('agent');
+    const cwd = await mkdtemp(join(tmpdir(), 'cf-inline-'));
+    try {
+        const outcome = await runSubscriptionHarness(job.harness, {
+            cwd,
+            model: job.model,
+            systemPrompt: job.systemPrompt,
+            userPrompt: job.userPrompt,
+            ...(job.subscriptionToken ? { subscriptionToken: job.subscriptionToken } : {}),
+            ...(job.subscriptionBaseUrl ? { subscriptionBaseUrl: job.subscriptionBaseUrl } : {}),
+            ...(job.ambientAuth ? { ambientAuth: true } : {}),
+            ...(opts.signal ? { signal: opts.signal } : {}),
+            ...(opts.onActivity ? { onActivity: opts.onActivity } : {}),
+        });
+        return {
+            text: outcome.summary,
+            finishReason: deriveFinishReason(outcome.callMetrics),
+            ...(outcome.usage ? { usage: outcome.usage } : {}),
+            ...(outcome.callMetrics ? { callMetrics: outcome.callMetrics } : {}),
+        };
+    }
+    finally {
+        await rm(cwd, { recursive: true, force: true }).catch(() => { });
+    }
+}

package/dist/job.js

@@ -150,6 +150,30 @@ function parsePeerRepos(value) {
         return spec;
     });
 }
+/**
+ * Parse the optional read-only reference-repo list (document-authoring runs). Each entry carries
+ * a full {@link RepoSpec} (validated + sanitised like the primary) and an optional per-repo token.
+ * Any branch/PR fields on the wire are IGNORED — a reference repo is never pushed, so the parsed
+ * shape has none to carry. A malformed list throws; an absent one yields `[]`.
+ */
+function parseReferenceRepos(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error("Invalid job: 'referenceRepos' must be an array");
+    return value.map((entry, i) => {
+        if (typeof entry !== 'object' || entry === null) {
+            throw new Error(`Invalid job: 'referenceRepos[${i}]' must be an object`);
+        }
+        const e = entry;
+        const spec = {
+            repo: parseRepoSpec((e.repo ?? {})),
+        };
+        if (typeof e.ghToken === 'string' && e.ghToken)
+            spec.ghToken = e.ghToken;
+        return spec;
+    });
+}
 /** Parse the optional `repo.provider` discriminator (defaults to undefined ⇒ host inference). */
 function parseVcsProvider(value) {
     if (value === undefined || value === null)
@@ -431,6 +455,35 @@ function parseFrontendInfraSpec(o) {
         ...(wiremockPort !== undefined ? { wiremockPort } : {}),
     };
 }
+/**
+ * Validate + narrow an untrusted body into an {@link InlineJob}. The harness MUST be a
+ * subscription harness (`claude-code` / `codex`) — the inline path never runs Pi (that goes
+ * through the LLM proxy inline, not a container CLI). Reuses {@link parseHarnessAuth}, so a
+ * non-ambient job requires `subscriptionToken`.
+ */
+export function parseInlineJob(input) {
+    if (typeof input !== 'object' || input === null) {
+        throw new Error('Invalid job: body must be an object');
+    }
+    const o = input;
+    // Validate the harness FIRST (before parseHarnessAuth, whose `pi` branch demands a proxy
+    // base URL): the inline path only ever runs a subscription CLI, so a Pi/absent harness is a
+    // clear inline-specific rejection rather than a confusing "proxyBaseUrl required".
+    if (o.harness !== 'claude-code' && o.harness !== 'codex') {
+        throw new Error("Invalid inline job: 'harness' must be 'claude-code' or 'codex'");
+    }
+    const auth = parseHarnessAuth(o);
+    const maxOutputTokens = posInt(o.maxOutputTokens);
+    return {
+        jobId: str(o.jobId, 'jobId'),
+        model: str(o.model, 'model'),
+        // The system prompt is optional (an empty role is valid); the user prompt is required.
+        systemPrompt: typeof o.systemPrompt === 'string' ? o.systemPrompt : '',
+        userPrompt: str(o.userPrompt, 'userPrompt'),
+        ...auth,
+        ...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}),
+    };
+}
 /** Validate + narrow an untrusted body into an {@link AgentJob}, throwing on bad input. */
 export function parseAgentJob(input) {
     if (typeof input !== 'object' || input === null) {
@@ -479,6 +532,7 @@ export function parseAgentJob(input) {
         : undefined;
     const infra = parseAgentInfraSpec(o.infra);
     const peerRepos = parsePeerRepos(o.peerRepos);
+    const referenceRepos = parseReferenceRepos(o.referenceRepos);
     const bootstrap = parseAgentBootstrapSpec(o.bootstrap);
     const contextFiles = parseContextFiles(o.contextFiles);
     const packageRegistries = parsePackageRegistries(o.packageRegistries);
@@ -510,6 +564,7 @@ export function parseAgentJob(input) {
             : {}),
         ...(pr ? { pr } : {}),
         ...(peerRepos.length ? { peerRepos } : {}),
+        ...(referenceRepos.length ? { referenceRepos } : {}),
         ...(o.noChangesIsError === false ? { noChangesIsError: false } : {}),
         ...(o.persistentCheckout === true ? { persistentCheckout: true } : {}),
         ...(o.streamFollowUps === true ? { streamFollowUps: true } : {}),
@@ -528,5 +583,11 @@ export function parseAgentJob(input) {
     for (const [i, peer] of (job.peerRepos ?? []).entries()) {
         assertAllowedHost(peer.repo.cloneUrl, `peerRepos[${i}].repo.cloneUrl`);
     }
+    // Each reference repo's clone URL receives the installation/PAT token on clone (read-only,
+    // never pushed), so it must be an allowed host too — a body-supplied reference pointing at an
+    // attacker host would exfiltrate the token exactly like a rogue peer clone URL.
+    for (const [i, ref] of (job.referenceRepos ?? []).entries()) {
+        assertAllowedHost(ref.repo.cloneUrl, `referenceRepos[${i}].repo.cloneUrl`);
+    }
     return job;
 }

package/dist/server.js

@@ -1,7 +1,8 @@
 import { timingSafeEqual } from 'node:crypto';
 import { createServer } from 'node:http';
-import { parseAgentJob } from './job.js';
+import { parseAgentJob, parseInlineJob } from './job.js';
 import { handleAgent } from './agent.js';
+import { handleInline } from './inline.js';
 import { redactSecrets } from './git.js';
 import { JobRegistry, loadRunnerLimits } from './runner.js';
 import { log } from './logger.js';
@@ -67,6 +68,13 @@ const KINDS = {
         repo: `${job.repo.owner}/${job.repo.name}`,
         branch: job.branch,
     })),
+    // The one-shot, no-checkout inline completion (requirements reviewer / brainstorm /
+    // task-estimator / inline document kinds) on a leased subscription credential — the
+    // container analogue of the local host-CLI inline runner. See inline.ts.
+    inline: defineKind(parseInlineJob, handleInline, (job) => ({
+        harness: job.harness,
+        model: job.model,
+    })),
 };
 async function readBody(req) {
     const chunks = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.34.12",
+  "version": "1.37.0",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -26,8 +26,8 @@
     "hono": "^4.12.27",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9",
-    "@cat-factory/server": "0.85.0",
-    "@cat-factory/spend": "0.10.102"
+    "@cat-factory/server": "0.99.4",
+    "@cat-factory/spend": "0.11.13"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent.ts

@@ -739,13 +739,14 @@ async function runCodingMode(job: AgentJob, opts: RunOptions): Promise<AgentResu
   // clone full, merge the base in to surface the conflicts, then complete the merge
   // commit + push (no PR). Keyed off job DATA (`mergeBase`), not the agent kind.
   if (job.mergeBase) return runConflictResolution(job, opts)
-  // Multi-repo coding (service-connections phase 3): clone every connected peer repo as a
-  // sibling, run the agent once across all of them, and open one PR per changed repo. Keyed
-  // off job DATA (`peerRepos`), not the agent kind — the implementer sets it when the task
-  // has involved services in distinct repos.
-  const result = job.peerRepos?.length
-    ? await runMultiRepoCoding(job, opts)
-    : await runSingleRepoCoding(job, opts)
+  // Multi-repo coding: clone every additional repo as a sibling and run the agent once across
+  // all of them. Keyed off job DATA, not the agent kind — set for the implementer's writable
+  // peer repos (service-connections phase 3, `peerRepos`) OR the doc-writer's READ-ONLY
+  // reference repos (`referenceRepos`, cloned but never pushed).
+  const result =
+    job.peerRepos?.length || job.referenceRepos?.length
+      ? await runMultiRepoCoding(job, opts)
+      : await runSingleRepoCoding(job, opts)
 
   // Structured coding kind (repro-test): fold the final reply's JSON onto `custom` so the
   // backend post-completion resolver records the outcome. Skipped on a failed run (its `error`

package/src/coding-agent.ts

@@ -1,6 +1,13 @@
 import { mkdir } from 'node:fs/promises'
 import { join } from 'node:path'
-import type { AgentJob, AgentResult, HarnessAuthFields, PeerRepoSpec, RepoSpec } from './job.js'
+import type {
+  AgentJob,
+  AgentResult,
+  HarnessAuthFields,
+  PeerRepoSpec,
+  ReferenceRepoSpec,
+  RepoSpec,
+} from './job.js'
 import {
   branchAheadOfBase,
   branchHasCommitsSince,
@@ -435,6 +442,12 @@ interface RepoLeg {
   pr?: { title: string; body: string }
   frameId?: string
   primary: boolean
+  /**
+   * A READ-ONLY reference checkout (doc-writer's `referenceRepos`): cloned at its base branch for
+   * the agent to read, but NEVER given a work branch, committed, or pushed. Skipped entirely in the
+   * push phase, so it is structurally impossible for the run to write to it. Absent ⇒ a writable leg.
+   */
+  readOnly?: boolean
   /** The branch tip before the run — work iff the branch advances past it. */
   baseSha: string
   /** Whether an existing remote work branch was resumed (already carries prior work). */
@@ -461,6 +474,7 @@ export async function runMultiRepoCoding(
   const { signal } = opts
   const logger = (opts.log ?? log).child({ kind: 'multi-repo', jobId: job.jobId })
   const peers: PeerRepoSpec[] = job.peerRepos ?? []
+  const references: ReferenceRepoSpec[] = job.referenceRepos ?? []
   const primaryWorkBranch = job.pushBranch ?? job.newBranch ?? job.branch
 
   // Assign the sibling directory per repo via the shared deterministic allocator (`owner__name`,
@@ -496,6 +510,23 @@ export async function runMultiRepoCoding(
         resumed: false,
       }),
     ),
+    // Read-only reference repos (doc-writer): cloned as siblings the agent reads but never writes.
+    // `workBranch` is set to the base only to satisfy the type — a read-only leg never branches or
+    // pushes (guarded by `readOnly` in both the clone and push phases below).
+    ...references.map(
+      (reference): RepoLeg => ({
+        repo: reference.repo,
+        dirName: claimDir(reference.repo),
+        dir: '',
+        cloneBranch: reference.repo.baseBranch,
+        workBranch: reference.repo.baseBranch,
+        ghToken: reference.ghToken ?? job.ghToken,
+        primary: false,
+        readOnly: true,
+        baseSha: '',
+        resumed: false,
+      }),
+    ),
   ]
 
   return withWorkspace('multi', async (root) => {
@@ -505,6 +536,23 @@ export async function runMultiRepoCoding(
     for (const leg of legs) {
       const dir = join(root, leg.dirName)
       await mkdir(dir, { recursive: true })
+      // A read-only reference leg: clone its base branch for the agent to read, and stop there —
+      // no work branch, no resume, no base-refresh. It is skipped in the push phase, so it can
+      // never be written to. (Kept in the loop so it lands in the same workspace root as siblings.)
+      if (leg.readOnly) {
+        logger.info('multi-repo: cloning read-only reference', {
+          repo: leg.dirName,
+          cloneBranch: leg.cloneBranch,
+        })
+        await cloneRepo({
+          repo: { ...leg.repo, baseBranch: leg.cloneBranch },
+          ghToken: leg.ghToken,
+          dir,
+          signal,
+        })
+        leg.dir = dir
+        continue
+      }
       leg.resumed = await remoteBranchExists(leg.repo.cloneUrl, leg.workBranch, leg.ghToken, signal)
       if (leg.resumed) {
         logger.info('multi-repo: resuming existing branch', {
@@ -587,6 +635,9 @@ export async function runMultiRepoCoding(
     let primaryPrUrl: string | undefined
     const peerPullRequests: NonNullable<AgentResult['peerPullRequests']> = []
     for (const leg of legs) {
+      // A read-only reference leg is never committed or pushed — the third layer of the read-only
+      // guarantee (the spec carries no branch/PR, and the clone phase gave it no work branch).
+      if (leg.readOnly) continue
       await commitTrackedEdits(
         leg.dir,
         job.commitMessage ?? leg.pr?.title ?? 'Agent changes',

package/src/inline.ts

@@ -0,0 +1,63 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { runSubscriptionHarness, type SubscriptionHarness } from './agent-runner.js'
+import type { HarnessCallMetric } from './pi.js'
+import type { InlineJob, InlineResult } from './job.js'
+import type { RunOptions } from './runner.js'
+
+// The `inline` job handler: one-shot LLM completion through a subscription harness CLI
+// (Claude Code / Codex) with NO checkout. It is the container analogue of the local
+// host-CLI inline runner (runtimes/local `harnessInline.ts`) — it exists so the inline
+// LLM steps (requirements reviewer, brainstorm, task-estimator, inline document kinds) can
+// run on a subscription model even when the host has no `claude`/`codex` binary (and in
+// mothership mode without touching the host), at warm-pool latency. It reuses
+// `runSubscriptionHarness`'s credential-env setup verbatim (the single site that turns a
+// leased subscription token into `CLAUDE_CODE_OAUTH_TOKEN` / `ANTHROPIC_*` / a Codex
+// `auth.json`), so the container and coding paths can never disagree on how a credential
+// is injected.
+
+/**
+ * Map the harness CLI's terminal stop reason (lifted onto the last call metric) to the
+ * inline `finishReason` the reviewer keys off. Only Claude Code reports it (`max_tokens` on
+ * a `--output-format stream-json` result); Codex's thinner stream exposes none, so it reads
+ * as `stop` — the same one-shot limitation the host-CLI runner has.
+ */
+function deriveFinishReason(calls: HarnessCallMetric[] | undefined): 'stop' | 'length' {
+  const last = calls?.[calls.length - 1]
+  const reason = last?.finishReason?.toLowerCase() ?? ''
+  return reason === 'max_tokens' || reason === 'length' ? 'length' : 'stop'
+}
+
+/**
+ * Run one inline completion in a throwaway temp cwd and return the reply text + lifted
+ * usage/telemetry. The CLI clones/pushes nothing — the empty cwd only gives it a working
+ * directory. The job's watchdog (inactivity + max-duration, see {@link JobRegistry}) bounds
+ * it through `opts.signal`; `opts.onActivity` keeps the inactivity timer alive while the CLI
+ * streams. The temp cwd is always removed.
+ */
+export async function handleInline(job: InlineJob, opts: RunOptions): Promise<InlineResult> {
+  opts.onPhase?.('agent')
+  const cwd = await mkdtemp(join(tmpdir(), 'cf-inline-'))
+  try {
+    const outcome = await runSubscriptionHarness(job.harness as SubscriptionHarness, {
+      cwd,
+      model: job.model,
+      systemPrompt: job.systemPrompt,
+      userPrompt: job.userPrompt,
+      ...(job.subscriptionToken ? { subscriptionToken: job.subscriptionToken } : {}),
+      ...(job.subscriptionBaseUrl ? { subscriptionBaseUrl: job.subscriptionBaseUrl } : {}),
+      ...(job.ambientAuth ? { ambientAuth: true } : {}),
+      ...(opts.signal ? { signal: opts.signal } : {}),
+      ...(opts.onActivity ? { onActivity: opts.onActivity } : {}),
+    })
+    return {
+      text: outcome.summary,
+      finishReason: deriveFinishReason(outcome.callMetrics),
+      ...(outcome.usage ? { usage: outcome.usage } : {}),
+      ...(outcome.callMetrics ? { callMetrics: outcome.callMetrics } : {}),
+    }
+  } finally {
+    await rm(cwd, { recursive: true, force: true }).catch(() => {})
+  }
+}

package/src/job.ts

@@ -84,6 +84,21 @@ export interface PeerRepoSpec {
   ghToken?: string
 }
 
+/**
+ * A repository checked out READ-ONLY as a sibling alongside the primary during a
+ * document-authoring coding run — the doc-writer reads it (to reuse existing solutions as a
+ * reference) but the harness never creates a branch, commits, or opens a PR for it. Deliberately
+ * carries NO branch/PR fields (unlike {@link PeerRepoSpec}), so it is structurally impossible to
+ * push: the read-only guarantee is enforced by the shape itself, by cloning at the repo's own
+ * base branch with no work branch, and by skipping the leg in the push phase. The clone URL is
+ * host-allowlisted exactly like the primary `repo.cloneUrl`.
+ */
+export interface ReferenceRepoSpec {
+  repo: RepoSpec
+  /** Per-repo GitHub token; defaults to the job's `ghToken` (one installation per workspace today). */
+  ghToken?: string
+}
+
 function str(value: unknown, path: string): string {
   if (typeof value !== 'string' || value.length === 0) {
     throw new Error(`Invalid job: '${path}' must be a non-empty string`)
@@ -234,6 +249,28 @@ function parsePeerRepos(value: unknown): PeerRepoSpec[] {
   })
 }
 
+/**
+ * Parse the optional read-only reference-repo list (document-authoring runs). Each entry carries
+ * a full {@link RepoSpec} (validated + sanitised like the primary) and an optional per-repo token.
+ * Any branch/PR fields on the wire are IGNORED — a reference repo is never pushed, so the parsed
+ * shape has none to carry. A malformed list throws; an absent one yields `[]`.
+ */
+function parseReferenceRepos(value: unknown): ReferenceRepoSpec[] {
+  if (value === undefined || value === null) return []
+  if (!Array.isArray(value)) throw new Error("Invalid job: 'referenceRepos' must be an array")
+  return value.map((entry, i) => {
+    if (typeof entry !== 'object' || entry === null) {
+      throw new Error(`Invalid job: 'referenceRepos[${i}]' must be an object`)
+    }
+    const e = entry as Record<string, unknown>
+    const spec: ReferenceRepoSpec = {
+      repo: parseRepoSpec((e.repo ?? {}) as Record<string, unknown>),
+    }
+    if (typeof e.ghToken === 'string' && e.ghToken) spec.ghToken = e.ghToken
+    return spec
+  })
+}
+
 /** Parse the optional `repo.provider` discriminator (defaults to undefined ⇒ host inference). */
 function parseVcsProvider(value: unknown): 'github' | 'gitlab' | undefined {
   if (value === undefined || value === null) return undefined
@@ -591,6 +628,14 @@ export interface AgentJob extends HarnessAuthFields {
    * peer repo it actually changed — in addition to the primary. Absent ⇒ single-repo run.
    */
   peerRepos?: PeerRepoSpec[]
+  /**
+   * Coding mode (doc-writer): repositories to clone READ-ONLY as SIBLINGS for the agent to
+   * reference while it drafts the document. When present the agent works at the workspace ROOT
+   * (all checkouts are siblings under it); the harness clones each reference at its own base
+   * branch and NEVER creates a branch, commits, or opens a PR for it. Only the primary is
+   * pushed. Absent ⇒ single-repo run. Independent of {@link peerRepos} (those are writable).
+   */
+  referenceRepos?: ReferenceRepoSpec[]
   /**
    * Coding mode: whether a no-op run (nothing changed) is a failure. The implementer
    * fails on a no-op; the in-place fixers (ci-fix / fix-tests) treat it as a non-fatal
@@ -878,6 +923,73 @@ function parseFrontendInfraSpec(o: Record<string, unknown>): FrontendInfraSpec {
   }
 }
 
+// ---- Inline job (POST /jobs, kind=inline) --------------------------------
+//
+// A ONE-SHOT, no-checkout LLM completion run through a subscription harness CLI
+// (Claude Code / Codex) on a leased subscription credential — the container analogue of
+// the local host-CLI inline runner. It exists so a deployment that can't run the ambient
+// CLI on the host (no `claude`/`codex` binary, or mothership mode) can still serve the
+// inline LLM steps (requirements reviewer, brainstorm, task-estimator, inline document
+// kinds) on a subscription model, at warm-pool latency. It clones NOTHING and pushes
+// NOTHING: the CLI runs in a throwaway temp cwd and only the completion text + token usage
+// come back. Auth is the SAME `HarnessAuthFields` the coding path uses (subscriptionToken +
+// optional subscriptionBaseUrl, or ambientAuth), so the credential-env setup is shared.
+
+/** The one-shot inline completion job. `harness` must be a subscription harness. */
+export interface InlineJob extends HarnessAuthFields {
+  jobId: string
+  /** Real vendor model id, e.g. `claude-opus-4-8` / `gpt-5.5-codex`. */
+  model: string
+  /** Composed role + best-practice fragments (Claude: `--append-system-prompt`; Codex: prepended). */
+  systemPrompt: string
+  /** The concrete task/user prompt fed to the CLI over stdin. */
+  userPrompt: string
+  /** Advisory output cap, forwarded for parity; the one-shot CLIs don't all honour it. */
+  maxOutputTokens?: number
+}
+
+/** The inline completion result: the reply text plus lifted token usage / per-call telemetry. */
+export interface InlineResult {
+  text: string
+  /** `length` when the model hit its output cap (the reviewer rejects a truncated doc). */
+  finishReason?: 'stop' | 'length'
+  usage?: { inputTokens: number; outputTokens: number }
+  /** Per-model-call telemetry lifted from the CLI stream (recorded into `llm_call_metrics`). */
+  callMetrics?: HarnessCallMetric[]
+  /** A structured failure marks a job-level failure even on a clean HTTP exit (see JobResultBase). */
+  error?: string
+}
+
+/**
+ * Validate + narrow an untrusted body into an {@link InlineJob}. The harness MUST be a
+ * subscription harness (`claude-code` / `codex`) — the inline path never runs Pi (that goes
+ * through the LLM proxy inline, not a container CLI). Reuses {@link parseHarnessAuth}, so a
+ * non-ambient job requires `subscriptionToken`.
+ */
+export function parseInlineJob(input: unknown): InlineJob {
+  if (typeof input !== 'object' || input === null) {
+    throw new Error('Invalid job: body must be an object')
+  }
+  const o = input as Record<string, unknown>
+  // Validate the harness FIRST (before parseHarnessAuth, whose `pi` branch demands a proxy
+  // base URL): the inline path only ever runs a subscription CLI, so a Pi/absent harness is a
+  // clear inline-specific rejection rather than a confusing "proxyBaseUrl required".
+  if (o.harness !== 'claude-code' && o.harness !== 'codex') {
+    throw new Error("Invalid inline job: 'harness' must be 'claude-code' or 'codex'")
+  }
+  const auth = parseHarnessAuth(o)
+  const maxOutputTokens = posInt(o.maxOutputTokens)
+  return {
+    jobId: str(o.jobId, 'jobId'),
+    model: str(o.model, 'model'),
+    // The system prompt is optional (an empty role is valid); the user prompt is required.
+    systemPrompt: typeof o.systemPrompt === 'string' ? o.systemPrompt : '',
+    userPrompt: str(o.userPrompt, 'userPrompt'),
+    ...auth,
+    ...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}),
+  }
+}
+
 /** Validate + narrow an untrusted body into an {@link AgentJob}, throwing on bad input. */
 export function parseAgentJob(input: unknown): AgentJob {
   if (typeof input !== 'object' || input === null) {
@@ -926,6 +1038,7 @@ export function parseAgentJob(input: unknown): AgentJob {
       : undefined
   const infra = parseAgentInfraSpec(o.infra)
   const peerRepos = parsePeerRepos(o.peerRepos)
+  const referenceRepos = parseReferenceRepos(o.referenceRepos)
   const bootstrap = parseAgentBootstrapSpec(o.bootstrap)
   const contextFiles = parseContextFiles(o.contextFiles)
   const packageRegistries = parsePackageRegistries(o.packageRegistries)
@@ -957,6 +1070,7 @@ export function parseAgentJob(input: unknown): AgentJob {
       : {}),
     ...(pr ? { pr } : {}),
     ...(peerRepos.length ? { peerRepos } : {}),
+    ...(referenceRepos.length ? { referenceRepos } : {}),
     ...(o.noChangesIsError === false ? { noChangesIsError: false } : {}),
     ...(o.persistentCheckout === true ? { persistentCheckout: true } : {}),
     ...(o.streamFollowUps === true ? { streamFollowUps: true } : {}),
@@ -973,5 +1087,11 @@ export function parseAgentJob(input: unknown): AgentJob {
   for (const [i, peer] of (job.peerRepos ?? []).entries()) {
     assertAllowedHost(peer.repo.cloneUrl, `peerRepos[${i}].repo.cloneUrl`)
   }
+  // Each reference repo's clone URL receives the installation/PAT token on clone (read-only,
+  // never pushed), so it must be an allowed host too — a body-supplied reference pointing at an
+  // attacker host would exfiltrate the token exactly like a rogue peer clone URL.
+  for (const [i, ref] of (job.referenceRepos ?? []).entries()) {
+    assertAllowedHost(ref.repo.cloneUrl, `referenceRepos[${i}].repo.cloneUrl`)
+  }
   return job
 }

package/src/server.ts

@@ -1,7 +1,8 @@
 import { timingSafeEqual } from 'node:crypto'
 import { createServer, type IncomingMessage, type ServerResponse } from 'node:http'
-import { parseAgentJob } from './job.js'
+import { parseAgentJob, parseInlineJob } from './job.js'
 import { handleAgent } from './agent.js'
+import { handleInline } from './inline.js'
 import { redactSecrets } from './git.js'
 import { JobRegistry, loadRunnerLimits, type JobResultBase, type RunOptions } from './runner.js'
 import { log } from './logger.js'
@@ -84,6 +85,13 @@ const KINDS: Record<string, KindEntry> = {
     repo: `${job.repo.owner}/${job.repo.name}`,
     branch: job.branch,
   })),
+  // The one-shot, no-checkout inline completion (requirements reviewer / brainstorm /
+  // task-estimator / inline document kinds) on a leased subscription credential — the
+  // container analogue of the local host-CLI inline runner. See inline.ts.
+  inline: defineKind(parseInlineJob, handleInline, (job) => ({
+    harness: job.harness,
+    model: job.model,
+  })),
 }
 
 async function readBody(req: IncomingMessage): Promise<string> {