@catalyst-cloud/cli 0.16.33 → 0.16.34

package/dist/codex-attribution.js

@@ -0,0 +1,685 @@
+// codex-attribution.ts: the launch hooks `catalyst setup` installs around `catalyst codex-env`, so
+// every Codex launch on this machine names the coding account it runs as.
+//
+//   A terminal launch: one marked block in ~/.zshrc and ~/.bashrc defines a `codex` function. It asks
+//   `catalyst codex-env --print` about the Codex home in effect and exports the answer for that one
+//   call only.
+//   A Dock launch (macOS): the dev.catalystcloud.codex-attribution LaunchAgent runs
+//   `catalyst codex-env --apply` at login and whenever the default Codex home's login file changes.
+//
+// Which rc files: ~/.zshrc ($ZDOTDIR/.zshrc when ZDOTDIR is set) and ~/.bashrc, each only when it
+// exists or is the rc file of the login shell ($SHELL). A zsh-only Mac never gains a ~/.bashrc.
+// A file that defines `codex` itself (a function or an alias outside the block) is never written,
+// and neither is a link to a file outside the home folder. Files are read and written as latin1, so
+// every byte outside the block survives exactly, CRLF included.
+//
+// Nothing is installed when Codex is not on this computer (codexPresence); a later run adds it.
+//
+// Removal puts each file back byte for byte: the block records inside itself whether setup created
+// the file or added a line break before it. It unloads and deletes the agent, and takes back out of
+// the launch environment exactly the two attributes `--apply` sets (`codex-env --apply` keeps every
+// other pair already there, so removal does too).
+import { accessSync, chmodSync, constants, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { userInfo } from "node:os";
+import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep, } from "node:path";
+import { ACCOUNT_SLOT_ATTRIBUTE, HOST_NAME_ATTRIBUTE, attrValue, defaultCodexHome, readCodexAccountId, readCodexAccountsCache, resolveSlot, } from "./codex-env.js";
+import { configDirFor, loadConfig } from "./config.js";
+import { defaultRun, scheduledPath, writeFileAtomic, xml, } from "./runner-auto-update.js";
+export const CODEX_ATTRIBUTION_LABEL = "dev.catalystcloud.codex-attribution";
+export const BLOCK_BEGIN = "# >>> catalyst codex attribution >>>";
+export const BLOCK_END = "# <<< catalyst codex attribution <<<";
+/** Written into the block when setup created the file for it, so removal deletes the file again. */
+export const CREATED_NOTE = "# (setup created this file for the block; removing the block deletes the file)";
+/** Written when the file did not end in a line break, so removal takes back the one setup added. */
+export const NEWLINE_NOTE = "# (setup added the line break before this block; removing the block takes it back)";
+const ENV_NAME = "OTEL_RESOURCE_ATTRIBUTES";
+const defaultFileOps = {
+    writeFile: (path, data, options) => writeFileSync(path, data, options),
+    rename: renameSync,
+    unlink: unlinkSync,
+};
+const fileOps = (deps) => ({
+    ...defaultFileOps,
+    ...deps.files,
+});
+/** A temp file beside the target with the target's mode set past the umask, then a rename over the
+ *  target (never over a link that names it). A failure removes the temp file, so the target is
+ *  either as it was or wholly new. */
+export function writeRcAtomic(path, data, mode, ops = defaultFileOps) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temp = `${path}.${process.pid}.tmp`;
+    try {
+        ops.writeFile(temp, data, { mode });
+        chmodSync(temp, mode);
+        ops.rename(temp, path);
+    }
+    catch (err) {
+        try {
+            unlinkSync(temp);
+        }
+        catch {
+            // The temp file was never created.
+        }
+        throw err;
+    }
+}
+/** The desktop app's bundle name. */
+export const CODEX_APP_BUNDLE = "Codex.app";
+/** The block, always ending in one line break. The function runs the real codex with `command`. */
+export function codexBlock(notes = {}) {
+    return [
+        BLOCK_BEGIN,
+        ...(notes.created ? [CREATED_NOTE] : []),
+        ...(notes.newlineAdded ? [NEWLINE_NOTE] : []),
+        "# Added by catalyst setup: each codex launch names the coding account it runs as.",
+        "# Remove it with: catalyst setup --remove-codex-attribution",
+        "function codex {",
+        "  local catalyst_attributes",
+        '  catalyst_attributes="$(command catalyst codex-env --print --codex-home "${CODEX_HOME:-$HOME/.codex}" 2>/dev/null)" || catalyst_attributes=""',
+        '  if [ -n "$catalyst_attributes" ]; then',
+        '    OTEL_RESOURCE_ATTRIBUTES="$catalyst_attributes" command codex "$@"',
+        "  else",
+        '    command codex "$@"',
+        "  fi",
+        "}",
+        BLOCK_END,
+        "",
+    ].join("\n");
+}
+function linesOf(text) {
+    const out = [];
+    let start = 0;
+    while (start < text.length) {
+        const nl = text.indexOf("\n", start);
+        const end = nl === -1 ? text.length : nl + 1;
+        out.push({
+            start,
+            end,
+            text: text.slice(start, nl === -1 ? end : nl).replace(/\r$/, ""),
+        });
+        start = end;
+    }
+    return out;
+}
+/** Every complete block in order, or "malformed" when a marker has no partner. */
+export function findBlocks(text) {
+    const blocks = [];
+    let open = null;
+    for (const line of linesOf(text)) {
+        if (open === null) {
+            if (line.text === BLOCK_BEGIN)
+                open = { start: line.start, notes: new Set() };
+            else if (line.text === BLOCK_END)
+                return "malformed";
+            continue;
+        }
+        if (line.text === BLOCK_BEGIN)
+            return "malformed";
+        if (line.text === BLOCK_END) {
+            blocks.push({
+                start: open.start,
+                end: line.end,
+                created: open.notes.has(CREATED_NOTE),
+                newlineAdded: open.notes.has(NEWLINE_NOTE),
+            });
+            open = null;
+            continue;
+        }
+        open.notes.add(line.text);
+    }
+    return open === null ? blocks : "malformed";
+}
+function outsideBlocks(text, blocks) {
+    let out = "";
+    let cursor = 0;
+    for (const b of blocks) {
+        out += text.slice(cursor, b.start);
+        cursor = b.end;
+    }
+    return out + text.slice(cursor);
+}
+/** `alias codex=…` (zsh's `alias -g` too), `codex()` and `function codex`. Never `codex_helper` or a comment. */
+const CODEX_DEFINITIONS = [
+    /^\s*alias(?:\s+-\S+)*\s+(?:\S+\s+)*codex=/,
+    /^\s*function\s+codex(?:\s*\(\s*\))?(?=[\s{]|$)/,
+    /^\s*codex\s*\(\s*\)/,
+];
+export function definesCodex(text) {
+    return linesOf(text).some(({ text: line }) => !/^\s*#/.test(line) && CODEX_DEFINITIONS.some((re) => re.test(line)));
+}
+function present(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function shellRcFiles(ctx) {
+    const zdot = ctx.env.ZDOTDIR?.trim();
+    const login = basename(ctx.env.SHELL?.trim() ?? "");
+    const files = [
+        ["zsh", join(zdot && isAbsolute(zdot) ? zdot : ctx.home, ".zshrc")],
+        ["bash", join(ctx.home, ".bashrc")],
+    ];
+    return files.map(([shell, path]) => ({
+        shell,
+        path,
+        wanted: present(path) || login === shell,
+    }));
+}
+function realOr(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+function inside(path, home) {
+    const rel = relative(realOr(home), path);
+    return (rel !== "" &&
+        rel !== ".." &&
+        !rel.startsWith(`..${sep}`) &&
+        !isAbsolute(rel));
+}
+function sameHome(a, b) {
+    return realOr(a) === realOr(b);
+}
+/** Whether HOME is this account's own home folder. A test or a borrowed HOME is not. */
+export function ownsHome(home, deps = {}) {
+    return sameHome(home, (deps.realHome ?? (() => userInfo().homedir))());
+}
+/** A link is followed only to a file inside the home folder; the file it names is the one written. */
+function rcTarget(path, home) {
+    let link;
+    try {
+        link = lstatSync(path);
+    }
+    catch {
+        return { kind: "missing" };
+    }
+    let target = path;
+    if (link.isSymbolicLink()) {
+        try {
+            target = realpathSync(path);
+        }
+        catch {
+            return {
+                kind: "skip",
+                why: "it is a link to a file that does not exist",
+            };
+        }
+        if (!inside(target, home))
+            return {
+                kind: "skip",
+                why: `it is a link to ${target}, outside your home folder, which setup does not write`,
+            };
+    }
+    const stat = statSync(target);
+    if (!stat.isFile())
+        return { kind: "skip", why: "it is not a regular file" };
+    return { kind: "file", target, mode: stat.mode & 0o7777 };
+}
+const message = (err) => err instanceof Error ? err.message : String(err);
+/** One file: add the block, replace it in place (a second copy is dropped), or leave the file alone.
+ *  Null when the file does not exist and setup has no reason to create it. */
+export function installShellHook(file, home, ops = defaultFileOps) {
+    const where = rcTarget(file.path, home);
+    if (where.kind === "skip")
+        return { path: file.path, state: "skipped", why: where.why };
+    if (where.kind === "missing") {
+        if (!file.wanted)
+            return null;
+        writeRcAtomic(file.path, codexBlock({ created: true }), 0o644, ops);
+        return { path: file.path, state: "added" };
+    }
+    const before = readFileSync(where.target, "latin1");
+    const blocks = findBlocks(before);
+    if (blocks === "malformed")
+        return {
+            path: file.path,
+            state: "skipped",
+            why: `it has a "${BLOCK_BEGIN}" or "${BLOCK_END}" line without its partner; fix or delete that line, then run catalyst setup again`,
+        };
+    if (definesCodex(outsideBlocks(before, blocks)))
+        return {
+            path: file.path,
+            state: "skipped",
+            why: "it already defines codex itself, as a function or an alias. To use the hook, remove that definition and run catalyst setup again",
+        };
+    let after;
+    const first = blocks[0];
+    if (first === undefined) {
+        after =
+            before === "" || before.endsWith("\n")
+                ? before + codexBlock()
+                : `${before}\n${codexBlock({ newlineAdded: true })}`;
+    }
+    else {
+        after =
+            before.slice(0, first.start) +
+                codexBlock({ created: first.created, newlineAdded: first.newlineAdded });
+        let cursor = first.end;
+        for (const b of blocks.slice(1)) {
+            after += before.slice(cursor, b.start);
+            cursor = b.end;
+        }
+        after += before.slice(cursor);
+    }
+    if (after === before)
+        return { path: file.path, state: "unchanged" };
+    writeRcAtomic(where.target, Buffer.from(after, "latin1"), where.mode, ops);
+    return { path: file.path, state: first === undefined ? "added" : "replaced" };
+}
+/** One file: take every block out. Null when the file has none. */
+export function removeShellHook(path, home, ops = defaultFileOps) {
+    let link;
+    try {
+        link = lstatSync(path);
+    }
+    catch {
+        return null;
+    }
+    let target = path;
+    if (link.isSymbolicLink()) {
+        try {
+            target = realpathSync(path);
+        }
+        catch {
+            return null;
+        }
+        if (!inside(target, home)) {
+            let text = "";
+            try {
+                text = readFileSync(target, "latin1");
+            }
+            catch {
+                return null;
+            }
+            return text.includes(BLOCK_BEGIN)
+                ? {
+                    path,
+                    state: "skipped",
+                    why: `it is a link to ${target}, outside your home folder; remove the block from that file yourself`,
+                }
+                : null;
+        }
+    }
+    const stat = statSync(target);
+    if (!stat.isFile())
+        return null;
+    const before = readFileSync(target, "latin1");
+    const blocks = findBlocks(before);
+    if (blocks === "malformed")
+        return {
+            path,
+            state: "skipped",
+            why: `it has a "${BLOCK_BEGIN}" or "${BLOCK_END}" line without its partner; remove the block yourself`,
+        };
+    if (blocks.length === 0)
+        return null;
+    let after = before;
+    let created = false;
+    for (const b of [...blocks].reverse()) {
+        let start = b.start;
+        // The break setup added belongs to the block only while the block still ends the file.
+        if (b.newlineAdded &&
+            b.end === after.length &&
+            start > 0 &&
+            after[start - 1] === "\n")
+            start -= 1;
+        after = after.slice(0, start) + after.slice(b.end);
+        created ||= b.created;
+    }
+    if (created && after === "")
+        ops.unlink(target);
+    else
+        writeRcAtomic(target, Buffer.from(after, "latin1"), stat.mode & 0o7777, ops);
+    return { path, state: "removed" };
+}
+function hasBlock(path) {
+    try {
+        const blocks = findBlocks(readFileSync(path, "latin1"));
+        return blocks !== "malformed" && blocks.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+export function codexAgentPlistPath(home) {
+    return join(home, "Library", "LaunchAgents", `${CODEX_ATTRIBUTION_LABEL}.plist`);
+}
+/** The default Codex home's login file: the agent runs again whenever it changes. */
+export function codexLoginWatchPath(home) {
+    return join(home, ".codex", "auth.json");
+}
+export function codexAgentPlist(o) {
+    const log = join(configDirFor(o.home), "codex-attribution.log");
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+        '<plist version="1.0"><dict>',
+        `<key>Label</key><string>${CODEX_ATTRIBUTION_LABEL}</string>`,
+        `<key>ProgramArguments</key><array>${[o.cli, "codex-env", "--apply"].map((a) => `<string>${xml(a)}</string>`).join("")}</array>`,
+        `<key>EnvironmentVariables</key><dict><key>PATH</key><string>${xml(o.path)}</string><key>HOME</key><string>${xml(o.home)}</string></dict>`,
+        "<key>RunAtLoad</key><true/>",
+        `<key>WatchPaths</key><array><string>${xml(codexLoginWatchPath(o.home))}</string></array>`,
+        "<key>ProcessType</key><string>Background</string>",
+        `<key>StandardOutPath</key><string>${xml(log)}</string>`,
+        `<key>StandardErrorPath</key><string>${xml(log)}</string>`,
+        "</dict></plist>",
+        "",
+    ].join("\n");
+}
+function resolved(ctx, deps) {
+    const cli = deps.cli ?? resolve(process.argv[1] ?? "catalyst");
+    return {
+        platform: deps.platform ?? process.platform,
+        run: deps.run ?? defaultRun,
+        uid: deps.uid ?? process.getuid?.() ?? 0,
+        cli,
+        path: deps.path ?? scheduledPath(cli, process.execPath, ctx.env.PATH),
+    };
+}
+const readOr = (path) => {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+};
+/** Write, load and verify the agent, as the runner update agent does. An unchanged, loaded agent is left running. */
+export function installCodexAgent(ctx, deps = {}) {
+    const d = resolved(ctx, deps);
+    if (d.platform !== "darwin")
+        return { state: "not_macos" };
+    if (!ownsHome(ctx.home, deps))
+        return { state: "other_home" };
+    const path = codexAgentPlistPath(ctx.home);
+    const text = codexAgentPlist({ cli: d.cli, path: d.path, home: ctx.home });
+    const target = `gui/${d.uid}/${CODEX_ATTRIBUTION_LABEL}`;
+    const loaded = () => d.run("launchctl", ["print", target]).status === 0;
+    const wasLoaded = loaded();
+    if (readOr(path) === text && wasLoaded)
+        return { state: "unchanged", path };
+    try {
+        if (wasLoaded)
+            d.run("launchctl", ["bootout", target]);
+        // launchd opens the log itself and starts nothing when its folder is missing.
+        mkdirSync(configDirFor(ctx.home), { recursive: true });
+        writeFileAtomic(path, text);
+    }
+    catch (err) {
+        return {
+            state: "failed",
+            detail: `could not write ${path}: ${message(err)}`,
+        };
+    }
+    const boot = d.run("launchctl", ["bootstrap", `gui/${d.uid}`, path]);
+    if (boot.status !== 0)
+        return {
+            state: "failed",
+            detail: `launchctl bootstrap exited ${boot.status}: ${boot.stderr.trim().slice(0, 160)}`,
+        };
+    if (!loaded())
+        return {
+            state: "failed",
+            detail: `launchd did not keep ${CODEX_ATTRIBUTION_LABEL} loaded`,
+        };
+    // RunAtLoad already starts it; a busy Mac can hold that start back (runner-auto-update.ts), so ask once more.
+    d.run("launchctl", ["kickstart", target]);
+    return { state: "loaded", path };
+}
+/** The value with `--apply`'s two pairs taken out, and whether `--apply` had set them at all. */
+export function withoutAppliedAttributes(value) {
+    const pairs = value.split(",").filter((pair) => pair.trim() !== "");
+    const key = (pair) => (pair.includes("=") ? pair.slice(0, pair.indexOf("=")) : pair).trim();
+    return {
+        applied: pairs.some((pair) => key(pair) === ACCOUNT_SLOT_ATTRIBUTE),
+        rest: pairs
+            .filter((pair) => key(pair) !== ACCOUNT_SLOT_ATTRIBUTE &&
+            key(pair) !== HOST_NAME_ATTRIBUTE)
+            .join(","),
+    };
+}
+/** A value without the coding-account pair is not ours and stays as it is. */
+function undoLaunchEnvironment(run) {
+    const read = run("launchctl", ["getenv", ENV_NAME]);
+    const { applied, rest } = withoutAppliedAttributes(read.status === 0 ? read.stdout.trim() : "");
+    if (!applied)
+        return "untouched";
+    const done = rest === ""
+        ? run("launchctl", ["unsetenv", ENV_NAME])
+        : run("launchctl", ["setenv", ENV_NAME, rest]);
+    return done.status !== 0 ? "failed" : rest === "" ? "unset" : "kept_others";
+}
+export function removeCodexAgent(ctx, deps = {}) {
+    const d = resolved(ctx, deps);
+    if (d.platform !== "darwin")
+        return { agent: "not_macos", environment: "untouched" };
+    if (!ownsHome(ctx.home, deps))
+        return { agent: "other_home", environment: "untouched" };
+    const path = codexAgentPlistPath(ctx.home);
+    const target = `gui/${d.uid}/${CODEX_ATTRIBUTION_LABEL}`;
+    const loaded = () => d.run("launchctl", ["print", target]).status === 0;
+    const was = existsSync(path) || loaded();
+    if (was)
+        d.run("launchctl", ["bootout", target]);
+    // A loaded agent would set the value again, so the environment waits until it is gone.
+    if (loaded())
+        return {
+            agent: "failed",
+            detail: `it is still loaded: run launchctl bootout ${target}`,
+            environment: "untouched",
+        };
+    try {
+        if (existsSync(path))
+            fileOps(deps).unlink(path);
+    }
+    catch (err) {
+        return {
+            agent: "failed",
+            detail: `could not delete ${path}: ${message(err)}`,
+            environment: undoLaunchEnvironment(d.run),
+        };
+    }
+    return {
+        agent: was ? "removed" : "absent",
+        environment: undoLaunchEnvironment(d.run),
+    };
+}
+function tilde(path, home) {
+    const rel = relative(home, path);
+    return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel)
+        ? `~/${rel}`
+        : path;
+}
+function ageText(seconds) {
+    const plural = (n, unit) => `${n} ${unit}${n === 1 ? "" : "s"}`;
+    if (seconds < 60)
+        return "under a minute";
+    if (seconds < 3600)
+        return plural(Math.floor(seconds / 60), "minute");
+    if (seconds < 2 * 86400)
+        return plural(Math.floor(seconds / 3600), "hour");
+    return plural(Math.floor(seconds / 86400), "day");
+}
+/** `catalyst status`'s one line. Read only and offline: the cached account map, never a refresh. */
+export function codexAttributionStatusLine(ctx, deps = {}) {
+    const d = resolved(ctx, deps);
+    const hooked = shellRcFiles(ctx)
+        .filter((file) => hasBlock(file.path))
+        .map((file) => tilde(file.path, ctx.home));
+    const agent = d.platform !== "darwin"
+        ? null
+        : !existsSync(codexAgentPlistPath(ctx.home))
+            ? "not installed"
+            : d.run("launchctl", [
+                "print",
+                `gui/${d.uid}/${CODEX_ATTRIBUTION_LABEL}`,
+            ]).status === 0
+                ? "loaded"
+                : "not loaded";
+    const installed = hooked.length > 0 && (agent === null || agent === "loaded");
+    let workspace = null;
+    try {
+        workspace = loadConfig(ctx.home)?.account ?? null;
+    }
+    catch {
+        workspace = null;
+    }
+    const cached = workspace === null ? null : readCodexAccountsCache(ctx.home);
+    const cache = cached !== null && cached.workspace === workspace ? cached : null;
+    const codexHome = defaultCodexHome(ctx);
+    const slot = attrValue(resolveSlot(readCodexAccountId(codexHome), cache));
+    const fetchedMs = cache === null ? Number.NaN : Date.parse(cache.fetchedAt);
+    const age = Number.isFinite(fetchedMs)
+        ? `account list cached ${ageText(Math.max(0, Math.floor((ctx.now().getTime() - fetchedMs) / 1000)))} ago`
+        : "no account list cached";
+    const parts = [
+        hooked.length > 0
+            ? `shell hook in ${hooked.join(" and ")}`
+            : "no shell hook",
+        ...(agent === null ? [] : [`login agent ${agent}`]),
+    ];
+    return `Codex attribution: ${installed ? "installed" : "not installed"} (${parts.join(", ")}); ${tilde(codexHome, ctx.home)} resolves to coding account ${slot}, ${age}.${installed ? "" : " Run catalyst setup to add it."}`;
+}
+/** How setup knows Codex is on this computer: an executable `codex` on the PATH setup runs with
+ *  (the command a terminal launch runs), or the desktop app's bundle (what a Dock launch starts).
+ *  A Codex home folder alone does not count: it outlives an uninstalled Codex. Null when neither. */
+export function codexPresence(ctx, deps = {}) {
+    for (const dir of (ctx.env.PATH ?? "").split(delimiter)) {
+        if (!isAbsolute(dir))
+            continue;
+        const candidate = join(dir, "codex");
+        try {
+            accessSync(candidate, constants.X_OK);
+            if (statSync(candidate).isFile())
+                return candidate;
+        }
+        catch {
+            // Not here; the next PATH entry may have it.
+        }
+    }
+    const apps = deps.applicationDirs ?? [
+        "/Applications",
+        join(ctx.home, "Applications"),
+    ];
+    for (const dir of apps) {
+        const bundle = join(dir, CODEX_APP_BUNDLE);
+        try {
+            if (statSync(bundle).isDirectory())
+                return bundle;
+        }
+        catch {
+            // Not installed in this folder.
+        }
+    }
+    return null;
+}
+export const CODEX_ABSENT_LINE = `Codex attribution skipped: Codex is not installed on this computer (no codex command on PATH and no ${CODEX_APP_BUNDLE} in /Applications or ~/Applications). Run catalyst setup again after you install Codex to add it.`;
+/** Setup's part: the rc blocks and, on a Mac, the agent. Silent under another HOME, where it changes nothing. */
+export function setupCodexAttribution(ctx, deps = {}) {
+    if (!ownsHome(ctx.home, deps))
+        return [];
+    // No Codex, no hook: the agent would otherwise set the launch environment for every Dock app.
+    if (codexPresence(ctx, deps) === null)
+        return [CODEX_ABSENT_LINE];
+    const files = shellRcFiles(ctx).flatMap((file) => {
+        try {
+            const outcome = installShellHook(file, ctx.home, fileOps(deps));
+            return outcome === null ? [] : [outcome];
+        }
+        catch (err) {
+            return [
+                {
+                    path: file.path,
+                    state: "skipped",
+                    why: `it could not be read or written (${message(err)})`,
+                },
+            ];
+        }
+    });
+    const lines = [];
+    const written = files
+        .filter((f) => f.state !== "skipped")
+        .map((f) => `${tilde(f.path, ctx.home)} (${f.state})`);
+    if (written.length > 0)
+        lines.push(`Codex launches from a terminal name their coding account: the codex function is in ${written.join(" and ")}.`);
+    for (const f of files)
+        if (f.state === "skipped")
+            lines.push(`Left ${tilde(f.path, ctx.home)} without the Codex launch hook: ${f.why}.`);
+    if (files.length === 0)
+        lines.push("No shell rc file got the Codex launch hook: there is no ~/.zshrc or ~/.bashrc, and your login shell is neither zsh nor bash.");
+    const agent = installCodexAgent(ctx, deps);
+    if (agent.state === "loaded")
+        lines.push(`Codex launches from the Dock name their coding account: the ${CODEX_ATTRIBUTION_LABEL} LaunchAgent is loaded. A Codex app that is already open picks this up the next time it starts.`);
+    else if (agent.state === "unchanged")
+        lines.push(`The ${CODEX_ATTRIBUTION_LABEL} LaunchAgent is loaded and unchanged.`);
+    else if (agent.state === "failed")
+        lines.push(`Setup could not load the ${CODEX_ATTRIBUTION_LABEL} LaunchAgent (${agent.detail}), so apps started from the Dock do not name their coding account. Run catalyst setup again in Terminal on this Mac's desktop.`);
+    return lines;
+}
+/** What a full setup run adds after its steps, done or waiting. A dry run, a run scoped with
+ *  --only and --no-shell-hook add nothing. With --json the lines go to stderr, so stdout keeps its one
+ *  document. */
+export function codexAttributionAfterSetup(args, ctx, deps = {}) {
+    if (args.flags["dry-run"] === true ||
+        args.flags.only !== undefined ||
+        args.flags["no-shell-hook"] === true)
+        return;
+    const say = args.json ? ctx.stderr : ctx.stdout;
+    for (const line of setupCodexAttribution(ctx, deps))
+        say(line);
+}
+/** `catalyst setup --remove-codex-attribution`. Run twice, the second run finds nothing to remove. */
+export function removeCodexAttribution(ctx, deps = {}) {
+    const files = shellRcFiles(ctx).flatMap((file) => {
+        try {
+            const outcome = removeShellHook(file.path, ctx.home, fileOps(deps));
+            return outcome === null ? [] : [outcome];
+        }
+        catch (err) {
+            return [
+                {
+                    path: file.path,
+                    state: "skipped",
+                    why: `it could not be read or written (${message(err)})`,
+                },
+            ];
+        }
+    });
+    const agent = removeCodexAgent(ctx, deps);
+    const lines = [];
+    for (const f of files)
+        lines.push(f.state === "skipped"
+            ? `Left ${tilde(f.path, ctx.home)} as it is: ${f.why}.`
+            : `Removed the Codex launch hook from ${tilde(f.path, ctx.home)}; the file is as it was before setup added it.`);
+    if (files.length === 0)
+        lines.push("No shell rc file had the Codex launch hook.");
+    if (agent.agent === "removed")
+        lines.push(`Unloaded and deleted the ${CODEX_ATTRIBUTION_LABEL} LaunchAgent.`);
+    else if (agent.agent === "absent")
+        lines.push(`The ${CODEX_ATTRIBUTION_LABEL} LaunchAgent was not installed.`);
+    else if (agent.agent === "failed")
+        lines.push(`Could not remove the ${CODEX_ATTRIBUTION_LABEL} LaunchAgent: ${agent.detail}.`);
+    else if (agent.agent === "other_home")
+        lines.push(`HOME (${ctx.home}) is not this account's home folder, so the LaunchAgent and the launch environment were left alone.`);
+    if (agent.environment === "unset")
+        lines.push(`Unset ${ENV_NAME} in the launch environment. Apps that are already open keep it until they restart.`);
+    else if (agent.environment === "kept_others")
+        lines.push(`Took the coding account and machine name out of ${ENV_NAME} in the launch environment, and kept the attributes you set there yourself. Apps that are already open keep the old value until they restart.`);
+    else if (agent.environment === "failed")
+        lines.push(`Could not change ${ENV_NAME} in the launch environment. Run launchctl getenv ${ENV_NAME} to see it, and launchctl unsetenv ${ENV_NAME} to clear it.`);
+    return {
+        ok: files.every((f) => f.state !== "skipped") &&
+            agent.agent !== "failed" &&
+            agent.environment !== "failed",
+        files,
+        agent,
+        lines,
+    };
+}