impel-cli 0.20.62 → 0.20.63-canary.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.20.62",
+  "version": "0.20.63-canary.2",
   "description": "Prepare isolated Claude and Codex workspaces for every accessible Impel tenant",
   "type": "module",
   "bin": {

package/scripts/bake-canary-brand.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// Bake the canary channel into the runtime brand (canary release cycle, KTD7).
+//
+// `publish-canary.yml` runs this in the working tree immediately before
+// `pnpm pack`, after the test suite has run on the unmodified tree. It
+// rewrites the brand DEFAULT in `src/runtimeBrand.js` in place: the channel
+// literal becomes `canary` and the three production `defaultOrigin` literals
+// become the canary row of CHANNEL_ORIGINS, read from the very module being
+// baked so the row has one source of truth.
+//
+// It is a one-shot publish step, not a formatter: every literal it replaces
+// must occur exactly once in its shipped form, a file that is already baked
+// is refused, and the result is re-imported and validated before the script
+// exits 0 — a half-baked or doubly-baked tree can never be packed.
+//
+// Usage: node scripts/bake-canary-brand.mjs [path/to/runtimeBrand.js]
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const DEFAULT_TARGET = fileURLToPath(new URL("../src/runtimeBrand.js", import.meta.url));
+const CANARY_MARKER = 'channel: "canary",';
+
+function fail(message) {
+  process.stderr.write(`bake-canary-brand: ${message}\n`);
+  process.exit(1);
+}
+
+/** Import `target` fresh (never from this process's module cache) with no brand in the environment. */
+async function importBrandModule(target, cacheBuster) {
+  // The module reads IMPEL_CLI_RUNTIME_BRAND at import time; the bake is about
+  // the DEFAULT, so an inherited brand must not stand in for it.
+  delete process.env.IMPEL_CLI_RUNTIME_BRAND;
+  return import(`${pathToFileURL(target).href}?bake=${cacheBuster}`);
+}
+
+function replaceExactlyOnce(source, from, to) {
+  const occurrences = source.split(from).length - 1;
+  if (occurrences !== 1) {
+    fail(`expected exactly one occurrence of ${JSON.stringify(from)} in the brand source, found ${occurrences}`);
+  }
+  return source.replace(from, to);
+}
+
+async function main() {
+  const target = path.resolve(process.argv[2] || DEFAULT_TARGET);
+  const original = fs.readFileSync(target, "utf8");
+  if (original.includes(CANARY_MARKER)) fail(`${target} is already baked for the canary channel`);
+
+  const { CHANNEL_ORIGINS } = await importBrandModule(target, "before");
+  const rows = [
+    ['channel: "stable",', CANARY_MARKER],
+    ...["gateway", "sessions", "controlPlane"].map((column) => [
+      `defaultOrigin: ${JSON.stringify(CHANNEL_ORIGINS.stable[column])}`,
+      `defaultOrigin: ${JSON.stringify(CHANNEL_ORIGINS.canary[column])}`,
+    ]),
+  ];
+  let baked = original;
+  for (const [from, to] of rows) baked = replaceExactlyOnce(baked, from, to);
+
+  // Atomic replace, then prove the result by importing it: the DEFAULT must
+  // now be the canary row and must pass the validator's own channel check.
+  const temporary = `${target}.bake-${process.pid}`;
+  fs.writeFileSync(temporary, baked, { mode: fs.statSync(target).mode & 0o777 });
+  fs.renameSync(temporary, target);
+  try {
+    const { RUNTIME_BRAND, validateRuntimeBrand } = await importBrandModule(target, "after");
+    validateRuntimeBrand(RUNTIME_BRAND);
+    const mismatch = ["gateway", "sessions", "controlPlane"].find((column) => (
+      RUNTIME_BRAND[column].defaultOrigin !== CHANNEL_ORIGINS.canary[column]
+    ));
+    if (RUNTIME_BRAND.channel !== "canary" || mismatch) {
+      throw new Error(`baked DEFAULT is not the canary row (${mismatch || "channel"})`);
+    }
+    process.stdout.write(
+      `bake-canary-brand: ${target} now carries channel canary `
+      + `(gateway ${RUNTIME_BRAND.gateway.defaultOrigin}, sessions ${RUNTIME_BRAND.sessions.defaultOrigin}, `
+      + `controlPlane ${RUNTIME_BRAND.controlPlane.defaultOrigin})\n`,
+    );
+  } catch (error) {
+    fs.writeFileSync(target, original);
+    fail(`baked brand failed verification and was restored: ${error?.message || error}`);
+  }
+}
+
+await main();

package/scripts/canary-version.mjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+// Canary version computation and successor gate (canary release cycle, U4).
+//
+// `publish-canary.yml` publishes `<major>.<minor>.<patch + 1>-canary.<N>` on
+// every push to `dev` (R15), where `N` is `GITHUB_RUN_NUMBER` (KTD6): it is
+// monotonic across publishes and unique on a retry without a registry round
+// trip, and a GitHub re-run keeps its number, so the same version comes back
+// and the successor gate below refuses it. The script only reads
+// `package.json`; the publish job applies the version to its working tree
+// with `npm version --no-git-tag-version`, and nothing on `dev` is edited.
+//
+// Usage: node scripts/canary-version.mjs [package.json] [--dist-tags <file>]
+//   Prints the computed version on stdout. With `--dist-tags`, the file is
+//   the registry's dist-tags document and the version must strictly succeed
+//   its `canary` entry; an absent `canary` tag is the bootstrap case. Every
+//   refusal prints nothing on stdout and exits 1, so a caller that captures
+//   stdout can never pick up a half-computed version.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const RELEASE_VERSION = /^(\d+)\.(\d+)\.(\d+)$/u;
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/u;
+
+/** `<major>.<minor>.<patch + 1>-canary.<runNumber>` from a bare release version. */
+export function canaryVersion(packageVersion, runNumber) {
+  if (typeof packageVersion !== "string" || packageVersion === "") {
+    throw new Error(`package.json version must be a non-empty string, got ${JSON.stringify(packageVersion)}`);
+  }
+  if (/-/u.test(packageVersion) && SEMVER.test(packageVersion)) {
+    throw new Error(
+      `package.json version ${packageVersion} already carries a prerelease suffix; `
+      + "the canary base must be the bare release version committed on dev",
+    );
+  }
+  const match = RELEASE_VERSION.exec(packageVersion);
+  if (!match) {
+    throw new Error(`package.json version ${JSON.stringify(packageVersion)} is not a bare <major>.<minor>.<patch> release version`);
+  }
+  const text = typeof runNumber === "number" ? String(runNumber) : runNumber;
+  if (typeof text !== "string" || !/^\d+$/u.test(text) || Number(text) < 1 || !Number.isSafeInteger(Number(text))) {
+    throw new Error(`run number must be a positive integer, got ${JSON.stringify(runNumber)}`);
+  }
+  const [major, minor, patch] = match.slice(1).map(Number);
+  return `${major}.${minor}.${patch + 1}-canary.${Number(text)}`;
+}
+
+function parseSemver(text) {
+  const match = SEMVER.exec(text);
+  if (!match) throw new Error(`unparsable semver: ${text}`);
+  return {
+    release: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4] ? match[4].split(".") : [],
+  };
+}
+
+function compareIdentifiers(a, b) {
+  const aNumeric = /^\d+$/u.test(a);
+  const bNumeric = /^\d+$/u.test(b);
+  if (aNumeric && bNumeric) return Math.sign(Number(a) - Number(b));
+  if (aNumeric) return -1; // numeric identifiers sort before alphanumeric
+  if (bNumeric) return 1;
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** SemVer 2.0.0 precedence, the same ordering `publish-npm.yml`'s successor gate uses. */
+export function compareSemver(leftText, rightText) {
+  const a = parseSemver(leftText);
+  const b = parseSemver(rightText);
+  for (let index = 0; index < 3; index += 1) {
+    if (a.release[index] !== b.release[index]) return Math.sign(a.release[index] - b.release[index]);
+  }
+  if (a.prerelease.length === 0 && b.prerelease.length === 0) return 0;
+  if (a.prerelease.length === 0) return 1; // a release outranks its prereleases
+  if (b.prerelease.length === 0) return -1;
+  const length = Math.max(a.prerelease.length, b.prerelease.length);
+  for (let index = 0; index < length; index += 1) {
+    if (a.prerelease[index] === undefined) return -1; // shorter prerelease sorts first
+    if (b.prerelease[index] === undefined) return 1;
+    const result = compareIdentifiers(a.prerelease[index], b.prerelease[index]);
+    if (result !== 0) return result;
+  }
+  return 0;
+}
+
+/**
+ * Require `version` to strictly succeed `distTags.canary`. Only the `canary`
+ * tag is the predecessor: `latest` and `next` belong to the stable lane and
+ * never stand in for it. Returns a description for the step summary.
+ */
+export function assertCanarySuccessor(version, distTags) {
+  const current = distTags?.canary;
+  if (current === undefined) {
+    return {
+      bootstrap: true,
+      current,
+      message: `No existing \`canary\` dist-tag; ${version} is the canary channel bootstrap.`,
+    };
+  }
+  if (compareSemver(version, current) <= 0) {
+    throw new Error(
+      `version ${version} is not a strict semver successor of canary=${current}. `
+      + "A GitHub re-run keeps its run number and is refused by design; push a new commit "
+      + "to dev instead, or merge the released version back into dev if the base has moved.",
+    );
+  }
+  return {
+    bootstrap: false,
+    current,
+    message: `${version} strictly succeeds \`canary\`=${current}. Current tags: ${JSON.stringify(distTags)}`,
+  };
+}
+
+function fail(message) {
+  process.stderr.write(`canary-version: ${message}\n`);
+  process.exit(1);
+}
+
+function main(argv) {
+  let packageJson = "package.json";
+  let distTagsFile = null;
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--dist-tags") {
+      distTagsFile = argv[index + 1];
+      index += 1;
+      if (!distTagsFile) fail("--dist-tags requires a file path");
+    } else if (argument.startsWith("--")) {
+      fail(`unknown option ${argument}`);
+    } else {
+      packageJson = argument;
+    }
+  }
+
+  let version;
+  try {
+    const manifest = JSON.parse(fs.readFileSync(path.resolve(packageJson), "utf8"));
+    const runNumber = process.env.GITHUB_RUN_NUMBER;
+    if (runNumber === undefined || runNumber === "") fail("GITHUB_RUN_NUMBER is not set; the canary counter is the workflow run number");
+    version = canaryVersion(manifest.version, runNumber);
+  } catch (error) {
+    fail(error?.message || String(error));
+  }
+
+  if (distTagsFile) {
+    let distTags;
+    try {
+      distTags = JSON.parse(fs.readFileSync(path.resolve(distTagsFile), "utf8"));
+    } catch (error) {
+      fail(`cannot read dist-tags from ${distTagsFile}: ${error?.message || error}`);
+    }
+    if (!distTags || typeof distTags !== "object" || Array.isArray(distTags)) {
+      fail(`dist-tags document ${distTagsFile} is not a JSON object`);
+    }
+    let result;
+    try {
+      result = assertCanarySuccessor(version, distTags);
+    } catch (error) {
+      fail(error?.message || String(error));
+    }
+    process.stderr.write(`canary-version: ${result.message}\n`);
+    if (process.env.GITHUB_STEP_SUMMARY) {
+      fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, `## Canary gate: dist-tag successor\n\n${result.message}\n`);
+    }
+  }
+
+  process.stdout.write(`${version}\n`);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main(process.argv.slice(2));
+}

package/scripts/npm-dist-tags.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const DIST_TAGS_URL = "https://registry.npmjs.org/-/package/impel-cli/dist-tags";
+
+export function assertCanaryDistTags({ beforeLatest, expectedCanary, tags }) {
+  const latest = tags.latest ?? "";
+  const canary = tags.canary ?? "";
+  if (latest !== beforeLatest) {
+    throw new Error(
+      `dist-tags.latest moved during the canary publish: before=${beforeLatest || "<none>"} `
+      + `after=${latest || "<none>"}. The canary lane must never move latest; investigate before the next publish.`,
+    );
+  }
+  if (canary !== expectedCanary) {
+    throw new Error(`dist-tags.canary is ${canary || "<none>"}, expected ${expectedCanary}.`);
+  }
+  return { latest, canary };
+}
+
+async function readDistTags({ allowMissing, bustCache = false } = {}) {
+  const url = bustCache ? `${DIST_TAGS_URL}?t=${Date.now()}` : DIST_TAGS_URL;
+  let lastError;
+  for (let attempt = 1; attempt <= 3; attempt += 1) {
+    try {
+      const response = await fetch(url, { signal: AbortSignal.timeout(30_000) });
+      if (response.status === 404 && allowMissing) return {};
+      if (!response.ok) throw new Error(`npm registry dist-tags lookup failed: HTTP ${response.status}`);
+      const tags = await response.json();
+      if (!tags || typeof tags !== "object" || Array.isArray(tags)) {
+        throw new Error("npm registry returned an invalid dist-tags document");
+      }
+      return tags;
+    } catch (error) {
+      lastError = error;
+      if (attempt < 3) await new Promise((resolve) => setTimeout(resolve, 1_000));
+    }
+  }
+  throw lastError;
+}
+
+function appendEnvironment(name, value) {
+  if (!process.env.GITHUB_ENV) throw new Error("GITHUB_ENV is not set");
+  fs.appendFileSync(process.env.GITHUB_ENV, `${name}=${value}\n`);
+}
+
+function appendSummary(lines) {
+  if (!process.env.GITHUB_STEP_SUMMARY) throw new Error("GITHUB_STEP_SUMMARY is not set");
+  fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, `${lines.join("\n")}\n`);
+}
+
+async function main([command, ...args]) {
+  if (command === "fetch" && args.length === 1) {
+    const tags = await readDistTags({ allowMissing: true });
+    fs.writeFileSync(path.resolve(args[0]), `${JSON.stringify(tags)}\n`);
+    console.log(Object.keys(tags).length === 0 ? "No npm dist-tags found; using channel bootstrap." : "Fetched npm dist-tags.");
+    return;
+  }
+  if (command === "snapshot-latest" && args.length === 0) {
+    const tags = await readDistTags({ allowMissing: true });
+    const latest = tags.latest ?? "";
+    appendEnvironment("LATEST_BEFORE", latest);
+    console.log(`dist-tags.latest before publish: ${latest || "<none>"}`);
+    return;
+  }
+  if (command === "assert-canary" && args.length === 2) {
+    const [expectedCanary, beforeLatest] = args;
+    const tags = await readDistTags({ bustCache: true });
+    const { latest } = assertCanaryDistTags({ expectedCanary, beforeLatest, tags });
+    appendSummary([
+      "## Canary published",
+      "",
+      `- \`impel-cli@${expectedCanary}\` is \`canary\``,
+      `- \`latest\` is unchanged at \`${latest || "<none>"}\``,
+    ]);
+    console.log(`Published impel-cli@${expectedCanary} under canary; latest is still ${latest || "<none>"}.`);
+    return;
+  }
+  throw new Error(
+    "usage: node scripts/npm-dist-tags.mjs fetch <file> | snapshot-latest | assert-canary <version> <latest-before>",
+  );
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main(process.argv.slice(2)).catch((error) => {
+    console.error(`npm-dist-tags: ${error?.message || error}`);
+    process.exit(1);
+  });
+}

package/scripts/pack-canary.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+function appendEnvironment(name, value) {
+  if (!process.env.GITHUB_ENV) throw new Error("GITHUB_ENV is not set");
+  fs.appendFileSync(process.env.GITHUB_ENV, `${name}=${value}\n`);
+}
+
+function main([version]) {
+  const destination = process.env.RUNNER_TEMP;
+  if (!destination || !version) throw new Error("RUNNER_TEMP and a canary version are required");
+  execFileSync("pnpm", ["pack", "--pack-destination", destination], { stdio: "inherit" });
+  const tarball = path.join(destination, `impel-cli-${version}.tgz`);
+  if (!fs.existsSync(tarball)) throw new Error(`pnpm pack did not create ${tarball}`);
+  const prefix = path.join(destination, "impel-prefix");
+  execFileSync("npm", ["install", "--global", "--prefix", prefix, tarball], { stdio: "inherit" });
+  execFileSync(process.execPath, ["scripts/verify-canary-install.mjs", prefix, version], { stdio: "inherit" });
+  appendEnvironment("CANARY_TARBALL", tarball);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    main(process.argv.slice(2));
+  } catch (error) {
+    console.error(`pack-canary: ${error?.message || error}`);
+    process.exit(1);
+  }
+}

package/scripts/pack-release.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+function main() {
+  const destination = process.env.RUNNER_TEMP;
+  if (!destination) throw new Error("RUNNER_TEMP is required");
+  const { version } = JSON.parse(fs.readFileSync("package.json", "utf8"));
+  execFileSync("pnpm", ["pack", "--pack-destination", destination], { stdio: "inherit" });
+  const tarball = path.join(destination, `impel-cli-${version}.tgz`);
+  if (!fs.existsSync(tarball)) throw new Error(`pnpm pack did not create ${tarball}`);
+  const prefix = path.join(destination, "impel-prefix");
+  execFileSync("npm", ["install", "--global", "--prefix", prefix, tarball], { stdio: "inherit" });
+  const executable = process.platform === "win32" ? path.join(prefix, "impel.cmd") : path.join(prefix, "bin", "impel");
+  const actual = execFileSync(executable, ["--version"], { encoding: "utf8" }).trim();
+  if (actual !== version) throw new Error(`packed CLI reports ${actual}, expected ${version}`);
+  console.log(`Verified packed impel-cli ${version}.`);
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(`pack-release: ${error?.message || error}`);
+  process.exit(1);
+}

package/scripts/prepare-canary.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const CANARY_VERSION = /^\d+\.\d+\.\d+-canary\.\d+$/u;
+
+function main([version]) {
+  if (!CANARY_VERSION.test(version || "")) {
+    throw new Error(`the gate produced an invalid canary version: ${version || "<empty>"}`);
+  }
+  execFileSync("npm", ["version", version, "--no-git-tag-version"], { stdio: "inherit" });
+  execFileSync(process.execPath, ["scripts/bake-canary-brand.mjs"], { stdio: "inherit" });
+  const actual = JSON.parse(fs.readFileSync("package.json", "utf8")).version;
+  if (actual !== version) throw new Error(`package.json version ${actual} does not match ${version}`);
+  console.log(`Prepared ${version} canary package.`);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    main(process.argv.slice(2));
+  } catch (error) {
+    console.error(`prepare-canary: ${error?.message || error}`);
+    process.exit(1);
+  }
+}

package/scripts/release-gate.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { compareSemver } from "./canary-version.mjs";
+import { evaluateCheckRuns } from "./required-checks.mjs";
+
+const DIST_TAGS_URL = "https://registry.npmjs.org/-/package/impel-cli/dist-tags";
+
+function appendSummary(text) {
+  if (!process.env.GITHUB_STEP_SUMMARY) throw new Error("GITHUB_STEP_SUMMARY is not set");
+  fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, text.endsWith("\n") ? text : `${text}\n`);
+}
+
+async function fetchJson(url, { token, allowMissing = false } = {}) {
+  const response = await fetch(url, {
+    headers: {
+      Accept: "application/vnd.github+json",
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      "User-Agent": "UseImpel/impel-cli release gate",
+      "X-GitHub-Api-Version": "2022-11-28",
+    },
+    signal: AbortSignal.timeout(30_000),
+  });
+  if (response.status === 404 && allowMissing) return {};
+  if (!response.ok) throw new Error(`request failed: HTTP ${response.status}`);
+  return response.json();
+}
+
+async function checkRunsForCommit(repository, sha, token) {
+  const runs = [];
+  for (let page = 1; ; page += 1) {
+    const body = await fetchJson(
+      `https://api.github.com/repos/${repository}/commits/${sha}/check-runs?per_page=100&page=${page}`,
+      { token },
+    );
+    runs.push(...body.check_runs.map(({ name, status, conclusion }) => ({ name, status, conclusion })));
+    if (body.check_runs.length < 100) return runs;
+  }
+}
+
+function manifest() {
+  return JSON.parse(fs.readFileSync("package.json", "utf8"));
+}
+
+export function verifyTag({ tag, version }) {
+  const expected = `v${version}`;
+  if (tag !== expected) throw new Error(`release tag ${tag} does not match ${expected}`);
+  return expected;
+}
+
+export function verifyMain({ sha, mainRef = "origin/main" }) {
+  try {
+    execFileSync("git", ["merge-base", "--is-ancestor", sha, mainRef], { stdio: "ignore" });
+  } catch {
+    throw new Error(`tagged commit ${sha} is not on ${mainRef}; merge to main before tagging`);
+  }
+}
+
+export async function verifyChecks({ repository, sha, token }) {
+  const result = evaluateCheckRuns(await checkRunsForCommit(repository, sha, token));
+  const summary = result.summary;
+  appendSummary(summary);
+  if (result.state !== "success") {
+    throw new Error(`required checks on ${sha} are not all green: ${result.failures.join("; ") || result.pending.join(", ")}`);
+  }
+  return result;
+}
+
+export async function verifySuccessor({ version, channel = version.includes("-") ? "next" : "latest" }) {
+  const tags = await fetchJson(DIST_TAGS_URL, { allowMissing: true });
+  const current = tags[channel] ?? (channel === "next" ? tags.latest : undefined);
+  const message = current === undefined
+    ? `No existing \`${channel}\` dist-tag; ${version} is the channel bootstrap.`
+    : `${version} strictly succeeds \`${channel}\`=${current}. Current tags: ${JSON.stringify(tags)}`;
+  if (current !== undefined && compareSemver(version, current) <= 0) {
+    throw new Error(`version ${version} is not a strict semver successor of ${channel}=${current}`);
+  }
+  appendSummary(`## Release gate: dist-tag successor\n\n${message}\n`);
+  console.log(message);
+  return { channel, current, tags };
+}
+
+export function selectDistTag(version) {
+  const tag = version.includes("-") ? "next" : "latest";
+  if (!process.env.GITHUB_ENV) throw new Error("GITHUB_ENV is not set");
+  fs.appendFileSync(process.env.GITHUB_ENV, `NPM_DIST_TAG=${tag}\n`);
+  console.log(`Publishing ${version} under npm dist-tag ${tag}.`);
+  return tag;
+}
+
+async function main([command]) {
+  const pkg = manifest();
+  if (command === "verify-tag") {
+    verifyTag({ tag: process.env.RELEASE_TAG, version: pkg.version });
+    return;
+  }
+  if (command === "verify-main") {
+    const sha = execFileSync("git", ["rev-parse", "HEAD"], { encoding: "utf8" }).trim();
+    verifyMain({ sha });
+    console.log(`Tagged commit ${sha} is on origin/main.`);
+    return;
+  }
+  if (command === "verify-checks") {
+    const sha = execFileSync("git", ["rev-parse", "HEAD"], { encoding: "utf8" }).trim();
+    await verifyChecks({
+      repository: process.env.GITHUB_REPOSITORY,
+      sha,
+      token: process.env.GH_TOKEN,
+    });
+    console.log(`All required checks are green on ${sha}.`);
+    return;
+  }
+  if (command === "verify-successor") {
+    await verifySuccessor({ version: pkg.version });
+    return;
+  }
+  if (command === "select-dist-tag") {
+    selectDistTag(pkg.version);
+    return;
+  }
+  throw new Error("usage: node scripts/release-gate.mjs verify-tag|verify-main|verify-checks|verify-successor|select-dist-tag");
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main(process.argv.slice(2)).catch((error) => {
+    console.error(`release-gate: ${error?.message || error}`);
+    process.exit(1);
+  });
+}

package/scripts/release-metadata.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import { execFileSync } from "node:child_process";
+
+function main() {
+  if (!process.env.GITHUB_OUTPUT) throw new Error("GITHUB_OUTPUT is not set");
+  const { version } = JSON.parse(fs.readFileSync("package.json", "utf8"));
+  const sourceCommit = execFileSync("git", ["rev-parse", "HEAD"], { encoding: "utf8" }).trim();
+  fs.appendFileSync(process.env.GITHUB_OUTPUT, `version=${version}\nsource_commit=${sourceCommit}\n`);
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(`release-metadata: ${error?.message || error}`);
+  process.exit(1);
+}

package/scripts/required-checks.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// The CI check names a publishable commit must carry (canary release cycle, U4).
+//
+// Both release workflows consume this list through checked-in gate scripts.
+// A renamed CI job that is not renamed here fails the suite, not a release.
+// Every push to `dev` and `main` runs these via `ci.yml`, so they must exist on
+// a publishable SHA; names must match the job names exactly.
+//
+// Usage:
+//   node scripts/required-checks.mjs <check-runs.ndjson>
+//     Evaluate the Checks API output (one `{name, status, conclusion}` JSON
+//     object per line). Prints the markdown summary on stdout and exits 0
+//     when every required check is green, 2 while any is still queued,
+//     running, or not yet reported (the caller polls), and 1 when a required
+//     check, or a present Windows vendor check, has a non-success conclusion.
+//   node scripts/required-checks.mjs --list
+//     Print the required names, one per line.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const REQUIRED_CHECKS = Object.freeze([
+  "Node 18 on ubuntu-latest",
+  "Node 18 on macos-latest",
+  "Node 18 on windows-latest",
+  "Node 24 on ubuntu-latest",
+  "Node 24 on macos-latest",
+  "Node 24 on windows-latest",
+  "Pinned macOS CLI installer contract",
+  "Pinned ChatGPT/Codex config contract",
+  "Pinned Claude config contract",
+  "Windows standard-user Codex config contract",
+]);
+
+// The Windows vendor contract workflow is path-filtered, so its jobs may
+// legitimately be absent. Present => must be green. Absent => loud warning
+// telling the operator when a manual dispatch is owed.
+export const CONDITIONAL_CHECKS = Object.freeze([
+  "Pinned Claude MSIX install and replacement",
+  "Pinned ChatGPT/Codex Store install",
+]);
+
+/**
+ * Judge one commit's check runs. A name with any completed/success run is
+ * green (a re-run supersedes an earlier failure); a name with no run yet, or
+ * whose runs are all still queued or in progress, is pending; a name whose
+ * runs have all completed without a success has failed. Failure outranks
+ * pending so a superseded or broken SHA is refused as soon as it is known.
+ */
+export function evaluateCheckRuns(runs, { required = REQUIRED_CHECKS, conditional = CONDITIONAL_CHECKS } = {}) {
+  const byName = new Map();
+  for (const run of runs) {
+    if (!byName.has(run.name)) byName.set(run.name, []);
+    byName.get(run.name).push(run);
+  }
+  const runsFor = (name) => byName.get(name) ?? [];
+  const green = (name) => runsFor(name).some((run) => run.status === "completed" && run.conclusion === "success");
+  const unfinished = (name) => runsFor(name).some((run) => run.status !== "completed");
+  const describe = (name) => {
+    const found = runsFor(name);
+    if (found.length === 0) return "MISSING";
+    return found.map((run) => `${run.status}/${run.conclusion ?? "none"}`).join(", ");
+  };
+
+  const failures = [];
+  const pending = [];
+  const absentConditional = [];
+  for (const name of required) {
+    if (green(name)) continue;
+    if (runsFor(name).length === 0 || unfinished(name)) pending.push(name);
+    else failures.push(`required check "${name}": ${describe(name)}`);
+  }
+  for (const name of conditional) {
+    if (runsFor(name).length === 0) absentConditional.push(name);
+    else if (green(name)) continue;
+    else if (unfinished(name)) pending.push(name);
+    else failures.push(`Windows vendor check "${name}": ${describe(name)}`);
+  }
+
+  const state = failures.length > 0 ? "failure" : pending.length > 0 ? "pending" : "success";
+  const summary = ["## Release gate: checks on the commit", ""];
+  summary.push("| Check | Result |", "| --- | --- |");
+  for (const name of [...required, ...conditional]) summary.push(`| ${name} | ${describe(name)} |`);
+  if (absentConditional.length > 0) {
+    summary.push(
+      "",
+      "> **Warning:** " + absentConditional.map((name) => `\`${name}\``).join(" and ")
+        + " never ran on this commit. If this change touches bundle-affecting files"
+        + " (src/apps.js, src/windowsApps.js, src/desktopTasks.js, src/codesign.js,"
+        + " src/selfInvocation.js, or the Windows contract tests), dispatch the"
+        + " \"Pinned Windows vendor app contract\" workflow against this commit.",
+    );
+  }
+  if (failures.length > 0) summary.push("", "**Gate failed:**", ...failures.map((failure) => `- ${failure}`));
+  if (state === "pending") summary.push("", "**Still waiting on:** " + pending.map((name) => `\`${name}\``).join(", "));
+  summary.push("", `Total check runs found on this commit: ${runs.length}`);
+
+  return { state, failures, pending, absentConditional, summary: summary.join("\n") + "\n" };
+}
+
+function main(argv) {
+  if (argv[0] === "--list") {
+    process.stdout.write(REQUIRED_CHECKS.join("\n") + "\n");
+    return;
+  }
+  if (argv.length !== 1) {
+    process.stderr.write("usage: node scripts/required-checks.mjs <check-runs.ndjson> | --list\n");
+    process.exit(1);
+  }
+  const lines = fs.readFileSync(path.resolve(argv[0]), "utf8").split("\n").filter((line) => line.trim() !== "");
+  const runs = lines.map((line) => JSON.parse(line));
+  const result = evaluateCheckRuns(runs);
+  process.stdout.write(result.summary);
+  for (const failure of result.failures) process.stderr.write(`${failure}\n`);
+  if (result.state === "failure") process.exit(1);
+  if (result.state === "pending") {
+    process.stderr.write(`waiting for ${result.pending.map((name) => `"${name}": ${runs.some((run) => run.name === name) ? "pending" : "MISSING"}`).join(", ")}\n`);
+    process.exit(2);
+  }
+  process.stderr.write("All required checks are green on the pushed commit.\n");
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main(process.argv.slice(2));
+}

package/scripts/verify-canary-install.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+export function assertCanaryInstall({ version, expectedVersion, brand, origins }) {
+  assert.equal(version, `${expectedVersion} (canary)`);
+  assert.deepEqual({
+    channel: brand.channel,
+    gateway: brand.gateway,
+    sessions: brand.sessions,
+    resolvedSessions: brand.resolvedSessions,
+    controlPlane: brand.controlPlane,
+  }, {
+    channel: "canary",
+    gateway: origins.gateway,
+    sessions: origins.sessions,
+    resolvedSessions: origins.sessions,
+    controlPlane: origins.controlPlane,
+  });
+}
+
+async function main([prefix, expectedVersion]) {
+  if (!prefix || !expectedVersion) throw new Error("usage: node scripts/verify-canary-install.mjs <npm-prefix> <version>");
+  // Assert the installed package's defaults, never an Actions-level override.
+  for (const name of ["IMPEL_GATEWAY_URL", "IMPEL_SESSIONS_URL", "IMPEL_APP_URL", "IMPEL_CLI_RUNTIME_BRAND"]) {
+    delete process.env[name];
+  }
+  const cli = path.join(prefix, "bin", "impel");
+  const root = path.join(prefix, "lib", "node_modules", "impel-cli");
+  const version = execFileSync(cli, ["--version"], {
+    encoding: "utf8",
+    env: { ...process.env, IMPEL_SKIP_UPDATE_CHECK: "1", IMPEL_DISABLE_TELEMETRY: "1" },
+  }).trim();
+  const load = (file) => import(pathToFileURL(path.join(root, "src", file)).href);
+  const [config, sessions, runtime] = await Promise.all([
+    load("config.js"),
+    load("sessionCollector.js"),
+    load("runtimeBrand.js"),
+  ]);
+  const { resolveDefaultGateway, resolveDefaultAppUrl } = config;
+  const { DEFAULT_SESSIONS_URL, resolveSessionsUrl } = sessions;
+  const { CHANNEL_ORIGINS, RUNTIME_BRAND } = runtime;
+  assertCanaryInstall({
+    version,
+    expectedVersion,
+    brand: {
+      channel: RUNTIME_BRAND.channel,
+      gateway: resolveDefaultGateway(),
+      sessions: DEFAULT_SESSIONS_URL,
+      resolvedSessions: resolveSessionsUrl({}),
+      controlPlane: resolveDefaultAppUrl(),
+    },
+    origins: CHANNEL_ORIGINS.canary,
+  });
+  console.log(`Installed canary ${version} resolves ${JSON.stringify(CHANNEL_ORIGINS.canary)}.`);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await main(process.argv.slice(2));
+}

package/src/cli.js

@@ -34,6 +34,7 @@ import {
   TELEMETRY_FLUSH_COMMAND,
 } from "./posthog.js";
 import { maybePrintTelemetryNotice } from "./telemetryNotice.js";
+import { versionLine } from "./runtimeBrand.js";
 
 const HELP = `impel — isolated Impel workspaces for every tenant
 
@@ -93,7 +94,7 @@ Config file:
 function printVersion() {
   const pkgPath = fileURLToPath(new URL("../package.json", import.meta.url));
   const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
-  console.log(pkg.version);
+  console.log(versionLine(pkg.version));
 }
 
 // Accepts "claude" | "codex" | "all" | undefined; returns a normalized target

package/src/commands/auth.js

@@ -3,6 +3,7 @@ import {
   loadConfig,
   CONFIG_PATH,
   saveConfig,
+  foreignChannelOrigin,
   normalizeGatewayUrl,
   resolveDefaultGateway,
   resolveDefaultAppUrl,
@@ -12,7 +13,8 @@ import { promptSecret } from "../prompt.js";
 import { applyCliUser, fetchTenants, normalizeTenantId } from "../tenants.js";
 import { RUNTIME_BRAND } from "../runtimeBrand.js";
 
-export async function cmdAuth(argv) {
+export async function cmdAuth(argv, overrides = {}) {
+  const io = { fetchTenants, promptSecret, ...overrides };
   const { flags } = parseFlags(argv, {
     pat: { type: "string" },
     gateway: { type: "string" },
@@ -20,11 +22,16 @@ export async function cmdAuth(argv) {
     tenant: { type: "string" },
   });
 
-  const existing = loadConfig();
+  // `auth` is the one command that must run against a config whose origins
+  // belong to another channel: it is how a device that carried a production
+  // config is moved onto the canary origins (and the message `loadConfig`
+  // prints elsewhere tells the tester to run it).
+  const canary = RUNTIME_BRAND.channel === "canary";
+  const existing = loadConfig({ rejectForeignOrigins: !canary });
 
   let pat = flags.pat;
   if (!pat) {
-    pat = await promptSecret(`${RUNTIME_BRAND.product.displayName} Personal Access Token (${RUNTIME_BRAND.auth.patPrefix}...): `);
+    pat = await io.promptSecret(`${RUNTIME_BRAND.product.displayName} Personal Access Token (${RUNTIME_BRAND.auth.patPrefix}...): `);
   }
   if (!pat) {
     console.error("impel: no PAT provided, aborting.");
@@ -37,12 +44,21 @@ export async function cmdAuth(argv) {
     );
   }
 
-  const gatewayUrl = normalizeGatewayUrl(flags.gateway || existing?.gatewayUrl || resolveDefaultGateway());
-  const appUrl = normalizeGatewayUrl(flags.app || existing?.appUrl || resolveDefaultAppUrl());
+  // Under the canary brand the stored origins are ignored in favour of the
+  // brand defaults; a production origin can only survive here if it is asked
+  // for explicitly, and then it is refused below rather than written.
+  const gatewayUrl = normalizeGatewayUrl(flags.gateway || (canary ? null : existing?.gatewayUrl) || resolveDefaultGateway());
+  const appUrl = normalizeGatewayUrl(flags.app || (canary ? null : existing?.appUrl) || resolveDefaultAppUrl());
+  for (const [key, value] of [["gatewayUrl", gatewayUrl], ["appUrl", appUrl]]) {
+    const expected = foreignChannelOrigin(key, value);
+    if (expected) {
+      throw new Error(`${key} ${value} is not a ${RUNTIME_BRAND.channel} origin; this ${RUNTIME_BRAND.channel} build talks only to ${expected}.`);
+    }
+  }
 
   const config = { ...(existing || {}), pat, gatewayUrl, appUrl, updatedAt: new Date().toISOString() };
   try {
-    const listing = await fetchTenants(config);
+    const listing = await io.fetchTenants(config);
     const requestedTenant = flags.tenant ? normalizeTenantId(flags.tenant) : null;
     const selected = requestedTenant
       ? listing.tenants.find((tenant) => tenant.id === requestedTenant || tenant.slug === requestedTenant)

package/src/commands/update.js

@@ -15,7 +15,7 @@ import {
   convergenceSummaryDiagnostics,
   readRecentConvergenceSummary,
 } from "../convergenceSummary.js";
-import { brandedEnvironmentName, brandedText, RUNTIME_BRAND } from "../runtimeBrand.js";
+import { brandedEnvironmentName, brandedText, RUNTIME_BRAND, versionLine } from "../runtimeBrand.js";
 import { IMPEL_CLI_ENTRYPOINT } from "../selfInvocation.js";
 import {
   fetchRemoteVersion,
@@ -68,7 +68,9 @@ export function postInstallCliRunnable(expectedVersion, { spawn = spawnSync, exe
       windowsHide: true,
     });
     if (run.status !== 0 || run.error) return false;
-    return String(run.stdout || "").trim() === expectedVersion.trim();
+    // The freshly installed build is the same package on the same channel, so
+    // its `--version` line carries the same channel suffix this build prints.
+    return String(run.stdout || "").trim() === versionLine(expectedVersion.trim());
   } catch {
     return false;
   }

package/src/config.js

@@ -47,8 +47,39 @@ export function normalizeGatewayUrl(url) {
   return LEGACY_GATEWAY_URLS.has(normalized) ? DEFAULT_GATEWAY_URL : normalized;
 }
 
-/** Returns the parsed config object, or null if it doesn't exist yet. Throws on malformed JSON. */
-export function loadConfig() {
+const CHANNEL_ORIGIN_KEYS = Object.freeze({
+  gatewayUrl: Object.freeze({ brandDefault: DEFAULT_GATEWAY_URL, environmentSuffix: "GATEWAY_URL" }),
+  appUrl: Object.freeze({ brandDefault: DEFAULT_APP_URL, environmentSuffix: "APP_URL" }),
+});
+
+/**
+ * Under the canary brand, an origin the CLI would use must be the canary row
+ * the brand carries, or the explicit branded env override (how an engineer
+ * points a build at a local service). Returns the origin `key` is required to
+ * be when `value` is foreign, else null. The stable brand accepts every
+ * origin, exactly as before channels existed.
+ *
+ * Why this exists: the canary CLI replaces the stable one on a device under
+ * the same package name, so an engineer's existing production config would
+ * otherwise keep a canary build talking to production with production
+ * credentials (R17).
+ */
+export function foreignChannelOrigin(key, value) {
+  if (RUNTIME_BRAND.channel !== "canary" || !value) return null;
+  const { brandDefault, environmentSuffix } = CHANNEL_ORIGIN_KEYS[key];
+  const normalized = normalizeGatewayUrl(value);
+  const override = process.env[brandedEnvironmentName(environmentSuffix)];
+  if (normalized === brandDefault || (override && normalized === normalizeGatewayUrl(override))) return null;
+  return brandDefault;
+}
+
+/**
+ * Returns the parsed config object, or null if it doesn't exist yet. Throws
+ * on malformed JSON, and — under the canary brand — on a stored origin outside
+ * the canary row unless `rejectForeignOrigins` is false (`impel auth` reads
+ * that way so it can move a device off a production config).
+ */
+export function loadConfig({ rejectForeignOrigins = true } = {}) {
   let raw;
   try {
     raw = fs.readFileSync(CONFIG_PATH, "utf8");
@@ -56,15 +87,27 @@ export function loadConfig() {
     if (err.code === "ENOENT") return null;
     throw err;
   }
+  let config;
   try {
-    const config = JSON.parse(raw);
-    if (config?.gatewayUrl) config.gatewayUrl = normalizeGatewayUrl(config.gatewayUrl);
-    return config;
+    config = JSON.parse(raw);
   } catch {
     throw new Error(
       `${CONFIG_PATH} exists but isn't valid JSON. Fix or delete it, then run \`${RUNTIME_BRAND.cli.command} auth\` again.`
     );
   }
+  if (config?.gatewayUrl) config.gatewayUrl = normalizeGatewayUrl(config.gatewayUrl);
+  if (rejectForeignOrigins) {
+    for (const key of Object.keys(CHANNEL_ORIGIN_KEYS)) {
+      const expected = foreignChannelOrigin(key, config?.[key]);
+      if (expected) {
+        throw new Error(
+          `${CONFIG_PATH} stores ${key} ${normalizeGatewayUrl(config[key])}, but this ${RUNTIME_BRAND.channel} build talks only to ${expected}; `
+          + `run \`${RUNTIME_BRAND.cli.command} auth\` to re-enrol this device against the ${RUNTIME_BRAND.channel} origins.`
+        );
+      }
+    }
+  }
+  return config;
 }
 
 /** Writes the config atomically-ish and locks it down to 0600 (owner read/write only). */

package/src/extension/index.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 
 import { main as upstreamMain } from "../cli.js";
-import { brandedText, RUNTIME_BRAND, validateRuntimeBrand } from "../runtimeBrand.js";
+import { brandedText, RUNTIME_BRAND, validateRuntimeBrand, versionLine } from "../runtimeBrand.js";
 
 const ALIASES = Object.freeze({
   apps: "app",
@@ -95,7 +95,7 @@ export function createImpelCliExtension({ brand, entrypoint, version }) {
         return;
       }
       if (["--version", "-v"].includes(rawCommand)) {
-        process.stdout.write(`${version}\n`);
+        process.stdout.write(`${versionLine(version)}\n`);
         return;
       }
       const command = ALIASES[rawCommand] || rawCommand;

package/src/posthog.js

@@ -101,7 +101,7 @@ export const TELEMETRY_CONTRACT = Object.freeze({
       name: "cli_bug_report",
       origin: "server",
       properties: [
-        { key: "channel", type: "string", required: true, values: ["latest", "next"] },
+        { key: "channel", type: "string", required: true, values: ["latest", "next", "canary"] },
         { key: "cliVersion", type: "string", required: true, maxLength: 32 },
         { key: "hasMessage", type: "boolean", required: true },
         {
@@ -123,7 +123,7 @@ export const TELEMETRY_CONTRACT = Object.freeze({
       name: "cli_command_run",
       origin: "cli",
       properties: [
-        { key: "channel", type: "string", required: true, values: ["latest", "next"] },
+        { key: "channel", type: "string", required: true, values: ["latest", "next", "canary"] },
         { key: "cliVersion", type: "string", required: true, maxLength: 32 },
         { key: "command", type: "string", required: true, maxLength: 64 },
         {

package/src/runtimeBrand.js

@@ -14,8 +14,34 @@ const SUPPORTED_COMMANDS = new Set([
   "models", "agents", "update", "use", "experimental",
 ]);
 
+/**
+ * The closed per-channel origin row (canary release cycle, KTD9).
+ *
+ * A brand names its channel and every default origin must be that channel's
+ * row: a canary build pointed at production, or a stable build pointed at
+ * dev, is rejected at validation. `channel` is absent from the shipped
+ * source's third-party brands and defaults to `stable`, which constrains
+ * nothing beyond "not the canary row" so embedders' own origins stay valid.
+ * `scripts/bake-canary-brand.mjs` rewrites DEFAULT below to the canary row at
+ * publish time; the literals there are what it substitutes.
+ */
+export const CHANNEL_ORIGINS = Object.freeze({
+  stable: Object.freeze({
+    gateway: "https://gateway.useimpel.com",
+    sessions: "https://sessions.useimpel.com",
+    controlPlane: "https://www.useimpel.com",
+  }),
+  canary: Object.freeze({
+    gateway: "https://gateway.dev.useimpel.com",
+    sessions: "https://sessions.dev.useimpel.com",
+    controlPlane: "https://next.dev.useimpel.com",
+  }),
+});
+const CANARY_ORIGIN_SET = new Set(Object.values(CHANNEL_ORIGINS.canary));
+
 const DEFAULT = Object.freeze({
   schemaVersion: 1,
+  channel: "canary",
   product: Object.freeze({ id: "impel", displayName: "Impel" }),
   cli: Object.freeze({
     command: "impel",
@@ -27,9 +53,9 @@ const DEFAULT = Object.freeze({
   }),
   auth: Object.freeze({ patPrefix: "impel_pat_", tenantPrefix: "impel_tenant_" }),
   tenant: Object.freeze({ defaultId: null, displayName: null }),
-  gateway: Object.freeze({ defaultOrigin: "https://gateway.useimpel.com" }),
-  sessions: Object.freeze({ defaultOrigin: "https://sessions.useimpel.com" }),
-  controlPlane: Object.freeze({ defaultOrigin: "https://www.useimpel.com" }),
+  gateway: Object.freeze({ defaultOrigin: "https://gateway.dev.useimpel.com" }),
+  sessions: Object.freeze({ defaultOrigin: "https://sessions.dev.useimpel.com" }),
+  controlPlane: Object.freeze({ defaultOrigin: "https://next.dev.useimpel.com" }),
   updates: Object.freeze({ registry: null }),
   apps: Object.freeze({
     displayPrefix: "Impel",
@@ -74,10 +100,32 @@ function pathSegment(name, value) {
   return result;
 }
 
+function channel(value) {
+  if (value == null) return "stable";
+  if (value === "stable" || value === "canary") return value;
+  throw new Error("impel-cli runtime brand channel must be stable or canary");
+}
+
+/** Validate one default origin against the brand's channel row (R10). */
+function channelOrigin(name, value, brandChannel) {
+  const normalized = origin(name, value);
+  const column = name.split(".")[0];
+  if (brandChannel === "canary") {
+    const expected = CHANNEL_ORIGINS.canary[column];
+    if (normalized !== expected) {
+      throw new Error(`impel-cli runtime brand ${name} must be ${expected} on the canary channel`);
+    }
+  } else if (CANARY_ORIGIN_SET.has(normalized)) {
+    throw new Error(`impel-cli runtime brand ${name} is a canary origin; the stable channel must not carry it`);
+  }
+  return normalized;
+}
+
 export function validateRuntimeBrand(input) {
   if (!input || Array.isArray(input) || typeof input !== "object" || input.schemaVersion !== 1) {
     throw new Error("impel-cli runtime brand schemaVersion must be 1");
   }
+  const brandChannel = channel(input.channel);
   const command = text("cli.command", input.cli?.command, SAFE_ID);
   const packageName = text("cli.packageName", input.cli?.packageName || command, SAFE_PACKAGE);
   if (path.isAbsolute(packageName)) throw new Error("impel-cli runtime brand cli.packageName is invalid");
@@ -92,6 +140,7 @@ export function validateRuntimeBrand(input) {
   }
   return Object.freeze({
     schemaVersion: 1,
+    channel: brandChannel,
     product: Object.freeze({
       id: text("product.id", input.product?.id, SAFE_ID),
       displayName: text("product.displayName", input.product?.displayName),
@@ -112,14 +161,15 @@ export function validateRuntimeBrand(input) {
       defaultId: defaultTenant,
       displayName: input.tenant?.displayName == null ? defaultTenant : text("tenant.displayName", input.tenant.displayName),
     }),
-    gateway: Object.freeze({ defaultOrigin: origin("gateway.defaultOrigin", input.gateway?.defaultOrigin) }),
+    gateway: Object.freeze({ defaultOrigin: channelOrigin("gateway.defaultOrigin", input.gateway?.defaultOrigin, brandChannel) }),
     sessions: Object.freeze({
-      defaultOrigin: origin(
+      defaultOrigin: channelOrigin(
         "sessions.defaultOrigin",
         input.sessions?.defaultOrigin || input.gateway?.defaultOrigin,
+        brandChannel,
       ),
     }),
-    controlPlane: Object.freeze({ defaultOrigin: origin("controlPlane.defaultOrigin", input.controlPlane?.defaultOrigin) }),
+    controlPlane: Object.freeze({ defaultOrigin: channelOrigin("controlPlane.defaultOrigin", input.controlPlane?.defaultOrigin, brandChannel) }),
     updates: Object.freeze({
       registry: input.updates?.registry == null
         ? null
@@ -158,6 +208,15 @@ export function brandedEnvironmentName(suffix) {
   return `${RUNTIME_BRAND.cli.environmentPrefix}_${suffix}`;
 }
 
+/**
+ * The line `--version` prints. Off the stable channel it names the channel so
+ * a tester can tell a canary process from a stable one at a glance (R8); the
+ * stable output is the bare version, byte-identical to before channels existed.
+ */
+export function versionLine(version) {
+  return RUNTIME_BRAND.channel === "stable" ? String(version) : `${version} (${RUNTIME_BRAND.channel})`;
+}
+
 export function brandedText(value) {
   return String(value)
     .replaceAll("impel-cli", `${RUNTIME_BRAND.cli.command}-cli`)

package/src/updates.js

@@ -36,13 +36,22 @@ export function updateRegistry() {
   ).replace(/\/+$/u, "");
 }
 
-function normalizeUpdateTag(tag) {
-  if (tag === "latest" || tag === "next") return tag;
+/** The closed set of npm dist-tags the CLI can follow. */
+export function normalizeUpdateTag(tag) {
+  if (tag === "latest" || tag === "next" || tag === "canary") return tag;
   throw new Error(`unsupported npm update tag "${tag}"`);
 }
 
-/** Keep prerelease installs on npm's prerelease channel. */
+/**
+ * Keep prerelease installs on npm's prerelease channel.
+ *
+ * A canary build is keyed on the brand channel rather than its version
+ * string: `<patch+1>-canary.<N>` is a prerelease, but it must follow the
+ * `canary` dist-tag, not `next` — and under the stable brand that same
+ * version is only ever a prerelease that follows `next`.
+ */
 export function updateTagForVersion(version) {
+  if (RUNTIME_BRAND.channel === "canary") return "canary";
   const parsed = validVersion(version) ? version.match(VERSION_RE) : null;
   return parsed?.[4] ? "next" : "latest";
 }