@outerlayer/cli 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @outerlayer/cli
 
+## 0.18.0
+
+### Minor Changes
+
+- 2ef9133: Add `outerlayer claude`, which starts Claude Code with the repository's control plane attached. A governed build reads its control plane from a directory outside the checkout, so nothing from it is written into the checkout.
+- e92982d: A session now takes its control plane from the one the factory stores, chosen in the factory's Settings with Use as control plane in the Repositories list. Nothing reads a `governs` list in a control plane's config any more, and `doctor` reports a list left there as unused. A gateway older than 0.17.0 does not store the answer, and the CLI says so instead of guessing.
+
+  A validator or policy `when` can name `repositories`, so a check applies only to pull requests in those repositories.
+
+  A session that could not reach the gateway, or reached a gateway too old to answer, no longer reads the retry guess it wrote as a confirmed answer on the next start. A build that cannot write the staged control-plane files now says so, and no longer reports that a credential cannot read the control plane.
+
+- 2cb58e8: A container or microVM build now runs on the devcontainer of the repository that governs it. For a governed repository that is the control plane's `.devcontainer/devcontainer.json` (or `.devcontainer.json`), read at the commit the build's instructions come from. A governed repository's own devcontainer is not read, and the build log says so. A repository that governs itself builds from its own devcontainer, as before. `outerlayer runner image --repository <name>` builds the same image a build of that repository uses.
+
+  Before upgrading a runner host, copy the devcontainer your builds rely on into the control plane. A control plane with no devcontainer gives its builds the runner's default image. A factory whose only repository is its own control plane needs no move.
+
+  In a build with more than one repository, every repository is at `/build/work/repos/<owner>/<repo>`, the primary included. The primary is also at `/build/work/checkout`. The control plane devcontainer's setup commands run once, in the control plane's checkout, so they can name each repository by its fixed path. Host checks check out every repository at the same paths, each at the branch the build pushed there or else at its default branch.
+
+- 07bb510: A `where: host` check can declare `run.judge.brief` instead of `run.command`. After a build ends well, the runner stops everything the build left running, checks that the image's Claude Code is unchanged, and runs a read-only Claude Code session with that brief. It records the verdict under the check's name with the host's own key and links the judge's report.
+
+  The starter `acceptance-criteria` check now uses this form, and the starter `/build` skill no longer records its own `acceptance-criteria` pass. Run `outerlayer doctor` to see an unedited copy of the old file as outdated, and `outerlayer init --update` to replace it.
+
+- d776d34: `outerlayer spec` files and edits specs through OuterLayer, with no tracker tool of your own. `spec target` says where a spec would be filed. `spec search <query>` finds open and closed issues that match. `spec file --title <text> --body-file <path>` creates the issue and prints its key, URL and the `work build` command for it. `spec edit <key> --body-file <path>` replaces an issue's body, and `--updated-at` refuses the edit if the issue changed since you read it.
+
+  Filing works for GitHub today. An API key needs the new `spec.insert` permission to file and `spec.update` to edit, so re-mint keys that should do either. A GitHub organization admin must also approve the OuterLayer App's Issues write permission once.
+
+### Patch Changes
+
+- 8f46b70: The starter `/build` skill reads the issue from `outerlayer work status --json`, under the new `issue` field, instead of from a tracker tool. A build on a host holds no Linear or Jira credential, so it could not read those issues before. The build saves the issue to `build-reports/issue.md` and gives every agent that file. `/outerlayer-amend` reads the issue the same way.
+
+  To pick up the new `/build`, run `outerlayer init --update`. A copy you edited is left as it is.
+
+- fe8bb20: Printed command hints now name the command the way you ran the CLI. Run it through `npx @outerlayer/cli` (or `pnpm dlx`, `yarn dlx` or `bunx`) and a hint says `npx @outerlayer/cli login`, not an `outerlayer login` that is not on your PATH. `--help` usage lines follow the same rule.
+
+  `work build --local` no longer prints a branch name. The session it hands off to works on a branch of its own, so the printed name was never used. `--json` still carries the `branch` field.
+
+  `doctor` no longer warns when Claude Code is newer than the newest version this release was tested with. It passes, and names that tested version. A Claude Code older than the tested range still warns.
+
+- 9b898aa: Session cost estimates price Claude Haiku 5.5 requests over 100,000 input tokens at Haiku 5.5's long-context rates. Token buckets now start a new input band at 100,000 tokens.
+- 5cc77dc: Builds no longer print a Node warning on the stderr of every Node process. The runner sets `NODE_USE_ENV_PROXY` so Node uses the build's proxy, and Node 22 then warns `[UNDICI-EHPA] EnvHttpProxyAgent is experimental`. A test that expects a child process's stderr to be empty failed in a build and passed on a laptop.
+
+  The runner now adds `--disable-warning=UNDICI-EHPA` to `NODE_OPTIONS` in container, microVM and process builds. It keeps the options the image, the recipe's `containerEnv` or a named host variable already set. A build run through a provision hook's `exec` is left as it was. Node before 20.11 does not know the flag and refuses to start with it.
+
+- daac363: Uploaded sessions record the input band boundaries their token buckets were grouped by. The server uses them to tell when a bucket cannot be priced at a single rate, and prices that model from its individual requests instead.
+- 7a16e3f: `outerlayer work status`, `work remove`, `work claim`, `work renew` and `work release` take a Linear or Jira key in `--issue`, such as `--issue ENG-142`. Pass `--tracker linear` or `--tracker jira` when both trackers hold the key. Before, `--issue` took only a GitHub issue number, so a Linear or Jira item could be named only with `--item`.
+
+  A runner's `repos.include` and `repos.exclude` now match a Linear or Jira item by the repository it was added with (`work build --repo`), instead of skipping it. A runner using `builtin:process`, or its own provision hook, now clones the repository the claim chose, so it can build an item that was added without a repository.
+
 ## 0.17.0
 
 ### Minor Changes

package/README.md

@@ -95,6 +95,12 @@ content:
   list and read items, and `work.claim` to claim, renew or release — `work.claim`
   is not granted to a dashboard role by default, since a claim is a host's
   lease, not a person's.
+- **`outerlayer spec target`, `search`, `file` and `edit`** each make one
+  request to your gateway (`GET /v1/specs/target`, `GET /v1/specs/search`,
+  `POST /v1/specs`, `PATCH /v1/specs/{key}`). `search` sends your query, and
+  `file` and `edit` send the title and the Markdown body you give them.
+  Your gateway files the issue in your tracker; the CLI never holds a tracker
+  credential.
 - **`outerlayer runner start`** lists, claims, renews and releases work
   items the same way `work claim`/`renew`/`release` do, on the schedule its
   config sets — it sends nothing about the job it runs beyond that; the
@@ -116,6 +122,15 @@ content:
   command in a new container, and sends one `POST /v1/emitted-results` for
   each: the check's name, pass or fail, and for a fail the exit status and the
   last line of its output, scrubbed.
+  A `where: host` check that declares a `judge` runs after a successful
+  build instead of a command. The runner reads the item's recorded criteria
+  with `GET /v1/work-items/{id}`, fetches the build's commits and the brief
+  with the host's own git credentials, and copies out the tests that cite the
+  criteria. It starts a Claude Code agent in the build's image with the host's
+  Claude credential. The judge sees only a read-only folder of the criteria,
+  citations and diff, and it has no shell. The runner uploads the judge's
+  `report.html` as an artifact with its own key, and sends one
+  `POST /v1/emitted-results` with pass or fail and a one-line reason.
   Before each check's command runs, the runner writes a read-only folder for it
   to read: the work item, from `GET /v1/work-items/{id}` with the runner's own
   key; the branch's diff, from `git fetch` of the build's commits with the

package/dist/agent-setup-RBTEACYU.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+export { keepHandWritten, runAgentSetup } from './chunk-RAZTWYZN.js';
+import './chunk-47TTLEDX.js';
+import './chunk-YVZJ6GKF.js';
+import './chunk-F4XSVQJ4.js';
+import './chunk-ANPNT6PM.js';
+import './chunk-W5VPCONO.js';
+import './chunk-LXAY4A2G.js';
+import './chunk-T4Y6SCG3.js';
+import './chunk-ZRL6HKBY.js';
+import './chunk-52NC2FIU.js';
+import './chunk-MNTSH4CL.js';
+import './chunk-X5N6KC6V.js';
+import './chunk-N3CUDFCW.js';
+import './chunk-EABW6AJQ.js';
+import './chunk-RA3O54FC.js';
+import './chunk-M2ZWWTWZ.js';
+import './chunk-N2PXGQRL.js';
+import './chunk-BQXFBI7T.js';
+import './chunk-XCCLFVXM.js';
+import './chunk-ZJSNLVCE.js';
+import './chunk-BJ3KTMDH.js';
+import './chunk-CRB3POP4.js';
+import './chunk-VNVZDWO3.js';
+import './chunk-Z5GEFMRW.js';
+
+createRequire(import.meta.url);

package/dist/{artifact-link-cmd-2F47LT7F.js → artifact-link-cmd-AVM2EKTV.js}

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
-import { sanitizeTerminal, readEffectiveArtifactSpoolState } from './chunk-WUYTWNMA.js';
-import './chunk-J5M7BSJQ.js';
+import { sanitizeTerminal, readEffectiveArtifactSpoolState } from './chunk-MQJSXHV7.js';
+import './chunk-N3CUDFCW.js';
+import { cliInvocation } from './chunk-CRB3POP4.js';
 import { homeFromEnv } from './chunk-VNVZDWO3.js';
 import './chunk-Z5GEFMRW.js';
 
@@ -13,7 +14,7 @@ function lookupArtifactLink(artifactId, home = homeFromEnv()) {
   const entry = readEffectiveArtifactSpoolState(home).state.get(artifactId);
   if (entry === void 0) return { ok: false, reason: `no artifact ${shown} is queued or uploaded on this machine` };
   if (entry.state !== "uploaded") {
-    return { ok: false, reason: `artifact ${shown} is ${entry.state}, not uploaded yet \u2014 run \`outerlayer sync\` first` };
+    return { ok: false, reason: `artifact ${shown} is ${entry.state}, not uploaded yet \u2014 run \`${cliInvocation()} sync\` first` };
   }
   if (entry.url === void 0) {
     return { ok: false, reason: `artifact ${shown} uploaded, but the gateway returned no link for it` };

package/dist/{build-BG2YENGK.js → build-TQ6X5PYN.js}

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
-export { buildRepositoryImage } from './chunk-R7PF5OOU.js';
+export { buildRepositoryImage } from './chunk-3CWUOFV6.js';
 export { RecipeError } from './chunk-QOZKPLVJ.js';
-import './chunk-N5FOE5PS.js';
 import './chunk-CX22S5BA.js';
-import './chunk-BYT5O5RV.js';
-import './chunk-ZM2IMMYN.js';
+import './chunk-ECODQ7II.js';
+import './chunk-JBJTC3UU.js';
+import './chunk-N2PXGQRL.js';
+import './chunk-BQXFBI7T.js';
 import './chunk-Z5GEFMRW.js';
 
 createRequire(import.meta.url);

package/dist/build-info.json

@@ -1 +1 @@
-{"id":"2026-10-09T21:24:47.045Z+8773e8e","root":"/home/runner/_work/outerlayer/outerlayer","pkg":"outerlayer"}
+{"id":"2026-10-13T00:18:48.455Z+4c5e4a3","root":"/home/runner/_work/outerlayer/outerlayer","pkg":"outerlayer"}

package/dist/{builder-2D3WSOOY.js → builder-DUI2ZH2H.js}

@@ -1,13 +1,12 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
-export { MIN_BUILDX_VERSION, builderName, builderSpec, buildxState, ensureBuilder, ensureFailureCount, isOutOfMemory, proxyEnvironment, trackImageBuild } from './chunk-4NPZVMJU.js';
+export { MIN_BUILDX_VERSION, builderName, builderSpec, buildxState, ensureBuilder, ensureFailureCount, isOutOfMemory, proxyEnvironment, trackImageBuild } from './chunk-S26M3YBJ.js';
 import './chunk-7RQ73DLO.js';
-import './chunk-4Q7OMKAT.js';
 import './chunk-CX22S5BA.js';
-import './chunk-JXYVA45C.js';
-import './chunk-BYT5O5RV.js';
-import './chunk-J5M7BSJQ.js';
-import './chunk-ZM2IMMYN.js';
+import './chunk-BMYGAGBJ.js';
+import './chunk-N3CUDFCW.js';
+import './chunk-N2PXGQRL.js';
+import './chunk-BQXFBI7T.js';
 import './chunk-Z5GEFMRW.js';
 
 createRequire(import.meta.url);

package/dist/{check-5XE7XMC4.js → check-5C4YDZYV.js}

@@ -1,72 +1,75 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
-import { probeCredentials } from './chunk-WVUIRTWA.js';
-import './chunk-G5NPRL2K.js';
-import './chunk-RMWLBUCJ.js';
-import './chunk-O765JR4W.js';
-import './chunk-UGP76IZ5.js';
+import { probeCredentials } from './chunk-QQM2UJ6T.js';
 import './chunk-3JVYMD4G.js';
-import './chunk-YETTWTAY.js';
 import './chunk-I2UOAV7X.js';
-import './chunk-NNRTPG7X.js';
-import './chunk-HYZRY4KZ.js';
-import './chunk-ADJRGVZC.js';
-import './chunk-NWQTTSBB.js';
-import './chunk-HHJDN6AU.js';
-import { placeholderQueues, placeholderProblem, permissionModeProblems, permissionModeProblem, needsClaudeCredential, claudeCredentialCheck, claimPermissionProblem, formerSkillQueues, formerSkillProblem } from './chunk-LWSJQJC6.js';
+import './chunk-YETTWTAY.js';
+import './chunk-3OFZM4X6.js';
+import './chunk-SADUQSO4.js';
+import './chunk-KDVIU23F.js';
+import './chunk-MTP2QEVO.js';
+import './chunk-S5PCA3SN.js';
+import './chunk-UYOYTKE2.js';
+import './chunk-XNGMQ27R.js';
+import { placeholderQueues, placeholderProblem, permissionModeProblems, permissionModeProblem, needsClaudeCredential, claudeCredentialCheck, claimPermissionProblem, formerSkillQueues, formerSkillProblem } from './chunk-FUB7LRUE.js';
+import './chunk-AMFWYESY.js';
 import './chunk-YYYRBYWG.js';
-import './chunk-TI7B7UEO.js';
+import './chunk-GOBOJMOJ.js';
+import './chunk-JF42URPU.js';
+import './chunk-ESVW4MJY.js';
 import './chunk-TBT347UY.js';
-import './chunk-VQYBXPI7.js';
-import './chunk-ONKJUM6R.js';
-import './chunk-MAK5LYRF.js';
-import './chunk-KMDLFI4P.js';
-import './chunk-QKFB4K7X.js';
-import './chunk-RSNSZ2LJ.js';
-import './chunk-OZGHL5Y5.js';
-import './chunk-RLYZLUQ7.js';
+import './chunk-NL4XPC7W.js';
+import './chunk-Y5MXET4M.js';
+import './chunk-L2USZT6T.js';
+import './chunk-S26M3YBJ.js';
+import './chunk-GGOMT6KF.js';
+import './chunk-X5H2WYMB.js';
+import './chunk-6CHIYEZZ.js';
+import './chunk-SWCTGCSC.js';
+import './chunk-WGAUY5LE.js';
 import { parseRunnerEnv } from './chunk-6MZSX4M7.js';
-import './chunk-S3NYLI2P.js';
-import './chunk-6Y5RUTHO.js';
+import './chunk-KK4VBOH6.js';
+import './chunk-WBT5X3NH.js';
 import './chunk-IP7BIBXJ.js';
-import { loadRunnerConfig, RunnerConfigError, checkHooks } from './chunk-22RMZBGW.js';
+import './chunk-S76AYB4M.js';
+import './chunk-MQJSXHV7.js';
+import { loadRunnerConfig, RunnerConfigError, checkHooks } from './chunk-XGP3VYOG.js';
 import './chunk-UXYLWVTQ.js';
-import './chunk-R7PF5OOU.js';
-import './chunk-QOZKPLVJ.js';
-import './chunk-N5FOE5PS.js';
-import './chunk-OGFGZQA3.js';
-import './chunk-4NPZVMJU.js';
 import './chunk-7RQ73DLO.js';
-import './chunk-4Q7OMKAT.js';
+import './chunk-3CWUOFV6.js';
+import './chunk-QOZKPLVJ.js';
 import './chunk-CX22S5BA.js';
+import './chunk-ECODQ7II.js';
+import './chunk-JBJTC3UU.js';
+import './chunk-OGFGZQA3.js';
 import './chunk-F7CU5ABH.js';
 import './chunk-BKO6JEZI.js';
-import './chunk-3NSNIIBE.js';
-import './chunk-WUYTWNMA.js';
-import './chunk-JXYVA45C.js';
-import './chunk-4KSQKQXE.js';
-import './chunk-N6LURUEF.js';
-import './chunk-YRYMNBGQ.js';
-import './chunk-GQD22KKN.js';
+import './chunk-BMYGAGBJ.js';
+import './chunk-NACDBXUG.js';
+import './chunk-GOSFARMS.js';
+import './chunk-ANPNT6PM.js';
+import './chunk-T2Q7ISPE.js';
 import './chunk-WZBHBH3J.js';
 import './chunk-5QRP3MVS.js';
-import './chunk-YZ5F4PIS.js';
-import './chunk-WTE3MQML.js';
-import './chunk-C5Y5ZJJZ.js';
-import './chunk-ZJSNLVCE.js';
-import './chunk-YO4PSLVB.js';
-import './chunk-BYT5O5RV.js';
-import './chunk-POJMEEJJ.js';
-import './chunk-OHVJA253.js';
-import './chunk-PLMTLGYH.js';
-import './chunk-J5M7BSJQ.js';
+import './chunk-W5VPCONO.js';
+import './chunk-LXAY4A2G.js';
+import './chunk-T4Y6SCG3.js';
+import './chunk-ZRL6HKBY.js';
+import './chunk-52NC2FIU.js';
+import './chunk-MNTSH4CL.js';
+import './chunk-X5N6KC6V.js';
+import './chunk-N3CUDFCW.js';
 import './chunk-EABW6AJQ.js';
 import './chunk-RA3O54FC.js';
-import './chunk-V7NIVOFD.js';
-import './chunk-ZM2IMMYN.js';
-import './chunk-BWQ66M6N.js';
+import './chunk-M2ZWWTWZ.js';
+import './chunk-N2PXGQRL.js';
+import './chunk-BQXFBI7T.js';
+import './chunk-ULSIJGLS.js';
+import './chunk-G2YNJIGF.js';
 import './chunk-XCCLFVXM.js';
+import './chunk-ZJSNLVCE.js';
 import './chunk-BJ3KTMDH.js';
+import './chunk-CRB3POP4.js';
 import './chunk-VNVZDWO3.js';
 import './chunk-Z5GEFMRW.js';
 import { readFileSync } from 'fs';

package/dist/{chunk-R7PF5OOU.js → chunk-3CWUOFV6.js}

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
 import { RecipeError, locateRecipe, readRecipe, assertBuildable, writeSanitizedRecipe, classifyProperties, SANITIZED_NAME } from './chunk-QOZKPLVJ.js';
-import { startTimeOf, claimPidFile, RunnerAlreadyRunningError, releasePidFile } from './chunk-N5FOE5PS.js';
 import { CLAUDE_CODE_VERSION, NODE_IMAGE, DEFAULT_BASE_IMAGE, TINI_VERSION, GH_VERSION, GH_SHA256, TINI_SHA256 } from './chunk-CX22S5BA.js';
-import { withGitConfig, tokenHeader } from './chunk-BYT5O5RV.js';
-import { RUNNER_DIR_MODE, repoCacheDir, imagesDir, attemptStamp, runnerDir, rootfsPathFor, RUNNER_FILE_MODE } from './chunk-ZM2IMMYN.js';
+import { claimPidFile, RunnerAlreadyRunningError, releasePidFile } from './chunk-ECODQ7II.js';
+import { startTimeOf } from './chunk-JBJTC3UU.js';
+import { RUNNER_DIR_MODE, repoCacheDir, imagesDir, attemptStamp, runnerDir, rootfsPathFor, RUNNER_FILE_MODE } from './chunk-N2PXGQRL.js';
+import { withGitConfig, tokenHeader } from './chunk-BQXFBI7T.js';
 import { mkdirSync, rmSync, existsSync, mkdtempSync, cpSync, readFileSync, writeFileSync, readdirSync, lstatSync, readlinkSync } from 'fs';
 import { tmpdir } from 'os';
 import { dirname, join } from 'path';
@@ -36,6 +37,10 @@ function git(cwd, args, timeoutMs, extend = (env) => env) {
     );
   });
 }
+function gitFailureLine(err) {
+  const lines = (err instanceof Error ? err.message : String(err)).replace(/^git [\w-]+ failed: /, "").split("\n").map((line) => line.trim()).filter((line) => line !== "");
+  return lines.find((line) => !/^warning:/i.test(line)) ?? lines[0] ?? "";
+}
 function defaultBranchOf(lsRemote) {
   const match = lsRemote.match(/^ref: refs\/heads\/(\S+)\s+HEAD$/m);
   return match ? match[1] : null;
@@ -90,7 +95,7 @@ async function readBranchHead(input) {
   try {
     out = await git(input.dir, ["ls-remote", "--heads", input.remote, `refs/heads/${input.branch}`], HEAD_TIMEOUT_MS, credential);
   } catch (err) {
-    return { kind: "unreadable", reason: (err instanceof Error ? err.message : String(err)).replace(/^git [\w-]+ failed: /, "").split("\n")[0] };
+    return { kind: "unreadable", reason: gitFailureLine(err) };
   }
   const sha = out.match(/^([0-9a-f]{40}|[0-9a-f]{64})\trefs\/heads\//m)?.[1];
   return sha === void 0 ? { kind: "absent" } : { kind: "found", sha };
@@ -102,9 +107,10 @@ async function fetchCommit(input) {
     await git(input.dir, ["init", "--quiet"]);
     await git(input.dir, ["fetch", "--quiet", "--depth", "1", "--no-tags", input.remote, input.commit], CLONE_TIMEOUT_MS, credential);
     await git(input.dir, ["checkout", "--quiet", "--detach", "--force", "FETCH_HEAD"]);
+    if (input.clean === true) await git(input.dir, ["clean", "-ffdx", "--quiet"]);
     return { ok: true };
   } catch (err) {
-    const detail = (err instanceof Error ? err.message : String(err)).replace(/^git [\w-]+ failed: /, "").split("\n")[0];
+    const detail = gitFailureLine(err);
     return { ok: false, reason: `the fetch of ${input.commit.slice(0, 8)} from ${input.remote} failed: ${detail}` };
   }
 }
@@ -122,7 +128,7 @@ async function diffBetween(input) {
     );
     return { ok: true };
   } catch (err) {
-    const detail = (err instanceof Error ? err.message : String(err)).replace(/^git [\w-]+ failed: /, "").split("\n")[0];
+    const detail = gitFailureLine(err);
     return { ok: false, reason: `the diff of ${input.head.slice(0, 8)} from ${input.base.slice(0, 8)} could not be read from ${input.remote}: ${detail}` };
   }
 }
@@ -189,9 +195,9 @@ function toolsDockerfile(parts) {
     " && chmod 1777 /out/build",
     ...parts.guestHelper === true ? [
       "COPY guest/outerlayer-guest /out/opt/outerlayer/bin/outerlayer-guest",
-      // The guest mounts the build's tmpfs, the kernel's file systems and the run directory over these.
+      // The guest mounts the build's tmpfs, the kernel's file systems and the run directory over these. The judge's tmpfs is mounted over its directory when the judge runs.
       "RUN chmod 0755 /out/opt/outerlayer/bin/outerlayer-guest \\",
-      " && mkdir -p /out/outerlayer/job /out/run /out/proc /out/sys /out/dev"
+      " && mkdir -p /out/outerlayer/job /out/outerlayer/judge /out/run /out/proc /out/sys /out/dev"
     ] : [],
     `RUN set -eu \\`,
     ` && case "$TARGETARCH" in \\`,
@@ -295,6 +301,11 @@ function splitRepository(repository) {
   }
   return { full, owner: parts[0], name: parts[1] };
 }
+async function fetchPinnedCommit(opts) {
+  const fetched = await fetchCommit({ remote: opts.remote, dir: opts.dir, commit: opts.commit, token: opts.token, clean: true });
+  if (!fetched.ok) throw new RecipeError("repository_unreadable", `cannot read ${opts.repository}: ${fetched.reason}`);
+  return { dir: opts.dir, defaultBranch: opts.ref, commit: opts.commit };
+}
 function metadataOf(image) {
   try {
     const parsed = JSON.parse(image.labels["devcontainer.metadata"] ?? "[]");
@@ -345,12 +356,8 @@ async function buildRepositoryImage(opts, ports) {
     throw err;
   }
   try {
-    const checkout = await fetchDefaultBranch({
-      remote: opts.remote ?? `https://github.com/${owner}/${name}.git`,
-      dir: cacheDir,
-      token: opts.readToken,
-      repository
-    });
+    const remote = opts.remote ?? `https://github.com/${owner}/${name}.git`;
+    const checkout = opts.pinned === void 0 ? await fetchDefaultBranch({ remote, dir: cacheDir, token: opts.readToken, repository }) : await fetchPinnedCommit({ remote, dir: cacheDir, token: opts.readToken, repository, ...opts.pinned });
     const location = locateRecipe(checkout.dir);
     const recipe = readRecipe(checkout.dir, location);
     assertBuildable(checkout.dir, location, recipe);