chainlesschain 0.162.95 → 0.162.97

package/src/commands/hub.js

@@ -356,6 +356,15 @@ async function cmdSyncAdapter(name, options) {
     if (options.passphrase) opts.passphrase = String(options.passphrase);
     // Cookie-mode sources (weread): pass the login cookie through to the adapter.
     if (options.cookie) opts.cookie = String(options.cookie);
+    // L1 local files (module 101): the local-files adapter walks directories
+    // given via opts.roots (comma-separated dirs → array). Without this the
+    // adapter falls back to its default user-data dirs.
+    if (options.roots) {
+      opts.roots = String(options.roots)
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    }
     const report = await hub.registry.syncAdapter(name, opts);
     if (spinner) spinner.succeed(`synced ${name}`);
     // 2026-05-24 in-APK Android exit + flush-race fix. Real-device repro on
@@ -843,6 +852,116 @@ async function cmdSalvage(dumpfile, options) {
   }
 }
 
+// ─── collect-qq (QQNT frida-free decrypt → vault) ────────────────────────
+//
+// module 101 QQNT 采集方案 — on-device path. Decrypts a (root-staged) encrypted
+// nt_msg.db via the DERIVED key (MD5(MD5(uid)+rand), no frida), protobuf-parses
+// the messages, and ingests them. The Android CollectQqNativeTool su-reads the
+// DB + uid candidates, then invokes this. Same logic also runs on PC (USB).
+// Plaintext is written to a temp file only for parsing, then deleted.
+async function cmdCollectQq(options) {
+  const spinner = options.json
+    ? null
+    : ora("collect-qq (decrypt + ingest)...").start();
+  try {
+    const { createRequire } = await import("module");
+    const require = createRequire(import.meta.url);
+    const fs = require("fs");
+    const os = require("os");
+    const path = require("path");
+    const qq = options._qqCore
+      ? options._qqCore
+      : await import("@chainlesschain/personal-data-hub/forensics/qq-nt-collect");
+
+    if (!options.db) throw new Error("need --db <encrypted nt_msg.db>");
+    if (!options.uids) throw new Error("need --uids <file with u_ candidates>");
+    const raw = fs.readFileSync(options.db);
+    const rand = options.rand || qq.extractRand(raw);
+    if (!rand)
+      throw new Error(
+        "could not read `rand` from nt_msg.db header (pass --rand)",
+      );
+    const uids = fs
+      .readFileSync(options.uids, "utf8")
+      .split(/\s+/)
+      .filter((u) => /^u_[A-Za-z0-9_-]{10,}$/.test(u));
+    if (!uids.length) throw new Error("no u_ uid candidates in --uids file");
+
+    const result = qq.deriveAndDecrypt(raw, uids, rand);
+    if (!result) {
+      const report = {
+        ok: false,
+        reason: "no-uid-match",
+        uidCandidates: uids.length,
+      };
+      if (options.json) {
+        jsonAndExit(report);
+        return;
+      }
+      if (spinner)
+        spinner.fail(
+          "no uid matched (account uid not in candidates, or formula changed)",
+        );
+      process.exit(2);
+    }
+
+    // better-sqlite3's native binding isn't at the standard `bindings` path on
+    // Android (the bundle loads it specially) — reuse the vault's already-loaded
+    // Database constructor instead of require("better-sqlite3").
+    const hub = await (options._getHub || getHub)();
+    const vault = hub.vault;
+    const Database = (vault.db || vault._db || vault).constructor;
+
+    // Write the plaintext next to the (app-writable) input DB — os.tmpdir() is
+    // /data/local/tmp on Android, which the app uid can't write (EACCES).
+    void os;
+    const tmp = path.join(
+      path.dirname(path.resolve(options.db)),
+      `qqnt-dec-${process.pid}.db`,
+    );
+    fs.writeFileSync(tmp, result.decrypted);
+    let events;
+    try {
+      events = qq.parseEvents(Database, tmp, options.self || "self");
+    } finally {
+      try {
+        fs.unlinkSync(tmp);
+      } catch {
+        /* best-effort wipe */
+      }
+    }
+
+    let ingested = 0;
+    for (const ev of events) {
+      try {
+        vault.putEvent(ev);
+        ingested++;
+      } catch {
+        /* skip dup/invalid */
+      }
+    }
+    const report = {
+      ok: true,
+      matchedUid: result.uid,
+      kdf: result.kdf,
+      messages: events.length,
+      ingested,
+    };
+    if (spinner) spinner.succeed(`collect-qq: ${ingested} QQ messages → vault`);
+    if (options.json) {
+      jsonAndExit(report);
+      return;
+    }
+    logger.log(chalk.green("✓ QQNT collect succeeded"));
+    logger.log(`  matched uid:  ${result.uid} (kdf ${result.kdf})`);
+    logger.log(`  messages:     ${events.length}`);
+    logger.log(`  ingested:     ${ingested}`);
+    process.exit(0);
+  } catch (err) {
+    fail(spinner, err, options.json);
+  }
+}
+
 // ─── Phase 10.3 — cc hub aichat <verb> wizard subcommand surface ─────
 //
 // Mirrors the WS topics (personal-data-hub.aichat-*) so scripts and the
@@ -2239,6 +2358,10 @@ export function registerHubCommand(program) {
       "--input <path>",
       "Path to a snapshot file or local DB (system-data-android snapshot, douyin <uid>_im.db, wechat-pc MSG*.db, etc.)",
     )
+    .option(
+      "--roots <dirs>",
+      "Comma-separated directories to scan (local-files adapter, e.g. /sdcard/Documents,/sdcard/Download)",
+    )
     .option(
       "--db-path <path>",
       "Explicit local DB path (alias of --input for device-pull adapters)",
@@ -2548,6 +2671,21 @@ export function registerHubCommand(program) {
     .option("--json", "Output JSON")
     .action(cmdSalvage);
 
+  hub
+    .command("collect-qq")
+    .description(
+      "QQNT (modern QQ): decrypt a root-staged encrypted nt_msg.db via the DERIVED key (no frida), protobuf-parse messages, and ingest into the vault. Used by the Android CollectQqNativeTool (su-reads DB + uids); also runnable on PC.",
+    )
+    .requiredOption("--db <path>", "Encrypted nt_msg.db (root-staged / pulled)")
+    .requiredOption(
+      "--uids <path>",
+      "File with u_ uid candidates (one per line)",
+    )
+    .option("--rand <str>", "Override the header-derived rand")
+    .option("--self <qq>", "Your own QQ number (attribution fallback)")
+    .option("--json", "Output JSON")
+    .action(cmdCollectQq);
+
   hub
     .command("event-detail <eventId>")
     .description(

package/src/commands/mtc.js

@@ -1374,6 +1374,14 @@ function registerFederationCommands(mtc) {
         const issuer =
           options.issuer || `mtca:cc:${federationId}:${options.memberId}`;
         const registry = loadFederationRegistry();
+        // Founding the federation = first time this node has seen it. The
+        // founder writes a genesis `create` event into governance.log so the
+        // founding member is part of the replayed roster everywhere the log is
+        // synced (a peer that pulls the log must know who the founder is to
+        // recognize their votes — the membership-gated vote replay would
+        // otherwise silently drop the founder's own approve). See the create
+        // handler in core-mtc replayGovernanceLog.
+        const isFounding = !registry.federations[federationId];
         const fedEntry = registry.federations[federationId] || {
           federation_id: federationId,
           members: {},
@@ -1429,6 +1437,25 @@ function registerFederationCommands(mtc) {
         registry.federations[federationId] = fedEntry;
         saveFederationRegistry(registry);
 
+        // Genesis event: anchor the founder into the governance.log so the
+        // M-of-N vote replay (which only counts votes from current members)
+        // recognizes the founder — locally and on any peer that syncs the log.
+        if (isFounding) {
+          emitAndPersist(federationId, {
+            eventType: "create",
+            actorMemberId: options.memberId,
+            secretKey: keys.secretKey,
+            publicKey: keys.publicKey,
+            alg: sig.signer.ALG,
+            payload: {
+              bootstrap_member_id: options.memberId,
+              bootstrap_pubkey_id: trustAnchor.pubkey_id,
+              bootstrap_alg: sig.signer.ALG,
+              initial_threshold: 1,
+            },
+          });
+        }
+
         if (options.json) {
           console.log(
             JSON.stringify(
@@ -2770,7 +2797,16 @@ function registerFederationGovernanceCommands(fed) {
 // ─────────────────────────────────────────────────────────────────────────
 
 function getDiscoverAnnouncesDir(dropZone, federationId) {
-  return path.join(dropZone, "federation-announces", federationId);
+  // Sanitize federation_id (same charset as getDiscoverFilename's pubkey_id):
+  // a value from a (remote) announce must not escape the drop zone via "../",
+  // and ":" in a did-style id is an invalid path char on Windows. Mirrors
+  // core-mtc's _persistAnnounce. Publish + scan both go through here, so the
+  // sanitized dir name stays consistent between write and read.
+  const safe = String(federationId == null ? "" : federationId).replace(
+    /[^a-zA-Z0-9_-]/g,
+    "_",
+  );
+  return path.join(dropZone, "federation-announces", safe);
 }
 
 function getDiscoverFilename(announce) {

package/src/gateways/discord/discord-formatter.js

@@ -20,7 +20,11 @@ export function formatForDiscord(response, options = {}) {
   if (!response) return "";
   const maxLength = options.maxLength || DISCORD_MAX_LENGTH;
 
-  let text = response;
+  // Defang mass-mention pings (@everyone / @here) that can appear in agent
+  // output — a zero-width space after the `@` renders identically but stops
+  // Discord parsing it as a mention. There is no allowed_mentions safety net at
+  // the send layer, so the formatter must be safe by default.
+  let text = neutralizeMassMentions(response);
 
   if (text.length > maxLength) {
     text = text.substring(0, maxLength - 3) + "...";
@@ -29,6 +33,19 @@ export function formatForDiscord(response, options = {}) {
   return text;
 }
 
+/**
+ * Insert a zero-width space into @everyone / @here so they don't ping. Exported
+ * so callers composing messages by other means can reuse it.
+ * @param {string} text
+ * @returns {string}
+ */
+export function neutralizeMassMentions(text) {
+  return String(text == null ? "" : text).replace(
+    /@(everyone|here)/g,
+    "@​$1",
+  );
+}
+
 /**
  * Split a response into Discord-sized chunks.
  * Tries to split at code block or newline boundaries.

package/src/gateways/telegram/telegram-formatter.js

@@ -47,17 +47,20 @@ export function toTelegramMarkdown(markdown) {
   // Escape special characters in text
   result = escapeMarkdownV2(result);
 
-  // Restore code blocks and inline code (unescaped)
+  // Restore code blocks and inline code (unescaped). Use a replacement FUNCTION
+  // so `$`-sequences inside the code (e.g. `$&`, `$1`, `$$` in sed/regex/shell)
+  // are inserted literally — a string replacement would interpret them as
+  // String.replace patterns and corrupt the code.
   for (let i = codeBlocks.length - 1; i >= 0; i--) {
     result = result.replace(
       `__CODE_BLOCK_${i}__`.replace(ESCAPE_CHARS, "\\$1"),
-      codeBlocks[i],
+      () => codeBlocks[i],
     );
   }
   for (let i = inlineCode.length - 1; i >= 0; i--) {
     result = result.replace(
       `__INLINE_CODE_${i}__`.replace(ESCAPE_CHARS, "\\$1"),
-      inlineCode[i],
+      () => inlineCode[i],
     );
   }
 

package/src/gateways/ws/ws-server.js

@@ -12,6 +12,7 @@
 
 import { EventEmitter } from "node:events";
 import { spawn } from "node:child_process";
+import { createHash, timingSafeEqual } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { WebSocketServer } from "ws";
@@ -525,10 +526,27 @@ export class ChainlessChainWSServer extends EventEmitter {
     return handleLlmChat(this, id, ws, message);
   }
 
+  /**
+   * Constant-time check of a client-supplied token against the configured one.
+   * A plain `===` leaks timing that a network client could use to recover the
+   * token byte-by-byte; hash both to a fixed length and compare in constant
+   * time. Preserves the original semantics: no configured token matches only an
+   * absent token (the auto-authenticated path).
+   * @private
+   */
+  _tokenMatches(provided) {
+    const expected = this.token;
+    if (expected == null) return provided == null;
+    if (typeof provided !== "string") return false;
+    const a = createHash("sha256").update(provided).digest();
+    const b = createHash("sha256").update(String(expected)).digest();
+    return timingSafeEqual(a, b);
+  }
+
   /** @private */
   _handleAuth(clientId, ws, message) {
     const { id, token } = message;
-    const success = token === this.token;
+    const success = this._tokenMatches(token);
     const client = this.clients.get(clientId);
 
     if (success && client) {

package/src/harness/plugin-manager.js

@@ -352,10 +352,20 @@ export function installPluginSkills(db, pluginName, pluginPath, skills) {
   const installed = [];
 
   for (const skill of skills) {
+    if (!skill || typeof skill.name !== "string" || typeof skill.path !== "string") {
+      continue;
+    }
     const srcDir = path.resolve(pluginPath, skill.path);
+    // Reject manifest entries that escape the plugin (read) or the marketplace
+    // (arbitrary file WRITE) via `../` — a malicious plugin could otherwise drop
+    // files anywhere (e.g. overwrite ~/.bashrc) during install.
+    if (!_isWithin(pluginPath, srcDir)) continue;
     if (!fs.existsSync(srcDir)) continue;
 
     const destDir = path.join(marketplaceDir, skill.name);
+    if (!_isWithin(marketplaceDir, destDir) || path.resolve(destDir) === path.resolve(marketplaceDir)) {
+      continue;
+    }
     fs.mkdirSync(destDir, { recursive: true });
 
     // Copy skill files
@@ -419,6 +429,16 @@ export function getPluginSkills(db, pluginName) {
 /**
  * Recursively copy a directory
  */
+/**
+ * True when `child` resolves to `parent` or a path inside it. Used to keep a
+ * (semi-trusted) plugin manifest from escaping its sandbox via `../` in
+ * skill.path / skill.name.
+ */
+function _isWithin(parent, child) {
+  const rel = path.relative(path.resolve(parent), path.resolve(child));
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
 function _copyDirSync(src, dest) {
   fs.mkdirSync(dest, { recursive: true });
   const entries = fs.readdirSync(src, { withFileTypes: true });

package/src/harness/worktree-isolator.js

@@ -10,11 +10,17 @@
 import { execSync } from "node:child_process";
 import { existsSync, rmSync } from "node:fs";
 import { resolve } from "node:path";
-import { isGitRepo, gitExec } from "../lib/git-integration.js";
+import {
+  isGitRepo,
+  gitExec,
+  assertSafeGitRef,
+} from "../lib/git-integration.js";
 
 const WORKTREE_DIR = ".worktrees";
 
 export function createWorktree(repoDir, branchName, baseBranch) {
+  assertSafeGitRef(branchName, "branch name");
+  if (baseBranch) assertSafeGitRef(baseBranch, "base branch");
   if (!isGitRepo(repoDir)) {
     throw new Error("Not a git repository");
   }
@@ -157,6 +163,8 @@ export function cleanupAgentWorktrees(repoDir) {
 }
 
 export function diffWorktree(repoDir, branchName, options = {}) {
+  assertSafeGitRef(branchName, "branch name");
+  if (options.baseBranch) assertSafeGitRef(options.baseBranch, "base branch");
   const base = options.baseBranch || "HEAD";
   const filePath = options.filePath || null;
   const fileArg = filePath ? ` -- "${filePath}"` : "";
@@ -204,6 +212,8 @@ export function diffWorktree(repoDir, branchName, options = {}) {
 }
 
 export function mergeWorktree(repoDir, branchName, options = {}) {
+  assertSafeGitRef(branchName, "branch name");
+  if (options.baseBranch) assertSafeGitRef(options.baseBranch, "base branch");
   const strategy = options.strategy || "merge";
   const deleteBranch = options.deleteBranch !== false;
 
@@ -285,6 +295,8 @@ export function mergeWorktree(repoDir, branchName, options = {}) {
 }
 
 export function previewWorktreeMerge(repoDir, branchName, options = {}) {
+  assertSafeGitRef(branchName, "branch name");
+  if (options.baseBranch) assertSafeGitRef(options.baseBranch, "base branch");
   const strategy = options.strategy || "merge";
   const baseBranch = _resolveBaseBranchForMerge(repoDir, options.baseBranch);
   const worktree = _findWorktreeByBranch(repoDir, branchName);
@@ -374,6 +386,8 @@ export function applyWorktreeAutomationCandidate(
   branchName,
   options = {},
 ) {
+  assertSafeGitRef(branchName, "branch name");
+  if (options.baseBranch) assertSafeGitRef(options.baseBranch, "base branch");
   const filePath = options.filePath || null;
   const candidateId = options.candidateId || null;
   const conflictType = options.conflictType || null;
@@ -473,6 +487,8 @@ export function applyWorktreeAutomationCandidate(
 }
 
 export function worktreeLog(repoDir, branchName, baseBranch = "HEAD") {
+  assertSafeGitRef(branchName, "branch name");
+  assertSafeGitRef(baseBranch, "base branch");
   try {
     const output = gitExec(
       `log ${baseBranch}..${branchName} --pretty=format:"%h|%s|%ci"`,

package/src/index.js

@@ -62,6 +62,7 @@ import { registerContextCommand } from "./commands/context.js";
 import { registerCheckpointCommand } from "./commands/checkpoint.js";
 import { registerGoalCommand } from "./commands/goal.js";
 import { registerCommandCommand } from "./commands/command.js";
+import { registerAgentsCommand } from "./commands/agents.js";
 import { registerCompactCommand } from "./commands/compact.js";
 import { registerLoopCommand } from "./commands/loop.js";
 import { registerReviewCommand } from "./commands/review.js";
@@ -478,6 +479,7 @@ export function createProgram(opts = {}) {
   registerCheckpointCommand(program);
   registerGoalCommand(program);
   registerCommandCommand(program);
+  registerAgentsCommand(program);
   registerCompactCommand(program);
   registerLoopCommand(program);
   registerReviewCommand(program);

package/src/lib/__tests__/model-deprecation.test.js

@@ -0,0 +1,194 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import {
+  DEPRECATED_MODELS,
+  checkModelDeprecation,
+  formatModelDeprecationWarning,
+  maybeWarnDeprecatedModel,
+  _warned,
+} from "../model-deprecation.js";
+
+describe("checkModelDeprecation", () => {
+  it("flags an exact retired snapshot", () => {
+    const info = checkModelDeprecation("claude-3-opus-20240229");
+    expect(info).toBeTruthy();
+    expect(info.id).toBe("claude-3-opus-20240229");
+    expect(info.state).toBe("retired");
+    expect(info.replacement).toMatch(/claude-opus-4-8/);
+  });
+
+  it("flags retired Claude 3.5 / 3.7 families by prefix (the common ones)", () => {
+    expect(checkModelDeprecation("claude-3-5-sonnet-20240620")).toBeTruthy();
+    expect(checkModelDeprecation("claude-3-5-sonnet-20241022")).toBeTruthy();
+    expect(checkModelDeprecation("claude-3-5-haiku-20241022")).toBeTruthy();
+    expect(checkModelDeprecation("claude-3-7-sonnet-20250219")).toBeTruthy();
+    expect(checkModelDeprecation("claude-3-haiku-20240307")).toBeTruthy();
+  });
+
+  it("flags the retired ORIGINAL Claude 4 snapshots (exact dated id)", () => {
+    expect(checkModelDeprecation("claude-opus-4-20250514").state).toBe(
+      "retired",
+    );
+    expect(checkModelDeprecation("claude-sonnet-4-20250514").state).toBe(
+      "retired",
+    );
+  });
+
+  it("flags deprecated-but-live Claude Opus 4.1 with state=deprecated", () => {
+    const info = checkModelDeprecation("claude-opus-4-1-20250805");
+    expect(info).toBeTruthy();
+    expect(info.state).toBe("deprecated");
+  });
+
+  it("prefix-matches a retired family (claude-2 → claude-2.1)", () => {
+    expect(checkModelDeprecation("claude-2.1")).toBeTruthy();
+    expect(checkModelDeprecation("claude-2.0")).toBeTruthy();
+    expect(checkModelDeprecation("claude-instant-1.2")).toBeTruthy();
+  });
+
+  it("flags retired OpenAI snapshots", () => {
+    expect(checkModelDeprecation("gpt-4-0314")).toBeTruthy();
+    expect(checkModelDeprecation("gpt-4-32k-0613")).toBeTruthy();
+    expect(checkModelDeprecation("gpt-3.5-turbo-0301")).toBeTruthy();
+    expect(checkModelDeprecation("text-davinci-003")).toBeTruthy();
+  });
+
+  it("is case-insensitive and trims", () => {
+    expect(checkModelDeprecation("  GPT-4-0314  ")).toBeTruthy();
+    expect(checkModelDeprecation("Claude-2.1")).toBeTruthy();
+  });
+
+  it("CRITICAL: does NOT flag ACTIVE Claude 4 models (prefix-collision guard)", () => {
+    // These share a prefix with the retired 4.x snapshots — the entries use
+    // exact dated ids precisely so these stay silent.
+    expect(checkModelDeprecation("claude-opus-4-8")).toBeNull();
+    expect(checkModelDeprecation("claude-opus-4-7")).toBeNull();
+    expect(checkModelDeprecation("claude-opus-4-6")).toBeNull();
+    expect(checkModelDeprecation("claude-opus-4-5-20251101")).toBeNull();
+    expect(checkModelDeprecation("claude-sonnet-4-6")).toBeNull();
+    expect(checkModelDeprecation("claude-sonnet-4-5-20250929")).toBeNull();
+    expect(checkModelDeprecation("claude-haiku-4-5-20251001")).toBeNull();
+    expect(checkModelDeprecation("claude-haiku-4-5")).toBeNull();
+  });
+
+  it("does NOT flag other current GA / provider models", () => {
+    expect(checkModelDeprecation("gpt-4o")).toBeNull();
+    expect(checkModelDeprecation("gpt-4o-mini")).toBeNull();
+    expect(checkModelDeprecation("gpt-5")).toBeNull();
+    expect(checkModelDeprecation("gpt-4-turbo")).toBeNull();
+    // provider-specific ids (volcengine/doubao/ollama) never match
+    expect(checkModelDeprecation("doubao-seed-2-0-lite-260215")).toBeNull();
+    expect(checkModelDeprecation("qwen2.5-coder:7b")).toBeNull();
+  });
+
+  it("handles empty / non-string input", () => {
+    expect(checkModelDeprecation("")).toBeNull();
+    expect(checkModelDeprecation(null)).toBeNull();
+    expect(checkModelDeprecation(undefined)).toBeNull();
+    expect(checkModelDeprecation(42)).toBeNull();
+  });
+
+  it("every list entry is internally consistent and self-matches", () => {
+    for (const e of DEPRECATED_MODELS) {
+      expect(typeof e.id).toBe("string");
+      expect(e.id.length).toBeGreaterThan(0);
+      expect(["retired", "deprecated"]).toContain(e.state);
+      expect(typeof e.reason).toBe("string");
+      expect(typeof e.replacement).toBe("string");
+      expect(checkModelDeprecation(e.id)).toBeTruthy();
+      // the recommended replacement must itself never be flagged as retired
+      const firstReplacement = e.replacement.split(/\s+or\s+|\s+/)[0];
+      expect(checkModelDeprecation(firstReplacement)).toBeNull();
+    }
+  });
+});
+
+describe("formatModelDeprecationWarning", () => {
+  it("uses 'has been retired' for retired models", () => {
+    const info = checkModelDeprecation("claude-3-5-sonnet-20241022");
+    const line = formatModelDeprecationWarning(info);
+    expect(line).toMatch(/claude-3-5-sonnet-20241022/);
+    expect(line).toMatch(/has been retired/);
+    expect(line).toMatch(/claude-sonnet-4-6/);
+    expect(line).toMatch(/CC_MODEL_NOTICE=0/);
+  });
+
+  it("uses 'is deprecated' for deprecated-but-live models", () => {
+    const info = checkModelDeprecation("claude-opus-4-1-20250805");
+    const line = formatModelDeprecationWarning(info);
+    expect(line).toMatch(/is deprecated/);
+    expect(line).not.toMatch(/has been retired/);
+  });
+});
+
+describe("maybeWarnDeprecatedModel", () => {
+  let lines;
+  let print;
+  beforeEach(() => {
+    _warned.clear();
+    lines = [];
+    print = (l) => lines.push(l);
+  });
+
+  it("warns once for a deprecated model", () => {
+    const r = maybeWarnDeprecatedModel({ model: "claude-2.1", env: {}, print });
+    expect(r.warned).toBe(true);
+    expect(r.info.id).toBe("claude-2.1");
+    expect(lines).toHaveLength(1);
+    expect(lines[0]).toMatch(/claude-2\.1/);
+  });
+
+  it("warns for a retired Claude 3.5 Sonnet (the common stale id)", () => {
+    const r = maybeWarnDeprecatedModel({
+      model: "claude-3-5-sonnet-20241022",
+      env: {},
+      print,
+    });
+    expect(r.warned).toBe(true);
+    expect(lines[0]).toMatch(/has been retired/);
+  });
+
+  it("does not repeat the same model within a process", () => {
+    maybeWarnDeprecatedModel({ model: "gpt-4-0314", env: {}, print });
+    const r = maybeWarnDeprecatedModel({ model: "gpt-4-0314", env: {}, print });
+    expect(r.warned).toBe(false);
+    expect(r.info).toBeTruthy(); // still reports the match, just doesn't re-print
+    expect(lines).toHaveLength(1);
+  });
+
+  it("stays silent for a current model", () => {
+    const r = maybeWarnDeprecatedModel({
+      model: "claude-opus-4-8",
+      env: {},
+      print,
+    });
+    expect(r.warned).toBe(false);
+    expect(r.info).toBeNull();
+    expect(lines).toHaveLength(0);
+  });
+
+  it("honors CC_MODEL_NOTICE=0", () => {
+    const r = maybeWarnDeprecatedModel({
+      model: "claude-2.1",
+      env: { CC_MODEL_NOTICE: "0" },
+      print,
+    });
+    expect(r.warned).toBe(false);
+    expect(lines).toHaveLength(0);
+  });
+
+  it("fail-open on a throwing print", () => {
+    const r = maybeWarnDeprecatedModel({
+      model: "claude-2.1",
+      env: {},
+      print: () => {
+        throw new Error("boom");
+      },
+    });
+    expect(r.warned).toBe(false); // swallowed, no throw
+  });
+
+  it("no-ops on missing model", () => {
+    expect(maybeWarnDeprecatedModel({ env: {}, print }).warned).toBe(false);
+    expect(lines).toHaveLength(0);
+  });
+});