@yagni-app/code-staging 1.0.9-staging.1306.1 → 1.0.9-staging.1324.1

package/README.md

@@ -36,6 +36,38 @@ flag) — ask your workspace admin. Maintainers: the alpha checklist is
 `docs/yagni-code-alpha.md`; publish-day steps live in
 `docs/yagni-code-publishing.md`.
 
+## Connect Claude Code or Codex
+
+After `yagni login`, connect either installed client to the YAGNI model proxy:
+
+```bash
+yagni connect claude-code
+yagni connect codex
+```
+
+Restart the client after connecting. Keep `yagni` on its PATH: the client runs
+`yagni token --profile <name> --base-url <url>` to obtain refreshed credentials.
+The connection stays bound to the selected environment even after `yagni use`
+switches your active environment. If you change that profile's URL, log in and
+connect again. Temporary `YAGNI_BASE_URL` overrides must match the saved profile.
+
+Claude uses `~/.claude/settings.json` (or `CLAUDE_CONFIG_DIR`). For project scope,
+run `yagni connect claude-code --project` from the repository root; it writes
+`.claude/settings.local.json`. In a Git worktree, current Claude versions may
+use the main checkout's project settings. Remove conflicting Anthropic credentials
+or alternate provider settings before connecting; higher-priority project,
+managed, or shell settings can override the generated configuration.
+
+Codex uses `~/.codex/config.toml` (or `CODEX_HOME`) and selects the `advanced` tier.
+A selected Codex profile or project config can override these user defaults.
+Existing TOML comments are saved in `config.toml.yagni-backup`. If a later
+rewrite has different comments or settings, a separate backup with a unique
+suffix preserves that version; the command prints its location.
+
+Use the matching command with `--off` to remove the YAGNI connection. This
+preserves unrelated settings but does not restore model or gateway values
+replaced when connecting. No API token is stored in either client's configuration.
+
 ## Develop
 
 Working in this monorepo, install from the repo instead of the registry. Build

package/dist/cli.js

@@ -687,7 +687,7 @@ export async function main(argv) {
         return feedbackCommand(rest, {}, cliVersion());
     }
     if (command === "token") {
-        return tokenCommand();
+        return tokenCommand({}, rest);
     }
     if (command === "upgrade") {
         return upgradeCommand(rest, { current: cliVersion() });

package/dist/connectClaudeCode.d.ts

@@ -9,8 +9,8 @@
  *                               dialect route)
  *   env.ANTHROPIC_CUSTOM_HEADERS  `x-yagni-caller: claude-code`, the
  *                               attribution label the usage report rolls up on
- *   apiKeyHelper                `yagni token` — the credential comes from the
- *                               profile at call time, so nothing secret is
+ *   apiKeyHelper                `yagni token --profile … --base-url …` —
+ *                               credentials stay bound to this environment, so nothing secret is
  *                               ever baked into a settings file and a rotated
  *                               token is picked up automatically
  *
@@ -53,7 +53,7 @@ export interface DisconnectPlan {
 }
 /** Pure: the settings object after `--off` — managed keys out, all else kept. */
 export declare function planDisconnect(existing: Settings, helperCommand: string): DisconnectPlan;
-export declare function settingsPathFor(scope: "user" | "project", cwd: string, home?: string): string;
+export declare function settingsPathFor(scope: "user" | "project", cwd: string, home?: string, env?: NodeJS.ProcessEnv): string;
 /** Read + parse a settings file. Missing → {}. Corrupt/symlink/non-object → throws. */
 export declare function readSettings(path: string): Settings;
 /** Atomic write (temp + rename), preserving an existing file's permissions. */
@@ -66,6 +66,7 @@ export interface ConnectArgs {
 export declare function parseConnectArgs(args: string[]): ConnectArgs;
 export interface ConnectDeps {
     readProfile?: () => Promise<Profile>;
+    readNamedProfile?: (name: string) => Promise<Profile | null>;
     cwd?: string;
     home?: string;
     env?: NodeJS.ProcessEnv;

package/dist/connectClaudeCode.js

@@ -9,8 +9,8 @@
  *                               dialect route)
  *   env.ANTHROPIC_CUSTOM_HEADERS  `x-yagni-caller: claude-code`, the
  *                               attribution label the usage report rolls up on
- *   apiKeyHelper                `yagni token` — the credential comes from the
- *                               profile at call time, so nothing secret is
+ *   apiKeyHelper                `yagni token --profile … --base-url …` —
+ *                               credentials stay bound to this environment, so nothing secret is
  *                               ever baked into a settings file and a rotated
  *                               token is picked up automatically
  *
@@ -21,11 +21,13 @@
  * here rather than a silent back-off: the user asked for a config change, so
  * failing quietly would be lying.
  */
-import { existsSync, lstatSync, readFileSync, renameSync, rmSync, writeFileSync, mkdirSync, chmodSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { join } from "node:path";
+import { configFileStat, writeConfigAtomic, connectionFailureHint } from "./connectFiles.js";
+import { classifyTokenExpiry } from "./launch.js";
 import { DISTRIBUTION } from "./distribution.js";
-import { credentialsFromProfile, readActiveProfile } from "./profiles.js";
+import { credentialsFromProfile, readActiveProfile, readProfile as readNamedProfile } from "./profiles.js";
 export const CALLER_HEADER_LINE = "x-yagni-caller: claude-code";
 function envOf(settings) {
     const env = settings.env;
@@ -38,7 +40,7 @@ function envOf(settings) {
  */
 export function mergeCustomHeaders(existing) {
     const lines = typeof existing === "string" && existing.length > 0 ? existing.split("\n") : [];
-    const kept = lines.filter((l) => l.trim() !== "" && !/^x-yagni-caller\s*:/i.test(l));
+    const kept = lines.filter((l) => l.trim() !== "" && !/^\s*x-yagni-caller\s*:/i.test(l));
     return [...kept, CALLER_HEADER_LINE].join("\n");
 }
 /** Pure: the settings object after connecting, plus what changed. */
@@ -49,7 +51,7 @@ export function planConnect(existing, input) {
     const note = (key, prior, next) => {
         if (prior === next)
             return;
-        changes.push(prior === undefined ? `${key} = ${next}` : `${key}: ${String(prior)} → ${next}`);
+        changes.push(`${key} ${prior === undefined ? "set" : "updated"}`);
         if (prior !== undefined)
             replaced.push(key);
     };
@@ -57,7 +59,7 @@ export function planConnect(existing, input) {
     env.ANTHROPIC_BASE_URL = input.baseUrl;
     const headers = mergeCustomHeaders(env.ANTHROPIC_CUSTOM_HEADERS);
     if (env.ANTHROPIC_CUSTOM_HEADERS !== headers) {
-        changes.push(`env.ANTHROPIC_CUSTOM_HEADERS = ${headers.replaceAll("\n", " | ")}`);
+        changes.push("env.ANTHROPIC_CUSTOM_HEADERS updated");
     }
     env.ANTHROPIC_CUSTOM_HEADERS = headers;
     note("apiKeyHelper", existing.apiKeyHelper, input.helperCommand);
@@ -72,14 +74,15 @@ export function planDisconnect(existing, helperCommand) {
     const env = envOf(existing);
     const removed = [];
     const out = { ...existing };
-    if (env.ANTHROPIC_BASE_URL !== undefined) {
+    const ownsHelper = typeof existing.apiKeyHelper === "string" && isYagniHelper(existing.apiKeyHelper, helperCommand);
+    if (ownsHelper && env.ANTHROPIC_BASE_URL !== undefined) {
         removed.push("env.ANTHROPIC_BASE_URL");
         delete env.ANTHROPIC_BASE_URL;
     }
     if (typeof env.ANTHROPIC_CUSTOM_HEADERS === "string") {
         const kept = env.ANTHROPIC_CUSTOM_HEADERS
             .split("\n")
-            .filter((l) => l.trim() !== "" && !/^x-yagni-caller\s*:/i.test(l));
+            .filter((l) => l.trim() !== "" && !/^\s*x-yagni-caller\s*:/i.test(l));
         if (kept.length !== env.ANTHROPIC_CUSTOM_HEADERS.split("\n").filter((l) => l.trim() !== "").length) {
             removed.push("env.ANTHROPIC_CUSTOM_HEADERS (x-yagni-caller line)");
         }
@@ -91,8 +94,8 @@ export function planDisconnect(existing, helperCommand) {
     let keptForeignHelper;
     if (typeof out.apiKeyHelper === "string") {
         // Only remove a helper that is ours — `yagni token` under any install path
-        // (npx wrapper, absolute bin). Someone else's gateway helper stays.
-        if (new RegExp(`(^|[/\\s])${helperCommand.split(" ")[0]}\\s+token\\s*$`).test(out.apiKeyHelper)) {
+        // (absolute bin). Someone else's gateway helper stays.
+        if (ownsHelper) {
             removed.push("apiKeyHelper");
             delete out.apiKeyHelper;
         }
@@ -102,25 +105,31 @@ export function planDisconnect(existing, helperCommand) {
     }
     if (Object.keys(env).length === 0 && out.env !== undefined)
         delete out.env;
-    else
+    else if (Object.keys(env).length > 0)
         out.env = env;
     return { settings: out, removed, ...(keptForeignHelper ? { keptForeignHelper } : {}) };
 }
 // ---------------------------------------------------------------------------
 // File I/O
 // ---------------------------------------------------------------------------
-export function settingsPathFor(scope, cwd, home = homedir()) {
+function isYagniHelper(helper, command) {
+    const name = command.split(" ")[0].replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`^(?:[^\\s]+/)?${name}\\s+token(?:\\s+--profile\\s+[a-zA-Z0-9_-]+\\s+--base-url\\s+.+)?\\s*$`).test(helper);
+}
+function shellArg(value) {
+    if (/^[a-zA-Z0-9_/:.=-]+$/.test(value))
+        return value;
+    return "'" + value.replaceAll("'", "'\\''") + "'";
+}
+export function settingsPathFor(scope, cwd, home = homedir(), env = process.env) {
     return scope === "project"
         ? join(cwd, ".claude", "settings.local.json")
-        : join(home, ".claude", "settings.json");
+        : join(env.CLAUDE_CONFIG_DIR?.trim() || join(home, ".claude"), "settings.json");
 }
 /** Read + parse a settings file. Missing → {}. Corrupt/symlink/non-object → throws. */
 export function readSettings(path) {
-    if (!existsSync(path))
+    if (!configFileStat(path))
         return {};
-    if (lstatSync(path).isSymbolicLink()) {
-        throw new Error(`${path} is a symlink; refusing to rewrite it. Point yagni at the real file.`);
-    }
     let parsed;
     try {
         parsed = JSON.parse(readFileSync(path, "utf8"));
@@ -135,18 +144,7 @@ export function readSettings(path) {
 }
 /** Atomic write (temp + rename), preserving an existing file's permissions. */
 export function writeSettings(path, settings) {
-    const existingMode = existsSync(path) ? lstatSync(path).mode & 0o777 : undefined;
-    mkdirSync(dirname(path), { recursive: true });
-    const tmp = join(dirname(path), `.${DISTRIBUTION.commandName}-connect-${process.pid}.tmp`);
-    try {
-        writeFileSync(tmp, `${JSON.stringify(settings, null, 2)}\n`);
-        renameSync(tmp, path);
-    }
-    finally {
-        rmSync(tmp, { force: true });
-    }
-    if (existingMode !== undefined)
-        chmodSync(path, existingMode);
+    writeConfigAtomic(path, `${JSON.stringify(settings, null, 2)}\n`);
 }
 export function parseConnectArgs(args) {
     let target;
@@ -159,13 +157,32 @@ export function parseConnectArgs(args) {
             off = true;
         else if (!a.startsWith("-") && target === undefined)
             target = a;
+        else
+            throw new Error(`Unexpected connect argument: ${a}`);
     }
     return { target, project, off };
 }
 export async function connectCommand(args, deps = {}) {
+    try {
+        return await runConnectCommand(args, deps);
+    }
+    catch (err) {
+        (deps.stderr ?? ((t) => process.stderr.write(t)))(`Could not update connection settings. ${connectionFailureHint(err)}\n`);
+        return 1;
+    }
+}
+async function runConnectCommand(args, deps) {
     const stdout = deps.stdout ?? ((t) => process.stdout.write(t));
     const stderr = deps.stderr ?? ((t) => process.stderr.write(t));
-    const { target, project, off } = parseConnectArgs(args);
+    let parsed;
+    try {
+        parsed = parseConnectArgs(args);
+    }
+    catch (err) {
+        stderr(`${err instanceof Error ? err.message : "Invalid connect arguments"}\n`);
+        return 1;
+    }
+    const { target, project, off } = parsed;
     if (target === "codex") {
         if (project) {
             stderr("`connect codex` has no --project scope: Codex reads one user-level config.toml.\n");
@@ -180,9 +197,7 @@ export async function connectCommand(args, deps = {}) {
             : `Usage: ${DISTRIBUTION.commandName} connect <claude-code|codex> [--project] [--off]\n`);
         return 1;
     }
-    const profile = await (deps.readProfile ?? readActiveProfile)();
-    const helperCommand = `${DISTRIBUTION.commandName} token`;
-    const path = settingsPathFor(project ? "project" : "user", deps.cwd ?? process.cwd(), deps.home);
+    const path = settingsPathFor(project ? "project" : "user", deps.cwd ?? process.cwd(), deps.home, deps.env);
     let existing;
     try {
         existing = readSettings(path);
@@ -193,20 +208,38 @@ export async function connectCommand(args, deps = {}) {
     }
     if (off) {
         const plan = planDisconnect(existing, DISTRIBUTION.commandName);
-        writeSettings(path, plan.settings);
+        if (plan.removed.length > 0)
+            writeSettings(path, plan.settings);
         stdout(plan.removed.length > 0
             ? `✓ Claude Code disconnected from YAGNI.\n  ${path}\n  Removed: ${plan.removed.join(", ")}\n`
             : `Nothing to disconnect in ${path}.\n`);
         if (plan.keptForeignHelper) {
-            stdout(`  Kept apiKeyHelper (${plan.keptForeignHelper}) since it is not YAGNI's.\n`);
+            stdout("  Kept the existing apiKeyHelper since it is not YAGNI's.\n");
         }
         return 0;
     }
+    const profile = await (deps.readProfile ?? readActiveProfile)();
+    const helperCommand = `${DISTRIBUTION.commandName} token --profile ${shellArg(profile.name)} --base-url ${shellArg(profile.baseUrl)}`;
+    const stored = await (deps.readNamedProfile ?? readNamedProfile)(profile.name);
+    if (stored && stored.baseUrl.replace(/\/+$/, "") !== profile.baseUrl.replace(/\/+$/, "")) {
+        stderr("The active URL override differs from the saved profile. Save the environment with yagni use --base-url and log in before connecting. No settings changed.\n");
+        return 1;
+    }
+    if (classifyTokenExpiry(profile.expiresAt, Date.now()).kind === "expired") {
+        stderr("Your YAGNI Code session has expired. Run yagni login before connecting. No settings changed.\n");
+        return 1;
+    }
     const creds = credentialsFromProfile(profile);
     if (!creds?.token) {
         stderr(`Not logged in to environment "${profile.name}" (${profile.baseUrl}). Run \`${DISTRIBUTION.commandName} login\` first.\n`);
         return 1;
     }
+    const conflicts = ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "CLAUDE_CODE_USE_BEDROCK", "CLAUDE_CODE_USE_VERTEX", "CLAUDE_CODE_USE_FOUNDRY"]
+        .filter((key) => envOf(existing)[key] && envOf(existing)[key] !== "0");
+    if (conflicts.length > 0) {
+        stderr(`Remove conflicting settings.env keys before connecting: ${conflicts.join(", ")}. No settings changed.\n`);
+        return 1;
+    }
     const plan = planConnect(existing, { baseUrl: profile.baseUrl, helperCommand });
     writeSettings(path, plan.settings);
     stdout(`✓ Claude Code connected to YAGNI (${profile.name} → ${profile.baseUrl}).\n`);

package/dist/connectCodex.d.ts

@@ -21,7 +21,7 @@
  *                                          everything else.
  *
  * TOML cannot be comment-preservingly round-tripped by a parser, so when the
- * existing config carries comments we save a one-time `config.toml.yagni-backup`
+ * existing config carries comments we save a `config.toml.yagni-backup`
  * next to it before rewriting and say so — never silently eat a user's notes.
  * Everything else follows the claude-code connector's contract: managed keys
  * only, atomic write, symlink refusal, corrupt file is a loud error, `--off`
@@ -41,6 +41,7 @@ export interface CodexConnectPlan {
 export declare function planConnectCodex(existing: TomlTable, input: {
     baseUrl: string;
     commandName: string;
+    profileName?: string;
 }): CodexConnectPlan;
 export interface CodexDisconnectPlan {
     config: TomlTable;
@@ -58,11 +59,14 @@ export declare function readCodexConfig(path: string): CodexConfigFile;
 /**
  * Atomic write; when the original text carried comments (which a parse →
  * stringify round-trip cannot preserve), a `config.toml.yagni-backup` copy of
- * the original is written first. Returns the backup path when one was made.
+ * the original is written first. Later differing originals get unique backup
+ * names; an identical first backup can be reused. Returns the current original
+ * backup path, or null when no backup was needed.
  */
 export declare function writeCodexConfig(path: string, config: TomlTable, originalRaw: string | null): string | null;
 export interface ConnectCodexDeps {
     readProfile?: () => Promise<Profile>;
+    readNamedProfile?: (name: string) => Promise<Profile | null>;
     home?: string;
     env?: NodeJS.ProcessEnv;
     stdout?: (text: string) => void;

package/dist/connectCodex.js

@@ -21,18 +21,21 @@
  *                                          everything else.
  *
  * TOML cannot be comment-preservingly round-tripped by a parser, so when the
- * existing config carries comments we save a one-time `config.toml.yagni-backup`
+ * existing config carries comments we save a `config.toml.yagni-backup`
  * next to it before rewriting and say so — never silently eat a user's notes.
  * Everything else follows the claude-code connector's contract: managed keys
  * only, atomic write, symlink refusal, corrupt file is a loud error, `--off`
  * removes exactly what we own.
  */
-import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { configFileStat, writeConfigAtomic, connectionFailureHint } from "./connectFiles.js";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+import { classifyTokenExpiry } from "./launch.js";
 import { DISTRIBUTION } from "./distribution.js";
-import { credentialsFromProfile, readActiveProfile } from "./profiles.js";
+import { credentialsFromProfile, readActiveProfile, readProfile as readNamedProfile } from "./profiles.js";
 export const CODEX_PROVIDER_ID = "yagni";
 export const CODEX_DEFAULT_TIER = "advanced";
 export function codexConfigPath(home = homedir(), env = process.env) {
@@ -67,7 +70,7 @@ export function planConnectCodex(existing, input) {
         base_url: `${input.baseUrl}/v1`,
         wire_api: "responses",
         http_headers: { "x-yagni-caller": "codex" },
-        auth: { command: input.commandName, args: ["token"] },
+        auth: { command: input.commandName, args: ["token", "--profile", input.profileName ?? "prod", "--base-url", input.baseUrl], timeout_ms: 20_000 },
     };
     return {
         config: {
@@ -107,11 +110,8 @@ export function planDisconnectCodex(existing) {
 }
 /** Read + parse the Codex config. Missing → {}. Corrupt/symlink → throws. */
 export function readCodexConfig(path) {
-    if (!existsSync(path))
+    if (!configFileStat(path))
         return { config: {}, raw: null };
-    if (lstatSync(path).isSymbolicLink()) {
-        throw new Error(`${path} is a symlink; refusing to rewrite it. Point yagni at the real file.`);
-    }
     const raw = readFileSync(path, "utf8");
     let parsed;
     try {
@@ -125,36 +125,46 @@ export function readCodexConfig(path) {
     }
     return { config: parsed, raw };
 }
-const COMMENT_RE = /^\s*#|\s#/m;
 /**
  * Atomic write; when the original text carried comments (which a parse →
  * stringify round-trip cannot preserve), a `config.toml.yagni-backup` copy of
- * the original is written first. Returns the backup path when one was made.
+ * the original is written first. Later differing originals get unique backup
+ * names; an identical first backup can be reused. Returns the current original
+ * backup path, or null when no backup was needed.
  */
 export function writeCodexConfig(path, config, originalRaw) {
+    configFileStat(path);
+    const text = `${stringifyToml(config)}\n`;
     mkdirSync(dirname(path), { recursive: true });
     let backupPath = null;
-    if (originalRaw !== null && COMMENT_RE.test(originalRaw)) {
+    // Conservatively keep hashes inside strings too, so inline comments cannot be missed.
+    if (originalRaw !== null && originalRaw.includes("#")) {
         backupPath = `${path}.yagni-backup`;
-        writeFileSync(backupPath, originalRaw);
+        const existingBackup = configFileStat(backupPath);
+        if (existingBackup && readFileSync(backupPath, "utf8") !== originalRaw) {
+            backupPath = `${backupPath}-${randomUUID()}`;
+        }
+        if (!existingBackup || backupPath !== `${path}.yagni-backup`) {
+            writeFileSync(backupPath, originalRaw, { flag: "wx", mode: 0o600 });
+        }
     }
-    const existingMode = existsSync(path) ? lstatSync(path).mode & 0o777 : undefined;
-    const tmp = join(dirname(path), `.${DISTRIBUTION.commandName}-connect-codex-${process.pid}.tmp`);
+    writeConfigAtomic(path, text);
+    return backupPath;
+}
+export async function connectCodexCommand(opts, deps = {}) {
     try {
-        writeFileSync(tmp, `${stringifyToml(config)}\n`, existingMode !== undefined ? { mode: existingMode } : {});
-        renameSync(tmp, path);
+        return await runConnectCodexCommand(opts, deps);
     }
-    finally {
-        rmSync(tmp, { force: true });
+    catch (err) {
+        (deps.stderr ?? ((t) => process.stderr.write(t)))(`Could not update Codex settings. ${connectionFailureHint(err)}\n`);
+        return 1;
     }
-    return backupPath;
 }
-export async function connectCodexCommand(opts, deps = {}) {
+async function runConnectCodexCommand(opts, deps) {
     const stdout = deps.stdout ?? ((t) => process.stdout.write(t));
     const stderr = deps.stderr ?? ((t) => process.stderr.write(t));
     const env = deps.env ?? process.env;
     const path = codexConfigPath(deps.home, env);
-    const profile = await (deps.readProfile ?? readActiveProfile)();
     let file;
     try {
         file = readCodexConfig(path);
@@ -175,6 +185,16 @@ export async function connectCodexCommand(opts, deps = {}) {
             stdout(`  Comments in the original were preserved at ${backup}.\n`);
         return 0;
     }
+    const profile = await (deps.readProfile ?? readActiveProfile)();
+    const stored = await (deps.readNamedProfile ?? readNamedProfile)(profile.name);
+    if (stored && stored.baseUrl.replace(/\/+$/, "") !== profile.baseUrl.replace(/\/+$/, "")) {
+        stderr("The active URL override differs from the saved profile. Save the environment with yagni use --base-url and log in before connecting. No settings changed.\n");
+        return 1;
+    }
+    if (classifyTokenExpiry(profile.expiresAt, Date.now()).kind === "expired") {
+        stderr("Your YAGNI Code session has expired. Run yagni login before connecting. No settings changed.\n");
+        return 1;
+    }
     const creds = credentialsFromProfile(profile);
     if (!creds?.token) {
         stderr(`Not logged in to environment "${profile.name}" (${profile.baseUrl}). Run \`${DISTRIBUTION.commandName} login\` first.\n`);
@@ -183,6 +203,7 @@ export async function connectCodexCommand(opts, deps = {}) {
     const plan = planConnectCodex(file.config, {
         baseUrl: profile.baseUrl,
         commandName: DISTRIBUTION.commandName,
+        profileName: profile.name,
     });
     const backup = writeCodexConfig(path, plan.config, file.raw);
     stdout(`✓ Codex connected to YAGNI (${profile.name} → ${profile.baseUrl}).\n`);
@@ -195,7 +216,7 @@ export async function connectCodexCommand(opts, deps = {}) {
     if (backup) {
         stdout(`  Your config had comments, which a rewrite cannot keep. The original is at ${backup}.\n`);
     }
-    stdout(`  Restart Codex to pick this up. It runs \`${DISTRIBUTION.commandName} token\` for credentials and serves the "${CODEX_DEFAULT_TIER}" tier; edit \`model\` to any YAGNI tier to change that.\n`);
+    stdout(`  Restart Codex to pick this up. Its credential helper stays bound to environment "${profile.name}" and serves the "${CODEX_DEFAULT_TIER}" tier; edit \`model\` to any YAGNI tier to change that.\n`);
     return 0;
 }
 //# sourceMappingURL=connectCodex.js.map

package/dist/connectFiles.d.ts

@@ -0,0 +1,5 @@
+import { type Stats } from "node:fs";
+export declare function configFileStat(path: string): Stats | undefined;
+export declare function writeConfigAtomic(path: string, contents: string): void;
+export declare function connectionFailureHint(error: unknown): string;
+//# sourceMappingURL=connectFiles.d.ts.map

package/dist/connectFiles.js

@@ -0,0 +1,49 @@
+import { lstatSync, mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+export function configFileStat(path) {
+    const stat = lstatSync(path, { throwIfNoEntry: false });
+    if (stat && !stat.isFile())
+        throw Object.assign(new Error(`${path} is a symlink or not a regular file; refusing to rewrite it.`), { code: "YAGNI_CONFIG_NOT_REGULAR" });
+    return stat;
+}
+export function writeConfigAtomic(path, contents) {
+    const mode = configFileStat(path)?.mode;
+    mkdirSync(dirname(path), { recursive: true });
+    const tempDir = mkdtempSync(join(dirname(path), ".yagni-connect-"));
+    try {
+        const temp = join(tempDir, "config");
+        writeFileSync(temp, contents, { flag: "wx", mode: mode === undefined ? 0o600 : mode & 0o777 });
+        configFileStat(path);
+        renameSync(temp, path);
+    }
+    finally {
+        rmSync(tempDir, { recursive: true, force: true });
+    }
+}
+export function connectionFailureHint(error) {
+    const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+    switch (code) {
+        case "ENOSPC":
+        case "EDQUOT":
+            return "The disk is full or its storage quota was reached. Free space and try again.";
+        case "EROFS":
+            return "The configuration filesystem is read-only. Make it writable and try again.";
+        case "EACCES":
+        case "EPERM":
+            return "Permission was denied. Check the configuration directory and file permissions, then try again.";
+        case "ENOTDIR":
+        case "EISDIR":
+        case "YAGNI_CONFIG_NOT_REGULAR":
+            return "A configuration or backup path is a symlink or has the wrong file type. Use a regular file in a writable directory.";
+        case "EMFILE":
+        case "ENFILE":
+            return "Too many files are open. Close unused applications and try again.";
+        case "ENOENT":
+            return "A configuration path is missing. Check the configuration directory and try again.";
+        case "EEXIST":
+            return "A configuration or backup path is already occupied. Check that path and try again.";
+        default:
+            return "Try again. If the problem persists, contact support with the command you ran.";
+    }
+}
+//# sourceMappingURL=connectFiles.js.map

package/dist/extension/hooks.d.ts

@@ -6,8 +6,8 @@
  * at lifecycle events. The config format mirrors Claude Code's `settings.json`
  * hooks shape so a user can copy-paste between them.
  *
- * Supported events (8): SessionStart, UserPromptSubmit, PreToolUse,
- * PostToolUse, PermissionRequest, PreCompact, PostCompact, SessionEnd.
+ * Supported events (9): SessionStart, UserPromptSubmit, PreToolUse,
+ * PostToolUse, PermissionRequest, PreCompact, PostCompact, SessionEnd, Stop.
  *
  * Exit code semantics (matching Claude Code / Codex):
  *   0   = success; stdout parsed as JSON for structured decisions
@@ -32,7 +32,7 @@ export interface HookGroup {
 /** The hooks section of config.json. */
 export type HooksConfig = Record<string, HookGroup[]>;
 /** Supported Claude Code event names. */
-export type HookEventName = "SessionStart" | "UserPromptSubmit" | "PreToolUse" | "PostToolUse" | "PermissionRequest" | "PreCompact" | "PostCompact" | "SessionEnd";
+export type HookEventName = "SessionStart" | "UserPromptSubmit" | "PreToolUse" | "PostToolUse" | "PermissionRequest" | "PreCompact" | "PostCompact" | "SessionEnd" | "Stop";
 declare const SUPPORTED_EVENTS: readonly HookEventName[];
 /** Result of a PreToolUse hook evaluation. */
 export type PreToolUseHookResult = {
@@ -82,6 +82,16 @@ export declare function parsePermissionRequestOutput(stdout: string): Permission
 export declare function parseAdditionalContext(stdout: string): string | null;
 /** Check if stdout JSON has continue: false (for PreCompact cancellation). */
 export declare function parseCompactCancel(stdout: string): boolean;
+/**
+ * A short upload-safe label for a hook-exec exception, for the always-on
+ * trail line. Tiers, in order: a Node error code ("ENOENT", "ETIMEDOUT"),
+ * the message's first token (a machine word like "spawn"), the constructor
+ * name, and typeof for non-Error throws (execImpl is an injected seam —
+ * a string throw is possible). Message-derived tiers are scrubbed — a
+ * message can begin with content (a credentials URL), and this label rides
+ * the default-on (upload-safe) tier.
+ */
+export declare function hookErrorLabel(err: unknown): string;
 interface HookExecutorOptions {
     config: HooksConfig;
     env?: NodeJS.ProcessEnv;

package/dist/extension/hooks.js

@@ -6,8 +6,8 @@
  * at lifecycle events. The config format mirrors Claude Code's `settings.json`
  * hooks shape so a user can copy-paste between them.
  *
- * Supported events (8): SessionStart, UserPromptSubmit, PreToolUse,
- * PostToolUse, PermissionRequest, PreCompact, PostCompact, SessionEnd.
+ * Supported events (9): SessionStart, UserPromptSubmit, PreToolUse,
+ * PostToolUse, PermissionRequest, PreCompact, PostCompact, SessionEnd, Stop.
  *
  * Exit code semantics (matching Claude Code / Codex):
  *   0   = success; stdout parsed as JSON for structured decisions
@@ -21,8 +21,10 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { codeStateHome } from "./stateHome.js";
+import { isDriverCaller } from "./config.js";
 import { isDebug } from "./diagnostics.js";
 import { logEvent } from "./errorSink.js";
+import { scrubSecrets } from "./pipeline/scrubSecrets.js";
 const SUPPORTED_EVENTS = [
     "SessionStart",
     "UserPromptSubmit",
@@ -32,6 +34,7 @@ const SUPPORTED_EVENTS = [
     "PreCompact",
     "PostCompact",
     "SessionEnd",
+    "Stop",
 ];
 // ---------------------------------------------------------------------------
 // Config loading
@@ -301,8 +304,72 @@ export function parseCompactCancel(stdout) {
     return parsed.continue === false;
 }
 // ---------------------------------------------------------------------------
+// Stop capture
+// ---------------------------------------------------------------------------
+/**
+ * Extract the last assistant message's text and stopReason from an
+ * agent_end event. Walks backwards (the shape cmux/state.ts walks forwards)
+ * so an aborted final turn with no text still reports its stopReason —
+ * the reason is what decides whether Stop hooks fire at all.
+ */
+function lastAssistantInfo(event) {
+    const messages = event?.messages;
+    if (!Array.isArray(messages))
+        return undefined;
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (!message || typeof message !== "object")
+            continue;
+        const typed = message;
+        if (typed.role !== "assistant")
+            continue;
+        const text = typeof typed.content === "string"
+            ? typed.content.trim() || undefined
+            : textFromBlocks(typed.content);
+        return { text, stopReason: typeof typed.stopReason === "string" ? typed.stopReason : undefined };
+    }
+    return undefined;
+}
+/** Join text blocks from a content array (mirrors cmux's textFromContent). */
+function textFromBlocks(content) {
+    if (!Array.isArray(content))
+        return undefined;
+    const parts = [];
+    for (const block of content) {
+        if (!block || typeof block !== "object")
+            continue;
+        const typed = block;
+        if (typed.type === "text" && typeof typed.text === "string" && typed.text.trim()) {
+            parts.push(typed.text);
+        }
+    }
+    return parts.join("\n") || undefined;
+}
+// ---------------------------------------------------------------------------
 // Diagnostic logging
 // ---------------------------------------------------------------------------
+/**
+ * A short upload-safe label for a hook-exec exception, for the always-on
+ * trail line. Tiers, in order: a Node error code ("ENOENT", "ETIMEDOUT"),
+ * the message's first token (a machine word like "spawn"), the constructor
+ * name, and typeof for non-Error throws (execImpl is an injected seam —
+ * a string throw is possible). Message-derived tiers are scrubbed — a
+ * message can begin with content (a credentials URL), and this label rides
+ * the default-on (upload-safe) tier.
+ */
+export function hookErrorLabel(err) {
+    const code = err?.code;
+    // Scrub BEFORE slicing: a secret-shaped value longer than the 40-char cap
+    // would be split first and the fragment could match no pattern.
+    if (typeof code === "string" && code)
+        return scrubSecrets(code).slice(0, 40);
+    if (err instanceof Error) {
+        if (err.message)
+            return scrubSecrets(err.message.split(/[\s:]+/)[0]).slice(0, 40);
+        return err.constructor.name;
+    }
+    return typeof err;
+}
 function logHookEvent(env, payload) {
     if (!isDebug(env))
         return;
@@ -656,6 +723,64 @@ export function registerHooks(pi, deps = {}) {
             }
         });
     }
+    // --- Stop (agent finished responding; driver turn complete) ---
+    // Two-phase capture, mirroring the cmux bridge: agent_settled carries no
+    // payload, so the last assistant message is captured at agent_end and
+    // consumed at settled. Firing is VOID, not awaited — pi awaits settled
+    // handlers before unblocking the TUI's prompt loop and RPC waitForIdle,
+    // so an awaited hook would keep a finished session looking busy for up
+    // to the full hook timeout.
+    const stopGroups = config["Stop"] ?? [];
+    if (stopGroups.length > 0 && isDriverCaller(env)) {
+        let pendingStop;
+        pi.on("agent_end", (event) => {
+            pendingStop = lastAssistantInfo(event);
+        });
+        pi.on("agent_settled", (_event, ctx) => {
+            // hasUI is fixed per session — checking it first keeps the capture
+            // consume order-independent (a headless session simply never fires).
+            if (!ctx.hasUI)
+                return;
+            const captured = pendingStop;
+            if (!captured)
+                return;
+            // Mid-retry/compaction/continuation settles are not the turn's end —
+            // pi sets isIdle only once no automatic follow-up work will run. The
+            // capture is NOT consumed here: a settle that isn't idle leaves it for
+            // the genuine end-of-turn settle (an agent_end between the two
+            // overwrites it with the continuation's own final message).
+            try {
+                if (!ctx.isIdle())
+                    return;
+            }
+            catch {
+                return;
+            }
+            pendingStop = undefined;
+            // Claude Code parity: its query loop returns before running Stop hooks
+            // when the user aborted or the model errored — "finished, your move"
+            // would be a lie for a killed turn. Retry/continuation agent_ends
+            // overwrite the capture, so an error followed by a successful retry
+            // still fires (with the retry's message).
+            if (captured.stopReason === "aborted" || captured.stopReason === "error")
+                return;
+            const cwd = ctx.cwd;
+            const inputJson = JSON.stringify({
+                session_id: sessionId,
+                cwd,
+                hook_event_name: "Stop",
+                stop_hook_active: false,
+                ...(captured.text ? { last_assistant_message: captured.text } : {}),
+            });
+            void (async () => {
+                for (const group of filterByTrust(stopGroups, trusted(ctx))) {
+                    for (const entry of group.hooks) {
+                        await runSideEffectHook(entry.command, inputJson, cwd, "Stop", ctx, env, execImpl);
+                    }
+                }
+            })();
+        });
+    }
 }
 /** Run a side-effect-only hook (no control effects, output ignored). */
 async function runSideEffectHook(command, inputJson, cwd, eventName, ctx, env, execImpl) {
@@ -665,6 +790,13 @@ async function runSideEffectHook(command, inputJson, cwd, eventName, ctx, env, e
             YAGNI_HOOK_CWD: cwd,
             YAGNI_HOOK_SESSION_ID: env.YAGNI_SESSION_ID ?? "",
         });
+        const failed = !!result.error || (result.exitCode !== 0 && result.exitCode !== null);
+        // One outcome, two tiers: the debug line carries the full detail
+        // (stderr, timing) and is YAGNI_DEBUG-gated; the warn line is always-on
+        // and upload-safe, so "hook fired and failed" is distinguishable from
+        // "hook never fired" in a default session. The command rides the warn
+        // line scrubbed (below) so N hooks on one event produce distinguishable
+        // lines without leaking anything the user embedded in the command.
         logHookEvent(env, {
             event: eventName,
             command,
@@ -674,14 +806,47 @@ async function runSideEffectHook(command, inputJson, cwd, eventName, ctx, env, e
             ...(result.error ? { error: result.error } : {}),
             ...(result.stderr.trim() ? { stderr: result.stderr.trim().slice(0, 512) } : {}),
         });
-        if (result.error || (result.exitCode !== 0 && result.exitCode !== null)) {
+        if (failed) {
+            logEvent({
+                source: "hooks",
+                level: "warn",
+                event: "hook_failed",
+                sessionId: env.YAGNI_SESSION_ID ?? undefined,
+                fields: {
+                    event_name: eventName,
+                    // Scrubbed at write time: the trail file stores lines raw (scrubbing
+                    // otherwise happens only at readSessionTrail), and a user's hook
+                    // command can embed secrets inline (curl -H "Authorization: Bearer …").
+                    // The full, unscrubbed command stays on the YAGNI_DEBUG tier.
+                    command: scrubSecrets(command).slice(0, 80),
+                    exit_code: result.exitCode,
+                    // Scrub the whole error string before taking the first colon token —
+                    // result.error embeds a raw err.message (spawn failed/err paths in
+                    // execHook), and the sibling hookErrorLabel path scrubs message-derived
+                    // tiers the same way.
+                    ...(result.error ? { error: scrubSecrets(result.error).split(":")[0] } : {}),
+                },
+            });
             if (ctx.hasUI && result.stderr.trim()) {
                 ctx.ui.notify(`Hook '${eventName}' exited with code ${result.exitCode}: ${result.stderr.trim().slice(0, 200)}`, "warning");
             }
         }
     }
-    catch {
-        // Fail-soft: a hook error never breaks the session
+    catch (err) {
+        // Fail-soft: a hook error never breaks the session — but never silent.
+        // The label distinguishes "spawn ENOENT" from a timeout (see
+        // hookErrorLabel); the command is scrubbed like the sibling path's.
+        logEvent({
+            source: "hooks",
+            level: "warn",
+            event: "hook_exec_threw",
+            sessionId: env.YAGNI_SESSION_ID ?? undefined,
+            fields: {
+                event_name: eventName,
+                command: scrubSecrets(command).slice(0, 80),
+                error: hookErrorLabel(err),
+            },
+        });
     }
 }
 // ---------------------------------------------------------------------------

package/dist/extension/pipeline/scrubSecrets.js

@@ -22,6 +22,11 @@ const PATTERNS = [
     [/\b([A-Za-z0-9_]*(?:secret|password|passwd|api[_-]?key|token|private[_-]?key|access[_-]?key)[A-Za-z0-9_]*)\b(\s*[:=]\s*)("[^"]+"|'[^']+'|`[^`]+`|[^\s"']+)/gi, "$1$2[REDACTED]"],
     // Long base64-ish blobs (likely keys/JWTs)
     [/\b[A-Za-z0-9+/]{40,}={0,2}\b/g, "[REDACTED]"],
+    // Opaque bearer tokens in Authorization headers: no provider prefix, no
+    // secret-named key, and usually under the base64 length threshold — none of
+    // the patterns above catch them. Keep the scheme, redact the token. Header
+    // names and auth schemes are case-insensitive (RFC 9110) — hence the flag.
+    [/(\bauthorization\s*[:=]\s*["']?bearer\s+)([a-z0-9._~+/=-]+)/gi, "$1[REDACTED]"],
 ];
 export function scrubSecrets(text) {
     let out = text;

package/dist/refresh.js

@@ -108,8 +108,11 @@ export async function maybeRefreshAtLaunch(creds, deps = {}) {
             await deps.persist(next);
         }
         catch {
-            // A failed write shouldn't block the spawn; the rotated token is still
-            // used for this session, and a later launch re-attempts persistence.
+            return {
+                creds: next,
+                refreshed: true,
+                warnings: ["Your refreshed YAGNI Code session could not be saved. Check disk space and profile permissions, then run yagni login before the next session."],
+            };
         }
     }
     return { creds: next, refreshed: true, warnings: [] };

package/dist/token.d.ts

@@ -15,11 +15,12 @@ import type { Credentials } from "./credentials.js";
 import { type Profile } from "./profiles.js";
 export interface TokenCommandDeps {
     readProfile?: () => Promise<Profile>;
+    readNamedProfile?: (name: string) => Promise<Profile | null>;
     refresh?: typeof maybeRefreshAtLaunch;
     persist?: (name: string, creds: Credentials) => Promise<void>;
     now?: () => number;
     stdout?: (text: string) => void;
     stderr?: (text: string) => void;
 }
-export declare function tokenCommand(deps?: TokenCommandDeps): Promise<number>;
+export declare function tokenCommand(deps?: TokenCommandDeps, args?: string[]): Promise<number>;
 //# sourceMappingURL=token.d.ts.map

package/dist/token.js

@@ -12,14 +12,40 @@
  */
 import { classifyTokenExpiry } from "./launch.js";
 import { maybeRefreshAtLaunch } from "./refresh.js";
-import { credentialsFromProfile, persistProfileTokenRotation, readActiveProfile, } from "./profiles.js";
-export async function tokenCommand(deps = {}) {
+import { credentialsFromProfile, persistProfileTokenRotation, readActiveProfile, readProfile as readNamedProfile, isValidProfileName, } from "./profiles.js";
+export async function tokenCommand(deps = {}, args = []) {
     const readProfile = deps.readProfile ?? readActiveProfile;
     const refresh = deps.refresh ?? maybeRefreshAtLaunch;
     const persist = deps.persist ?? persistProfileTokenRotation;
     const stdout = deps.stdout ?? ((t) => process.stdout.write(t));
     const stderr = deps.stderr ?? ((t) => process.stderr.write(t));
-    const profile = await readProfile();
+    let profile;
+    if (args.length > 0) {
+        const options = new Map();
+        for (let i = 0; i < args.length; i += 2) {
+            const key = args[i];
+            const value = args[i + 1];
+            if (!["--profile", "--base-url"].includes(key) || !value || options.has(key)) {
+                stderr("Usage: yagni token [--profile <name> --base-url <url>]\n");
+                return 1;
+            }
+            options.set(key, value);
+        }
+        const name = options.get("--profile");
+        const baseUrl = options.get("--base-url");
+        if (!name || !isValidProfileName(name) || !baseUrl) {
+            stderr("A valid --profile and --base-url are both required.\n");
+            return 1;
+        }
+        profile = await (deps.readNamedProfile ?? readNamedProfile)(name);
+        if (!profile || profile.baseUrl.replace(/\/+$/, "") !== baseUrl.replace(/\/+$/, "")) {
+            stderr("The connected YAGNI profile is missing or its URL changed. Re-run yagni connect for this client.\n");
+            return 1;
+        }
+    }
+    else {
+        profile = await readProfile();
+    }
     let creds = credentialsFromProfile(profile);
     if (!creds?.token) {
         stderr(`Not logged in to environment "${profile.name}" (${profile.baseUrl}). Run \`yagni login\` first.\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yagni-app/code-staging",
-  "version": "1.0.9-staging.1306.1",
+  "version": "1.0.9-staging.1324.1",
   "description": "YAGNI Code: a terminal coding agent that already knows your company. One YAGNI login routes the model and grounds the agent in your team's context.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "YAGNI, Inc. <jack@yagni.app> (https://yagni.app)",
@@ -58,5 +58,5 @@
     "turndown": "^7.2.4",
     "typebox": "^1.3.15"
   },
-  "yagniSourceSha": "b15d63d89acab434f4e2c9f20d60337cffb4a0c3"
+  "yagniSourceSha": "30c899295c967f5ebaa0293a7e9c20396ae07ae2"
 }