impel-cli 0.20.61 → 0.20.63-canary.1

package/RELEASE_NOTES.md

@@ -1,5 +1,16 @@
 # Release notes
 
+## 0.20.62 — Silence the Codex apps connector in desktop profiles
+
+- Persists `features.apps = false` in the managed ChatGPT desktop `config.toml`
+  so the hosted `codex_apps` connector no longer handshakes against the gateway
+  passthrough without a credential (HTTP 401 "MCP startup incomplete") when
+  the embedded Codex is launched from that profile. 0.20.61 applied this gate
+  only as a runtime override on `impel codex`; the desktop writer still set
+  `enable_mcp_apps=false` alone, which governs MCP-UI rendering and leaves the
+  connector enabled. Bumps the managed config version so existing installs
+  rewrite the profile.
+
 ## 0.20.61 — Silence the Codex apps connector at startup
 
 - Passes `features.apps=false` to tenant Codex CLI sessions so Codex no longer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.20.61",
+  "version": "0.20.63-canary.1",
   "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/notify-canary.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const TARGET = "https://api.github.com/repos/UseImpel/impel-apps/dispatches";
+
+async function main([version]) {
+  const token = process.env.IMPEL_APPS_DISPATCH_TOKEN;
+  const commit = process.env.GITHUB_SHA;
+  if (!version || !commit) throw new Error("canary version and GITHUB_SHA are required");
+  if (!token) {
+    const message = `IMPEL_APPS_DISPATCH_TOKEN is not configured; impel-apps will pick up impel-cli@${version} on its next canary rebuild.`;
+    console.warn(message);
+    if (process.env.GITHUB_STEP_SUMMARY) {
+      fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, `${message}\n`);
+    }
+    return;
+  }
+  const response = await fetch(TARGET, {
+    method: "POST",
+    headers: {
+      Accept: "application/vnd.github+json",
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+      "User-Agent": "UseImpel/impel-cli canary publisher",
+      "X-GitHub-Api-Version": "2022-11-28",
+    },
+    body: JSON.stringify({
+      event_type: "impel-cli-canary",
+      client_payload: { version, source_commit: commit, dist_tag: "canary" },
+    }),
+    signal: AbortSignal.timeout(30_000),
+  });
+  if (!response.ok) throw new Error(`impel-apps dispatch failed: HTTP ${response.status}`);
+  console.log(`Dispatched impel-cli canary ${version} (${commit}) to UseImpel/impel-apps.`);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main(process.argv.slice(2)).catch((error) => {
+    console.error(`notify-canary: ${error?.message || error}`);
+    process.exit(1);
+  });
+}

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/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/required-checks.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// The CI check names a publishable commit must carry (canary release cycle, U4).
+//
+// `publish-npm.yml`'s release gate inlines this list and must stay
+// byte-identical (R19), so the canary publisher reads it from here and
+// `test/publish-canary-workflow.test.js` asserts the two copies are equal:
+// a renamed CI job that is not renamed in both places 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 = ["## Canary gate: checks on the pushed 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/scripts/wait-for-required-checks.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { evaluateCheckRuns } from "./required-checks.mjs";
+
+const POLL_INTERVAL_MS = 30_000;
+const TIMEOUT_MS = 60 * 60 * 1_000;
+
+const delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+async function fetchCheckRuns(repository, sha, token) {
+  const runs = [];
+  for (let page = 1; ; page += 1) {
+    const response = await fetch(
+      `https://api.github.com/repos/${repository}/commits/${sha}/check-runs?per_page=100&page=${page}`,
+      {
+        headers: {
+          Accept: "application/vnd.github+json",
+          Authorization: `Bearer ${token}`,
+          "User-Agent": "UseImpel/impel-cli canary publisher",
+          "X-GitHub-Api-Version": "2022-11-28",
+        },
+        signal: AbortSignal.timeout(30_000),
+      },
+    );
+    if (!response.ok) throw new Error(`Checks API request failed: HTTP ${response.status}`);
+    const body = await response.json();
+    for (const { name, status, conclusion } of body.check_runs) {
+      runs.push({ name, status, conclusion });
+    }
+    if (body.check_runs.length < 100) return runs;
+  }
+}
+
+function writeSummary(summary) {
+  if (!process.env.GITHUB_STEP_SUMMARY) throw new Error("GITHUB_STEP_SUMMARY is not set");
+  fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, summary);
+}
+
+async function main() {
+  const { GITHUB_REPOSITORY: repository, GITHUB_SHA: sha, GH_TOKEN: token } = process.env;
+  if (!repository || !sha || !token) throw new Error("GITHUB_REPOSITORY, GITHUB_SHA, and GH_TOKEN are required");
+  const deadline = Date.now() + TIMEOUT_MS;
+  let lastSummary = "";
+  while (Date.now() < deadline) {
+    try {
+      const result = evaluateCheckRuns(await fetchCheckRuns(repository, sha, token));
+      lastSummary = result.summary;
+      if (result.state === "success") {
+        writeSummary(result.summary);
+        console.log(`All required checks are green on ${sha}.`);
+        return;
+      }
+      if (result.state === "failure") {
+        writeSummary(result.summary);
+        throw new Error(`A required check on ${sha} completed without success; nothing is published for this commit.`);
+      }
+      console.log(`Required checks are still pending on ${sha}; retrying in 30 seconds.`);
+    } catch (error) {
+      if (/completed without success/u.test(error?.message || "")) throw error;
+      console.warn(`Checks API request failed (${error?.message || error}); retrying in 30 seconds.`);
+    }
+    await delay(POLL_INTERVAL_MS);
+  }
+  if (lastSummary) writeSummary(lastSummary);
+  throw new Error(`Canary gate timed out after 60 minutes waiting for required checks on ${sha}.`);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`wait-for-required-checks: ${error?.message || error}`);
+    process.exit(1);
+  });
+}

package/src/apps.js

@@ -1589,7 +1589,7 @@ function mergeManagedChatGPTToml(current, managed) {
  * as staleness so the profile heals immediately instead of waiting out the
  * manifest TTL.
  */
-export function managedChatGPTConfigDrifted(paths) {
+export function managedChatGPTConfigDrifted(paths, platform = process.platform) {
   let current;
   try {
     current = fs.readFileSync(path.join(paths.chatgpt.codexHome, "config.toml"), "utf8");
@@ -1603,6 +1603,12 @@ export function managedChatGPTConfigDrifted(paths) {
   // out the refresh TTL. Configs from generations before the key existed are
   // merely stale (the manifest version bump rewrites them), never drift —
   // require it only once this install's manifest proves it was written.
+  //
+  // Only macOS demands the enabled value. The impel-apps profile generator
+  // deliberately emits `false` off macOS, where no companion check proves
+  // codex-code-mode-host shipped; requiring `true` there would flag every
+  // generated Windows profile as drifted and regenerate it on each refresh.
+  // Off macOS, require only that the key survives the vendor settings writer.
   let manifestConfigVersion = 0;
   try {
     manifestConfigVersion = Number(JSON.parse(
@@ -1612,8 +1618,11 @@ export function managedChatGPTConfigDrifted(paths) {
     // Without a readable manifest the version gate stays closed.
   }
   const featuresTable = current.match(/^\[features\]\n(?:[^[\n][^\n]*\n|\n)*/mu)?.[0] || "";
+  const requiredCodeModeHost = platform === "darwin"
+    ? /^code_mode_host = true$/mu
+    : /^code_mode_host = (?:true|false)$/mu;
   const featureKeysDropped = manifestConfigVersion >= 35
-    && !/^code_mode_host = true$/mu.test(featuresTable);
+    && !requiredCodeModeHost.test(featuresTable);
   return !current.includes(CHATGPT_CONFIG_START)
     || readTopLevelTomlString(current, "model_provider") !== RUNTIME_BRAND.cli.providerId
     || !readTopLevelTomlString(current, "chatgpt_base_url")

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/codexSecurity.js

@@ -169,17 +169,26 @@ export function enableManagedCodexDesktopCodeModeHost(
     "true",
     configPath,
   );
-  // Managed desktop profiles do not ship the native Codex Apps companion and
-  // must not eagerly initialize the vendor `codex_apps` MCP client. That
-  // client expects OpenAI account credentials, while Impel routes inference
-  // through the gateway and intentionally has no native account token.
-  return upsertManagedScalar(
+  // Codex contributes the hosted `codex_apps` connector whenever the stable
+  // `apps` feature is on. It handshakes against chatgpt_base_url with the
+  // native OpenAI account credential, which a gateway-routed profile does not
+  // have, so the gateway answers HTTP 401 at every startup. `enable_mcp_apps`
+  // only governs MCP-UI rendering and does not gate the connector; keep it
+  // off as well since the managed desktop never renders apps.
+  const withoutMcpApps = upsertManagedScalar(
     withCodeModeHost,
     "features",
     "enable_mcp_apps",
     "false",
     configPath,
   );
+  return upsertManagedScalar(
+    withoutMcpApps,
+    "features",
+    "apps",
+    "false",
+    configPath,
+  );
 }
 
 function assertSafeManagedPath(target, expectedType) {

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/launch.js

@@ -79,23 +79,37 @@ export const IMPEL_CODEX_SPECIALIST_DELEGATION_INSTRUCTIONS =
 export const IMPEL_CODEX_PARENT_DELEGATION_INSTRUCTIONS =
   `${IMPEL_CODEX_SPECIALIST_DELEGATION_INSTRUCTIONS} ${IMPEL_CUSTOM_AGENT_VERBATIM_RELAY_APPENDIX}`;
 
-const IMPEL_CODEX_RUNTIME_OVERRIDES = [
-  // The standalone companion is optional and is not shipped by every native
-  // Codex distribution (notably some Windows/macOS CLI packages). Disable the
-  // launcher path for tenant CLI sessions so a missing helper cannot abort
-  // startup. Desktop bundles that include the helper enable it explicitly.
-  "features.code_mode_host=false",
-  // Codex contributes the hosted codex_apps connector whenever the stable
-  // `apps` feature is on. It handshakes against chatgpt_base_url with no
-  // gateway credential, so headless tenant sessions get an HTTP 401 at
-  // startup. `enable_mcp_apps` only governs MCP-UI rendering and does not
-  // gate the connector; keep it off as well since the CLI never renders apps.
-  "features.apps=false",
-  "features.enable_mcp_apps=false",
-  // CLI profiles do not load desktop/plugin lifecycle bundles. Plugin hooks
-  // are user-layer code and newer Codex versions review every one at startup.
-  "features.plugins=false",
-];
+function impelCodexRuntimeOverrides(platform) {
+  return [
+    // Pinned Codex ships `code_mode_host` as a stable, default-on feature and
+    // fails closed when a code_mode_only model is selected while it is off —
+    // which is every 5.6-family model in the managed catalog. The flag is
+    // therefore derived from the platform rather than pinned to one value: the
+    // two failure modes it sits between are platform-specific, and forcing
+    // either answer onto both platforms regresses the other.
+    //
+    // macOS: resolveReviewedVendorCliBinary already refuses to launch a Codex
+    // whose codex-code-mode-host companion is missing, unsigned, or from the
+    // wrong team (see verifyReviewedMacVendorCli in ../vendorCliBinaries.js).
+    // Reaching launch proves the helper is present, so disabling the feature is
+    // pure loss.
+    //
+    // Other platforms: verifyReviewedWindowsVendorCli gates on version only and
+    // cannot prove the companion shipped, so keep the feature off rather than
+    // risk aborting startup on a distribution that omits it.
+    `features.code_mode_host=${platform === "darwin" ? "true" : "false"}`,
+    // Codex contributes the hosted codex_apps connector whenever the stable
+    // `apps` feature is on. It handshakes against chatgpt_base_url with no
+    // gateway credential, so headless tenant sessions get an HTTP 401 at
+    // startup. `enable_mcp_apps` only governs MCP-UI rendering and does not
+    // gate the connector; keep it off as well since the CLI never renders apps.
+    "features.apps=false",
+    "features.enable_mcp_apps=false",
+    // CLI profiles do not load desktop/plugin lifecycle bundles. Plugin hooks
+    // are user-layer code and newer Codex versions review every one at startup.
+    "features.plugins=false",
+  ];
+}
 
 const IMPEL_CODEX_UNRESTRICTED_ARGUMENT = "--dangerously-bypass-approvals-and-sandbox";
 const IMPEL_CLAUDE_MANAGED_AGENT_ARGUMENTS = [
@@ -112,6 +126,7 @@ const IMPEL_CLAUDE_MANAGED_AGENT_ARGUMENTS = [
 export function impelLaunchArguments(tool, argv, {
   claudeManagedAgent = null,
   codexAgentProfile = null,
+  platform = process.platform,
 } = {}) {
   if (!RUNTIME_BRAND.features.agents) return [...argv];
   if (tool === "claude") {
@@ -172,7 +187,7 @@ export function impelLaunchArguments(tool, argv, {
         `developer_instructions=${JSON.stringify(IMPEL_CODEX_PARENT_DELEGATION_INSTRUCTIONS)}`,
         IMPEL_CODEX_UNRESTRICTED_ARGUMENT,
       ]),
-      ...IMPEL_CODEX_RUNTIME_OVERRIDES.flatMap((override) => ["-c", override]),
+      ...impelCodexRuntimeOverrides(platform).flatMap((override) => ["-c", override]),
       ...argv,
     ];
   }

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/managedProfileVersion.js

@@ -14,4 +14,7 @@
 // reasserting the FALLBACK_MODELS floor, records provenance in
 // models-manifest.json, and (with cross-app models enabled) routes the CLI
 // provider through the experimental OpenAI-compatible gateway path.
-export const CURRENT_CONFIG_VERSION = 46;
+// v47 persists `features.apps = false` in the managed ChatGPT desktop profile
+// so the hosted codex_apps connector stops handshaking against the gateway
+// without a credential (the same gate 0.20.61 passed to CLI sessions).
+export const CURRENT_CONFIG_VERSION = 47;

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";
 }