@catalyst-cloud/cli 0.16.33 → 0.16.35

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.16.35
+
+On a self-hosted machine set up before 0.16.33, the runner update agent kept running the CLI it was installed with, and that CLI could not update itself. The daily job installed newer versions into its own folder, but the agent never ran them. Installing this release globally (`npm install -g @catalyst-cloud/cli`) now points that agent at the newly installed copy. It only ever moves the agent to a newer catalyst, and keeps the agent's runner folder and PATH. It saves the previous agent file beside it, as `<file>.before-0.16.35`, so you can roll back. On a Mac it waits for an update already in progress to finish. An agent file you cannot change is left alone. Each outcome is written to the runner's `update.log`, and a failed attempt puts the agent back exactly as it was. The install itself never fails because of this. To turn it off, set `CATALYST_NO_AGENT_REPOINT=1`.
+
+`catalyst runner update --check` now says when the last update failed or was rolled back, with its time, its reason and the release it was offered, between the image result and the component report. The JSON output carries the same as `lastProblem`.
+
+## 0.16.34
+
+`catalyst runner update` now tells Catalyst how its previous run went when it reads the approved release. A self-hosted machine that keeps waiting, refusing or rolling back an update shows up without anyone reading its local log. It sends a short report: the outcome, its reason code, the release it runs, the release that run was offered, when it ran and the CLI version. `--check` sends nothing, and nothing beyond that fixed set of words leaves the machine. When a self-hosted Mac cannot re-check its private storage during an update, the update log now names the reason instead of a generic failure.
+
+`catalyst update` now puts the Cloud and Dev skills packs and the Cloud Claude plugin at the exact commits the approved release names. Before, a matching version number read as current even from a different commit, and a pack ahead of the approved release stayed ahead. The Cloud plugin moves through Claude Code from the same verified copy, and the CLI no longer copies its bundled skills over an approved installation when it starts.
+
+`catalyst codex-env` adds the AI account and the machine name to the telemetry attributes a Codex launch reports, so its usage can be summed per account. `--print` prints the value, `--apply` sets it for apps opened from the Dock on macOS, and `--refresh` fetches the workspace's AI accounts again. `catalyst setup` now installs this for you when Codex is on the machine: a small `codex` wrapper in `~/.zshrc` and `~/.bashrc` for terminal launches, and on macOS a login item that covers Codex opened from the Dock. If the CLI cannot answer, Codex starts exactly as before. `catalyst setup --no-shell-hook` skips both, `catalyst setup --remove-codex-attribution` removes them, and `catalyst status` says whether they are installed.
+
 ## 0.16.33
 
 On a self-hosted machine, `catalyst update` now sees the approved versions of the CLI and the Cloud and Dev skills, and moves them. Before this release it reported "no approved version" for all three on every self-hosted machine and left them where they were. The runner images were not affected.

package/README.md

@@ -138,6 +138,14 @@ catalyst ready --onboarding --json
 
 The dry run writes no files. `--only <step>` runs one step and reports its scope separately from full onboarding. Exit 10 means a failed step, 11 means waiting, and 12 means a guard refused the action. The private receipt is `install/last-run.json` under your machine's Catalyst state directory; credentials stay in the login config. A fake HOME reports old services and keeps them intact.
 
+### Codex launches name their coding account
+
+When Codex is on this computer (a `codex` command on your PATH, or `Codex.app` in `/Applications` or `~/Applications`), setup adds a `codex` shell function to `~/.zshrc` and `~/.bashrc`, between the lines `# >>> catalyst codex attribution >>>` and `# <<< catalyst codex attribution <<<`. It writes to each of those files that exists, and creates one only for your login shell (`$SHELL`), so a Mac that uses only zsh gets no `~/.bashrc`. Bash on macOS reads `~/.bash_profile` rather than `~/.bashrc`, so if you use bash and your `~/.bash_profile` does not already source `~/.bashrc`, add the line `[ -f ~/.bashrc ] && . ~/.bashrc` to it. Each time you run `codex`, the function asks `catalyst codex-env --print` which coding account the Codex home in use (`$CODEX_HOME`, else `~/.codex`) is signed in to, and passes the answer to that one launch as `OTEL_RESOURCE_ATTRIBUTES`. The answer comes from a local cache, so a launch never waits on the network. Running setup again replaces the block in place. Setup leaves a file alone, and says why, when it already defines `codex` as a function or an alias of yours, or when it is a link to a file outside your home folder. A link to a file inside your home folder is followed, and the file keeps its permissions.
+
+On a Mac, setup also installs the `dev.catalystcloud.codex-attribution` LaunchAgent. It runs `catalyst codex-env --apply` when you log in, and again whenever Codex signs in to another account in its default home, so apps you start from the Dock or Finder, the Codex desktop app included, carry the same attributes. An app that is already open keeps the environment it started with. It picks up a change the next time it starts. On Linux, setup adds the shell function only. Without Codex, setup adds nothing and says it skipped this. Run `catalyst setup` again after you install Codex to add it.
+
+`catalyst status` ends with one line that says whether this is installed, which coding account the Codex home resolves to, and how old the cached account list is. `catalyst setup --no-shell-hook` skips all of it. `catalyst setup --remove-codex-attribution` removes it and runs nothing else. Each file goes back to exactly what it was before the block was added, the LaunchAgent is unloaded and deleted, and the two attributes it set (the coding account and the machine name) are taken back out of the launch environment. Attributes you set there yourself are kept. A fake HOME gets none of this.
+
 ### Headless setup (CI, image builds, agent VMs)
 
 `catalyst onboard --headless` (or `CATALYST_ONBOARD_HEADLESS=1`) is for a machine with no person at it. It assumes every browser approval already happened: the person's key exists, and Linear and GitHub are connected for the workspace and the person. It never prompts, never opens a browser and never starts the device sign-in. Every input comes from a flag, an environment variable or a file:
@@ -298,6 +306,7 @@ The package pins the contract range `1.x || 2.x`, recorded in `package.json` und
 - `~/.config/catalyst-cloud/customer.json`, written with mode `0600`, holding your personal key, who you are, and the CLI path.
 - `~/.config/catalyst-cloud/contract.json`, your account's cached contract.
 - `~/.config/catalyst-cloud/published.json`, the cached answer to "what is the newest release" — no credential in it.
+- The Codex launch hook: one marked block in `~/.zshrc` and `~/.bashrc`, and on a Mac `~/Library/LaunchAgents/dev.catalystcloud.codex-attribution.plist` with its log at `~/.config/catalyst-cloud/codex-attribution.log` (see "Codex launches name their coding account").
 - After `catalyst update` moves the CLI: `~/.config/catalyst-cloud/cli-runtimes/`, one directory per CLI version it installed and `active.json` naming the one your `catalyst` command runs.
 - Only if you start them: `~/.config/catalyst-cloud/replica.db` with its `.pid`, `.writer.lock` and `.writer.state` sidecars, `$XDG_STATE_HOME/catalyst/events/<tenant>/backbone/` (or the home-directory fallback) with bounded daily event segments, and `~/.config/catalyst-cloud/watch-cursor.json`.
 
@@ -305,7 +314,15 @@ The skill files themselves are written by whichever install command you ran, in
 
 ## Updating
 
-`catalyst update --check` lists each installed component beside the version your workspace approved, says which one is behind and why, and changes nothing. Add `--project <absolute path>` to include a project's SDK; the report gives the one command that moves it, `catalyst update sdk --project <path>`. A project's files change only when you run that command, or after you turn its SDK updates on with `catalyst update policy sdk on --project <path>`. `catalyst update` moves the runner images, the CLI, the Cloud skills (copied on this machine or installed as the Claude plugin), and a running local replica to the approved versions. The new CLI is installed beside the old one, and your `catalyst` command runs it from then on, at the same path. A running replica restarts on it and keeps its synced data; a stopped one stays stopped. The Claude plugin moves through Claude Code, and only when its marketplace serves the approved version; run `/reload-plugins` or restart Claude Code afterwards. When the release check cannot find the `claude` command, it changes nothing and prints the one command that moves the plugin. The development skills are not on the approved release yet: the report lists their version as unknown and gives no command for them, so update them the way you installed them. On a machine whose runner checks for releases every 15 minutes (`catalyst runner auto-update on`), that check moves the same components by itself. Otherwise they move when you run `catalyst update`. That check moves the runner images to a newer release only at set times of day, 03:00, 11:00, 16:00 and 22:00 in the machine's time zone, so a busy machine is not restarted every time a release is approved. `catalyst update policy windows 06:00,18:00 --time-zone America/Chicago` sets your own times, `catalyst update policy windows default` goes back to these, and `catalyst runner update` or `catalyst update` applies a waiting release at once. Each component is on by default; turn one off with `catalyst update policy <component> off` (for example `cli`), and `catalyst update policy` lists every setting. If you turned the installer's daily update off, the CLI and both skills packs start held, and `catalyst update policy cli on` turns the CLI back on. Add `--json` for a machine-readable report.
+`catalyst update --check` lists each installed component beside the version your workspace approved and changes nothing. For skills packs and the Cloud plugin, the report also compares `installedCommit` with `approvedCommit`. Matching versions alone do not establish that the installed skills match approval. Add `--json` for the machine-readable report, or `--project <absolute path>` to include a project's SDK. A project's files change only when you run `catalyst update sdk --project <path>`, or after you turn its SDK updates on with `catalyst update policy sdk on --project <path>`.
+
+`catalyst update` moves enabled components to the approved release. Owned skills packs move to the exact approved repository commits, including correction of a pack ahead of approval. It verifies existing contents before replacing them, preserves independent skills and local edits, and adds no missing skill names. The Cloud plugin uses the same verified Cloud checkout as a local user-scope marketplace. Run `/reload-plugins` or restart Claude Code after it updates. A missing `claude` executable, unsupported plugin scope or uncertain ownership leaves the plugin in place with a reason. Dev skills move only when the approved release includes a Dev pack; `pack_not_approved` means the installed pack was kept.
+
+The new CLI is installed beside the old one, and your `catalyst` command runs it at the same path. A running local replica restarts on it and keeps its synced data; a stopped one stays stopped. CLI, SDK and image updates keep their existing policy against moving to an older version. Ordinary CLI startup never replaces skills with its bundled copy.
+
+On a machine checking for releases every 15 minutes (`catalyst runner auto-update on`), that check applies the same component policies. Otherwise components move when you run `catalyst update`. That check moves the runner images to a newer release only at set times of day, 03:00, 11:00, 16:00 and 22:00 in the machine's time zone, so a busy machine is not restarted every time a release is approved. `catalyst update policy windows 06:00,18:00 --time-zone America/Chicago` sets your own times, `catalyst update policy windows default` goes back to these, and `catalyst runner update` or `catalyst update` applies a waiting release at once. Each component is on by default; turn one off with `catalyst update policy <component> off` (for example `cli`), and `catalyst update policy` lists every setting. If you turned the installer's daily update off, the CLI and both skills packs start held, and `catalyst update policy cli on` turns the CLI back on.
+
+The installer's daily job runs the same release check, so it moves the CLI and the Cloud skills only to the approved release and keeps your holds. Until the development skills join the release, it refreshes them from their repository.
 
 A CLI older than `catalyst update` cannot move itself: install it once with `npm install -g @catalyst-cloud/cli@latest && catalyst login`. The re-login rewrites the CLI path the skills spawn, so they stop running the old bundle. To run one command against the latest publish without installing, use `npx -p @catalyst-cloud/cli@latest catalyst login`. The next `catalyst` run prints a one-line notice:
 
@@ -325,10 +342,12 @@ Remove the skills the way you installed them: `/plugin uninstall catalyst@cataly
 
 ```sh
 catalyst replica stop
+catalyst setup --remove-codex-attribution
 rm -f ~/.config/catalyst-cloud/customer.json ~/.config/catalyst-cloud/contract.json ~/.config/catalyst-cloud/published.json ~/.config/catalyst-cloud/watch-cursor.json
 rm -f ~/.config/catalyst-cloud/replica.db ~/.config/catalyst-cloud/replica.db.pid ~/.config/catalyst-cloud/replica.db.writer.lock ~/.config/catalyst-cloud/replica.db.writer.state
 rm -rf "${XDG_STATE_HOME:-$HOME/.local/state}/catalyst/events"
 rm -rf ~/.config/catalyst-cloud/cli-runtimes
+rm -f ~/.config/catalyst-cloud/codex-accounts.json ~/.config/catalyst-cloud/codex-attribution.log
 npm uninstall -g @catalyst-cloud/cli
 ```
 

package/bin/postinstall.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// npm's postinstall for @catalyst-cloud/cli (CTC-6975): on a global install, point an older runner
+// update agent at this copy (src/agent-repoint.ts). A local or workspace install does nothing, and
+// nothing here ever fails the install. CATALYST_NO_AGENT_REPOINT=1 turns it off.
+if (process.env.npm_config_global === "true" && process.env.CATALYST_NO_AGENT_REPOINT !== "1") {
+  try {
+    const { postinstallRepoint } = await import("../dist/agent-repoint.js");
+    const line = postinstallRepoint();
+    if (line) console.error(line);
+  } catch (err) {
+    console.error(`catalyst: could not check the runner update agent (${err instanceof Error ? err.message : String(err)}). Run: catalyst runner auto-update on`);
+  }
+}

package/dist/agent-repoint.js

@@ -0,0 +1,241 @@
+// agent-repoint.ts — CTC-6975. A machine set up before 0.16.33 runs its runner update agent from a CLI
+// that can never move itself: those CLIs read no approved component release on a self-hosted machine,
+// so the agent's own copy stays where it was installed, while the daily job installs the newest CLI
+// into its own global prefix. npm runs this from that install (bin/postinstall.js) and points an older
+// agent at the copy updates do move.
+//
+// It only ever moves the agent forward, touches only this CLI's own agent, keeps the agent's runner
+// directory and PATH, and never fails the install. The agent file it replaces is kept beside it, named
+// `<file>.before-<version>`, which neither launchd nor systemd loads: that copy is the rollback.
+// Removing the stale CLI copy is the installer's job.
+import { accessSync, appendFileSync, constants, copyFileSync, existsSync, readFileSync, realpathSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { compareVersions, exactVersion } from "./approved-release.js";
+import { LEGACY_PACKAGE_NAME, readManifest } from "./config.js";
+import { AUTO_UPDATE_LABEL, defaultRun, enableAutoUpdate, launchAgentPath, scheduledPath, systemdUnitPaths, writeFileAtomic, } from "./runner-auto-update.js";
+import { CLAUDE_PATH_ENV, resolveClaude } from "./update-plugin.js";
+/** Long enough for an in-place update (under a minute on a Mac measured 2026-10-24), well inside the
+ *  installer's 600-second budget for the whole npm install. */
+export const BUSY_WAIT_MS = 240_000;
+const BUSY_POLL_MS = 5_000;
+const blockingSleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+const unxml = (value) => value.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&amp;/g, "&");
+/** The agent's command, from a plist this CLI wrote (launchAgentPlist). Anything else is unrecognized. */
+function plistProgram(text) {
+    const array = /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(text)?.[1];
+    if (array === undefined)
+        return null;
+    const args = [...array.matchAll(/<string>([\s\S]*?)<\/string>/g)].map((m) => unxml(m[1] ?? ""));
+    const env = (key) => {
+        const m = new RegExp(`<key>${key}</key>\\s*<string>([\\s\\S]*?)</string>`).exec(text);
+        return m ? unxml(m[1] ?? "") : null;
+    };
+    return programOf(args, env("PATH"), env(CLAUDE_PATH_ENV));
+}
+/** systemd's quoted words, as systemdUnits writes them. */
+function unitWords(line) {
+    return [...line.matchAll(/"((?:[^"\\]|\\.)*)"/g)].map((m) => (m[1] ?? "").replace(/\\(.)/g, "$1").replace(/%%/g, "%"));
+}
+function unitProgram(text) {
+    const lines = text.split("\n");
+    const exec = lines.find((l) => l.startsWith("ExecStart="));
+    if (exec === undefined)
+        return null;
+    const envs = lines.filter((l) => l.startsWith("Environment=")).flatMap((l) => unitWords(l));
+    const env = (key) => envs.find((e) => e.startsWith(`${key}=`))?.slice(key.length + 1) ?? null;
+    return programOf(unitWords(exec), env("PATH"), env(CLAUDE_PATH_ENV));
+}
+function programOf(args, path, claude) {
+    const [cli, ...rest] = args;
+    if (cli === undefined || !cli.startsWith("/") || rest.length !== 5)
+        return null;
+    const [a, b, c, d, dir] = rest;
+    if (a !== "runner" || b !== "update" || c !== "--auto" || d !== "--dir" || dir === undefined || !dir.startsWith("/"))
+        return null;
+    return { cli, dir, path, claude };
+}
+const real = (path) => {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return null;
+    }
+};
+const writable = (path) => {
+    try {
+        accessSync(path, constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** The version of the catalyst package a command belongs to, or null when it is not one. */
+export function cliVersionAt(command) {
+    const resolved = real(command);
+    if (resolved === null)
+        return null;
+    let dir = dirname(resolved);
+    for (let i = 0; i < 4; i++) {
+        const manifest = join(dir, "package.json");
+        if (existsSync(manifest)) {
+            try {
+                const pkg = JSON.parse(readFileSync(manifest, "utf8"));
+                if (pkg.name === "@catalyst-cloud/cli" || pkg.name === LEGACY_PACKAGE_NAME)
+                    return exactVersion(pkg.version);
+            }
+            catch {
+                return null;
+            }
+            return null;
+        }
+        dir = dirname(dir);
+    }
+    return null;
+}
+/** Whether the macOS agent is idle, waiting up to the budget for a running update to finish. */
+function waitIdle(deps) {
+    const run = deps.run ?? defaultRun;
+    const sleep = deps.sleep ?? blockingSleep;
+    const target = `gui/${deps.uid ?? process.getuid?.() ?? 0}/${AUTO_UPDATE_LABEL}`;
+    for (let waited = 0;; waited += BUSY_POLL_MS) {
+        if (!/^\s*state = running\s*$/m.test(run("launchctl", ["print", target]).stdout))
+            return true;
+        if (waited >= (deps.busyWaitMs ?? BUSY_WAIT_MS))
+            return false;
+        sleep(BUSY_POLL_MS);
+    }
+}
+/** Put the agent file back and load it again, best effort, then drop the backup. */
+function restore(deps, platform, agent, original, backup) {
+    if (!existsSync(agent) || !readFileSync(agent).equals(original)) {
+        writeFileAtomic(agent, original.toString("utf8"));
+        const run = deps.run ?? defaultRun;
+        try {
+            if (platform === "darwin")
+                run("launchctl", ["bootstrap", `gui/${deps.uid ?? process.getuid?.() ?? 0}`, agent]);
+            else
+                run("systemctl", ["--user", "daemon-reload"]);
+        }
+        catch {
+            // the file is back; the scheduler picks it up at the next login or reload
+        }
+    }
+    unlinkSync(backup);
+}
+/** Point an older runner update agent at this install. Never throws. Every outcome for an agent this
+ *  CLI recognizes is also appended to the agent's own update.log: npm hides a postinstall's output on
+ *  a global install, so that log is where a person, or a later run, reads what happened. */
+export function repointAgent(deps) {
+    const seen = {};
+    const result = decide(deps, seen);
+    if (seen.dir !== undefined) {
+        try {
+            appendFileSync(join(seen.dir, "update.log"), `${new Date().toISOString()} ${logLine(result, deps.version)}\n`);
+        }
+        catch {
+            // the agent's log is a courtesy; the outcome is already decided
+        }
+    }
+    return result;
+}
+function decide(deps, seen) {
+    try {
+        const platform = deps.platform ?? process.platform;
+        let program;
+        let agent;
+        if (platform === "darwin") {
+            agent = launchAgentPath(deps.home);
+            if (!existsSync(agent))
+                return { action: "skipped", reason: "no_agent" };
+            program = plistProgram(readFileSync(agent, "utf8"));
+        }
+        else if (platform === "linux") {
+            agent = systemdUnitPaths(deps.home).service;
+            if (!existsSync(agent))
+                return { action: "skipped", reason: "no_agent" };
+            program = unitProgram(readFileSync(agent, "utf8"));
+        }
+        else {
+            return { action: "skipped", reason: "unsupported_platform" };
+        }
+        if (program === null)
+            return { action: "skipped", reason: "agent_unrecognized" };
+        seen.dir = program.dir;
+        const from = real(program.cli);
+        if (from !== null && from === real(deps.self))
+            return { action: "skipped", reason: "already_current" };
+        // A program that no longer exists runs nothing, so any working copy is better. One that exists
+        // moves only when it is a catalyst CLI older than this one.
+        let fromVersion = null;
+        if (from !== null) {
+            fromVersion = cliVersionAt(program.cli);
+            if (fromVersion === null)
+                return { action: "skipped", reason: "agent_cli_unrecognized" };
+            if (compareVersions(fromVersion, deps.version) >= 0)
+                return { action: "skipped", reason: "agent_cli_not_older" };
+        }
+        const canWrite = deps.canWrite ?? writable;
+        const files = platform === "linux" ? [agent, systemdUnitPaths(deps.home).timer].filter((f) => existsSync(f)) : [agent];
+        if (![...files, dirname(agent)].every(canWrite))
+            return { action: "skipped", reason: "agent_not_writable", agent };
+        // launchctl bootout stops a running job, and the daily job starts on the same quarter hour as the
+        // agent does: wait for an update in progress to finish rather than cut it off.
+        if (platform === "darwin" && !waitIdle(deps))
+            return { action: "skipped", reason: "agent_busy" };
+        const original = readFileSync(agent);
+        const backup = `${agent}.before-${deps.version}`;
+        copyFileSync(agent, backup);
+        let status;
+        try {
+            status = enableAutoUpdate({
+                platform,
+                home: deps.home,
+                uid: deps.uid,
+                cli: deps.self,
+                path: scheduledPath(deps.self, deps.nodeExecutable, program.path ?? deps.env.PATH),
+                claude: program.claude ?? resolveClaude(deps.home, deps.env),
+                run: deps.run,
+            }, program.dir);
+        }
+        finally {
+            // A repoint that did not take puts the agent back exactly as it was, and leaves no backup.
+            if (status?.state !== "on")
+                restore(deps, platform, agent, original, backup);
+        }
+        if (status.state !== "on")
+            return { action: "failed", detail: status.detail };
+        return { action: "repointed", from: program.cli, fromVersion, to: deps.self, backup };
+    }
+    catch (err) {
+        return { action: "failed", detail: (err instanceof Error ? err.message : String(err)).slice(0, 160) };
+    }
+}
+/** One line for the person, or null when there is nothing to say. */
+export function repointLine(result, version) {
+    if (result.action === "repointed")
+        return `catalyst: the runner update agent now runs ${result.to} (${version}) instead of ${result.from} (${result.fromVersion ?? "missing"}). The previous agent file is kept at ${result.backup}.`;
+    if (result.action === "skipped" && result.reason === "agent_not_writable")
+        return `catalyst: the runner update agent at ${result.agent} runs an older catalyst, and this install cannot change it. Ask whoever installed it to run: catalyst runner auto-update on`;
+    if (result.action === "skipped" && result.reason === "agent_busy")
+        return "catalyst: the runner update agent was busy updating, so it keeps its current catalyst until the next install. Or run: catalyst runner auto-update on";
+    if (result.action === "failed")
+        return `catalyst: could not point the runner update agent at this install (${result.detail}). Run: catalyst runner auto-update on`;
+    return null;
+}
+/** The update.log line for any outcome: the person's line, or for a quiet skip, its reason. */
+export function logLine(result, version) {
+    return repointLine(result, version) ?? `catalyst ${version}: the runner update agent was left as it is (${result.action === "skipped" ? result.reason : result.action}).`;
+}
+/** npm's postinstall, for a global install: this install's own command, version and node. */
+export function postinstallRepoint(env = process.env) {
+    const version = readManifest().version;
+    const linked = env.npm_config_prefix ? join(env.npm_config_prefix, "bin", "catalyst") : null;
+    const self = linked !== null && existsSync(linked) ? linked : fileURLToPath(new URL("../bin/catalyst.js", import.meta.url));
+    const home = env.HOME;
+    if (!home)
+        return null;
+    return repointLine(repointAgent({ home, self, version, nodeExecutable: process.execPath, env }), version);
+}

package/dist/args.js

@@ -91,6 +91,14 @@ export const FLAG_TABLES = {
             value: false,
             help: "print setup in plain text, without colour or the Catalyst Cloud mark",
         },
+        "no-shell-hook": {
+            value: false,
+            help: "do not add the Codex launch hooks: the codex function in ~/.zshrc and ~/.bashrc, and on macOS the dev.catalystcloud.codex-attribution LaunchAgent",
+        },
+        "remove-codex-attribution": {
+            value: false,
+            help: "remove the Codex launch hooks setup added (each rc file goes back to what it was), unload and delete the LaunchAgent, and take its attributes out of the launch environment; runs nothing else",
+        },
         "resume-from": {
             value: true,
             help: "resume at a verified onboarding step",
@@ -527,6 +535,21 @@ export const FLAG_TABLES = {
     work: {
         team: { value: true, help: "available: one team's key (default: every team in the workspace contract)" },
     },
+    "codex-env": {
+        print: {
+            value: false,
+            help: "print the OTEL_RESOURCE_ATTRIBUTES value a Codex launch should carry: the attributes already set, plus the coding account's slot and this machine's short name",
+        },
+        apply: {
+            value: false,
+            help: "macOS: set that value with launchctl for apps started from now on, the Codex desktop app included, for the default Codex home",
+        },
+        refresh: {
+            value: false,
+            help: "fetch this workspace's coding accounts now and update the cache --print and --apply read",
+        },
+        "codex-home": { value: true, help: "print: the Codex home to read (default: $CODEX_HOME, else ~/.codex)" },
+    },
     repo: {
         reason: { value: true, help: "pause: required; resume: optional; 1 to 500 characters after trimming (owner or admin)" },
         write: {
@@ -584,7 +607,7 @@ export const VERB_USAGE = {
     update: "update [--check] [--project <absolute path>] [--dir <runner directory>] | update sdk --project <absolute path> | update policy [<component> on|off] | update policy sdk on|off --project <absolute path> | update policy windows <HH:MM,...>|default [--time-zone <zone>] [--json]   (components: runner, supervisor, watchdog, cli, skills-cloud, skills-dev, replica)",
     setup: "setup [onboard options]   (sets up Catalyst step by step; same as catalyst onboard) | setup --engine <file> --engine-sha256 <hex> [-- <install options>]   (run by install.sh; install.sh --help lists the options)",
     login: "login [--base-url <url>] [--start-replica]   (keyless; or --key <personal-key> / CATALYST_CLOUD_TOKEN)",
-    onboard: "onboard [--team <ID|key>] [--repo <owner/name>]... [--coding-account <slot>] [--resume-from <step>] [--only <step>] [--local-sync] [--remove-local-data] [--runner|--no-runner] [--no-color] [--yes] [--dry-run] [--json] | onboard --headless [--key-file <path>] [--team ...] [--repo ...]... [--coding-account ...] [--runner yes|no] [--remove-local-data] [--json]",
+    onboard: "onboard [--team <ID|key>] [--repo <owner/name>]... [--coding-account <slot>] [--resume-from <step>] [--only <step>] [--local-sync] [--remove-local-data] [--runner|--no-runner] [--no-shell-hook] [--no-color] [--yes] [--dry-run] [--json] | onboard --remove-codex-attribution [--json] | onboard --headless [--key-file <path>] [--team ...] [--repo ...]... [--coding-account ...] [--runner yes|no] [--remove-local-data] [--json]",
     install: "install [--skills-dir <dir>] [--force]",
     status: "status",
     notice: "notice",
@@ -615,6 +638,7 @@ export const VERB_USAGE = {
     capabilities: "capabilities [--json]",
     project: "project <list [--json] | wip-limit <get|set <n>|set default> [--team K] [--json]>",
     lease: "lease <take <ticket> --agent <seat> [--ttl <minutes>] | renew <ticket> (--commit <sha>|--artifact <path or id>|--finding <id>|--pr <number>) [--note <text>] [--agent <seat>] [--generation <n>] | release <ticket> [--agent <seat>] [--generation <n>] | show <ticket>> [--json]   (a seat's ticket lease: take, renew with new progress, release, read; needs login)",
+    "codex-env": "codex-env --print [--codex-home <dir>] | --apply | --refresh [--json]   (the telemetry attributes naming the coding account and machine a Codex launch runs as; only --refresh waits on the network)",
     work: "work available [--team K] [--json]   (per team: tickets nobody holds, with the last holder and progress, and open pull requests no live lease covers, drafts included)",
     repo: "repo <status|pause <owner/name> --reason <text>|resume <owner/name> [--reason <text>]|agents-block <path> [--write]|agent-setup <path> [--apply] [--with-check]> [--json]   (status: visible workspace repositories; agents-block/agent-setup: local checkout)",
     legacy: "legacy [--remove [--data] [--yes]] [--json]",

package/dist/capabilities.js

@@ -48,6 +48,8 @@ export const CAPABILITIES = [
     { verb: "var set|import", does: "enter plain environment variable values from this terminal, never echoed", needs: "admin", routes: [], since: "0.13.2" },
     { verb: "env import", does: "store this computer's values for the names .catalyst/catalyst.toml declares, never printed", needs: "admin", routes: [], since: "0.16.20" },
     { verb: "accounts", does: "read the workspace's coding accounts and which can take work", needs: "member", routes: [], since: "0.5.0" },
+    { verb: "codex-env", does: "name the coding account and the machine on every Codex launch's telemetry: print the attributes, set them for apps on macOS, or refresh the account cache", needs: "member", routes: [], since: "0.16.33" },
+    { verb: "setup --remove-codex-attribution", does: "take out the Codex launch hooks setup adds: the codex function in the shell rc files, and on macOS the login agent and the attributes it set", needs: "member", routes: [], since: "0.16.34" },
     { verb: "explain|running|queue|history", does: "read why a ticket runs or waits, what runs now, and what is queued", needs: "member", routes: [], since: "0.1.0" },
     { verb: "write comment|state|label|create|reaction|attachment|session", does: "act on a ticket as the person, through the agent proxy", needs: "member", routes: [agent("POST", "issue-comment"), agent("POST", "issue-state"), agent("POST", "issue-label"), agent("POST", "issue-create")], since: "0.1.0" },
     { verb: "ask raise|accept|list", does: "raise a decision to a human, or answer one", needs: "member", routes: [agent("POST", "ask"), agent("POST", "ask-accept")], since: "0.1.0" },

package/dist/cli.js

@@ -8,9 +8,9 @@ import { createSetupRenderer, setupBanner, } from "./setup-render.js";
 import { existsSync, openSync, closeSync } from "node:fs";
 import { ReadStream as TerminalInput } from "node:tty";
 import { Writable } from "node:stream";
-import { parseArgs, positionals, verbHelp } from "./args.js";
+import { flagBool, parseArgs, positionals, verbHelp } from "./args.js";
 import { reportCliVersion } from "./cli-version.js";
-import { CONFIG_MODE, DEFAULT_BASE_URL, LEGACY_PACKAGE_NAME, PACKAGE_NAME, cliPath, configPathFor, contractPathFor, defaultCtx, defaultReplicaDbFor, defaultSkillsDirFor, formatMode, installerOwnsSkills, INSTALL_COMMAND, loadConfig, modernCliPath, normalizeBaseUrl, readManifest, requireConfig, saveConfig, writeConfig, } from "./config.js";
+import { CONFIG_MODE, DEFAULT_BASE_URL, LEGACY_PACKAGE_NAME, PACKAGE_NAME, cliPath, configPathFor, contractPathFor, defaultCtx, defaultReplicaDbFor, defaultSkillsDirFor, formatMode, loadConfig, modernCliPath, normalizeBaseUrl, readManifest, requireConfig, saveConfig, writeConfig, } from "./config.js";
 import { loadContract, pickPath } from "./contract.js";
 import { CliError, MeError, UsageError } from "./errors.js";
 import { fetchMe } from "./transport.js";
@@ -50,6 +50,8 @@ import { cmdProject } from "./project.js";
 import { cmdRepo } from "./repo.js";
 import { cmdLease, cmdWork } from "./lease.js";
 import { cmdLegacy } from "./legacy.js";
+import { cmdCodexEnv } from "./codex-env.js";
+import { codexAttributionAfterSetup, codexAttributionStatusLine, removeCodexAttribution, } from "./codex-attribution.js";
 import { cmdIdentity } from "./identity.js";
 import { cmdMessages } from "./messages.js";
 import { cmdConnections } from "./connections.js";
@@ -85,7 +87,8 @@ export function usageText() {
         "  catalyst login --key <personal-key> [--base-url <url>]   (or CATALYST_CLOUD_TOKEN, for a key)",
         "  catalyst join ...   (deprecated alias of login; removed in the next minor version)",
         "  catalyst install [--skills-dir <dir>] [--force]   (repair path; your agent's own command installs the skills)",
-        "  catalyst onboard [--resume-from <step>] [--only <step>] [--runner|--no-runner] [--yes] [--dry-run] [--json]",
+        "  catalyst onboard [--resume-from <step>] [--only <step>] [--runner|--no-runner] [--no-shell-hook] [--yes] [--dry-run] [--json]",
+        "  catalyst setup --remove-codex-attribution   (take out the Codex launch hook and login agent setup added)",
         `  catalyst ${SETUP_USAGE}`,
         "  catalyst status | notice | me | ready | accounts",
         "  catalyst seat checkout --size big|med --harness claude,codex,opencode [--session-id ID] [--stage STAGE]",
@@ -119,6 +122,7 @@ export function usageText() {
         "  catalyst repo <agents-block <path> [--write]|agent-setup <path> [--apply] [--with-check]>   (a checkout's AGENTS.md block and portable agent layout; working tree only)",
         "  catalyst lease <take <ticket> --agent <seat> [--ttl <minutes>]|renew <ticket> --commit|--artifact|--finding|--pr <ref> [--note <text>]|release <ticket>|show <ticket>> [--json]   (a seat's ticket lease; needs login)",
         "  catalyst work available [--team K] [--json]   (tickets nobody holds and open pull requests no lease covers)",
+        "  catalyst codex-env --print [--codex-home <dir>] | --apply | --refresh   (the telemetry attributes naming the coding account and machine a Codex launch runs as)",
         "  catalyst legacy [--remove [--data] [--yes]]   (leftovers of the old local Catalyst runtime: list them; remove them only on a yes)",
         "  catalyst identity linear <status|options|set> [<linearUserId>] [--json]",
         "  catalyst messages read --ticket CTC-N [--since SEQUENCE] [--json]   (messages sent to a ticket on your teams)",
@@ -183,10 +187,7 @@ function migrateLegacyCliPath(ctx) {
         // Best effort: the old launcher still works, it only prints the notice.
     }
 }
-/**
- * The Tier-2 update path: when the bundle on disk is newer than the version the config last
- * recorded, refresh the copied skills FIRST and record the new version only once that succeeded.
- */
+/** Announce a new CLI bundle without changing approved skills. */
 function maybePrintUpdateNotice(args, ctx) {
     const say = HUMAN_VERBS.has(args.command ?? "") ? ctx.stdout : ctx.stderr;
     let cfg;
@@ -199,46 +200,16 @@ function maybePrintUpdateNotice(args, ctx) {
     if (!cfg)
         return;
     const manifest = readManifest();
-    if (cfg.lastSkillBundleVersion === manifest.version)
-        return;
-    // CTC-6741: a newer CLI selected by `catalyst update` records its own bundle here, and the older
-    // npm-installed one still runs for `catalyst runtime`. Copied skills only ever move forward.
-    if (cfg.lastSkillBundleVersion && semverOlder(manifest.version, cfg.lastSkillBundleVersion))
-        return;
     const previous = cfg.lastSkillBundleVersion;
-    if (previous) {
-        const entry = parseChangelogEntry(readChangelog(), manifest.version);
-        say(updateNoticeLine(previous, manifest.version, entry));
-    }
-    if (installerOwnsSkills(ctx.home, ctx.env)) {
-        cfg.lastSkillBundleVersion = manifest.version;
-        try {
-            saveConfig(ctx.home, cfg);
-        }
-        catch {
-            // Best effort: the notice prints again next time, and nothing else depends on it.
-        }
+    if (previous === manifest.version || previous && semverOlder(manifest.version, previous))
         return;
-    }
-    const skillsDir = resolveSkillsDir(args, ctx, cfg);
-    let refreshed;
+    if (previous)
+        say(updateNoticeLine(previous, manifest.version, parseChangelogEntry(readChangelog(), manifest.version)));
+    cfg.lastSkillBundleVersion = manifest.version;
     try {
-        refreshed = installSkills(skillsDir, { force: false, onlyExisting: true });
-    }
-    catch (err) {
-        ctx.stderr(`[catalyst] could not refresh the skills at ${skillsDir} (${err instanceof Error ? err.message : String(err)}) — the ${manifest.version} skills are not installed yet; re-run the install command: ${INSTALL_COMMAND}`);
-        return;
-    }
-    if (refreshed.installed.length > 0)
-        say(`[catalyst] refreshed ${refreshed.installed.join(", ")} at ${skillsDir} to ${manifest.version}`);
-    if (refreshed.removed.length > 0)
-        say(`[catalyst] removed retired skills ${refreshed.removed.join(", ")} from ${skillsDir}; their work moved into the skills this bundle ships`);
-    for (const s of refreshed.skipped) {
-        say(`[catalyst] left "${s.name}" alone: ${skillsDir}/${s.name} was not installed by this package (catalyst install --force to replace)`);
+        saveConfig(ctx.home, cfg);
     }
-    cfg.lastSkillBundleVersion = manifest.version;
-    cfg.skillsDir = skillsDir;
-    saveConfig(ctx.home, cfg);
+    catch { /* The notice can repeat on the next ordinary command. */ }
 }
 export async function main(argv, ctx = defaultCtx(), deps = {}) {
     // CTC-4625: setup passes the install options through to its engine untouched, so they never meet
@@ -305,7 +276,7 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
         }),
     };
     try {
-        if (args.command !== "onboard") {
+        if (args.command !== "onboard" && !(flagBool(args, "check") && (args.command === "update" || args.command === "runner"))) {
             migrateLegacyCliPath(ctx);
             maybePrintUpdateNotice(args, ctx);
         }
@@ -323,6 +294,19 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                         throw new UsageError(`--${flag} needs --headless`);
                 if (typeof args.flags.runner === "string" && !onboardHeadlessRequested(args, ctx.env))
                     throw new UsageError("--runner yes|no needs --headless; use --runner or --no-runner interactively");
+                // The Codex launch hooks' removal runs on its own, with no onboarding around it.
+                if (args.flags["remove-codex-attribution"] === true) {
+                    if (args.flags["dry-run"] === true)
+                        throw new UsageError("--remove-codex-attribution changes files; run it without --dry-run");
+                    deps.setupUi?.dispose();
+                    const removal = removeCodexAttribution(ctx, deps.codexAttribution);
+                    if (args.json)
+                        ctx.stdout(JSON.stringify({ removed: removal.ok, files: removal.files, agent: removal.agent }));
+                    else
+                        for (const line of removal.lines)
+                            ctx.stdout(line);
+                    return removal.ok ? 0 : 1;
+                }
                 // Headless runs drop the terminal UI, browser sign-in and every browser action (CTC-4633).
                 const runOnboard = async (args, ctx, headless) => {
                     let ui = headless ? undefined : deps.setupUi;
@@ -485,6 +469,8 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                     }
                     for (const line of jsonLines)
                         ctx.stdout(line);
+                    // The Codex launch hooks follow every full run, done or waiting, and never change its exit code.
+                    codexAttributionAfterSetup(args, ctx, deps.codexAttribution);
                     return code;
                 };
                 if (!onboardHeadlessRequested(args, ctx.env))
@@ -497,7 +483,7 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
             case "notice":
                 return 0;
             case "status":
-                return cmdStatus(ctx);
+                return cmdStatus(ctx, deps);
             case "me":
                 return await cmdMe(args, ctx);
             case "contract":
@@ -564,6 +550,8 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                 return await cmdWork(args, ctx);
             case "legacy":
                 return await cmdLegacy(args, ctx, { localSyncSelected: savedLocalSync(ctx), ...deps.legacy });
+            case "codex-env":
+                return await cmdCodexEnv(args, ctx, deps.codexEnv ?? {});
             case "identity":
                 return await cmdIdentity(args, ctx, deps.identity ?? {});
             case "messages":
@@ -643,6 +631,7 @@ const VERB_HELP_KNOWN = Object.fromEntries([
     "lease",
     "work",
     "legacy",
+    "codex-env",
     "onboard",
     "update",
 ].map((v) => [v, true]));
@@ -852,7 +841,7 @@ function cmdInstall(args, ctx) {
         ctx.stdout(`Removed retired skills from ${skillsDir}: ${result.removed.join(", ")}`);
     return 0;
 }
-function cmdStatus(ctx) {
+function cmdStatus(ctx, deps = {}) {
     const manifest = readManifest();
     const cfg = loadConfig(ctx.home);
     if (!cfg) {
@@ -871,6 +860,7 @@ function cmdStatus(ctx) {
     if (cfg.cliPath)
         ctx.stdout(`CLI: ${cfg.cliPath}${existsSync(cfg.cliPath) ? "" : " (missing — re-run login)"}`);
     ctx.stdout(`Contract: ${existsSync(contractPathFor(ctx.home)) ? contractPathFor(ctx.home) : "not cached (run: catalyst contract --refresh)"}`);
+    ctx.stdout(codexAttributionStatusLine(ctx, deps.codexAttribution));
     return 0;
 }
 /** A short human relative time for an ISO expiry, e.g. "in 14m", "in 2h", "in 6d", or "now" once past. */