@indigoai-us/hq-cli 5.344.0 → 5.345.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [5.345.0] — 2026-10-05
+- Apply Codex rollout retention, batched stale KPI notices, per-lead error isolation, and autopilot nudge deduplication without rollout gates.
+
+- On a Mac with the Claude app or the Codex app installed and used a lot lately (at least 5 of that app's own sessions on 3 different days in the last 14 days; sessions from the `claude` and `codex` commands do not count, and neither do HQ's own bot sessions), the setup bot's welcome now leads straight into "Looks like you use the Claude app. Want to continue setup there?" (or the Codex app), and the HQ desktop app shows a button to open that app in your HQ folder next to a "Keep going here" button. Only a few metadata fields of each session are read: when it was used and which app ran it. Otherwise setup starts as before.
+
+## [5.344.1] — 2026-10-05
+- Release the MCP server's package lease after its resident modules preload and record a bounded command purpose on CLI package leases.
+
 ## [5.344.0] — 2026-10-04
 - Include a bounded reason in sync-failure client-health reports.
 - Add an explicit opt-in to count usage from HQ sessions with no company toward the default company: `hq mesh context default set` asks in a terminal (default No), takes `--count-usage` / `--no-count-usage`, and writes `usageAttribution` (company and signed-in person) to the work-context config. Changing or clearing the default, logging out, or signing in as another account withdraws it; `get` shows it; an automatic default never opts in.

package/assets/bot-workers/setup/worker.yaml

@@ -165,6 +165,27 @@ instructions: |
   short: say what you can do for them and give one concrete example drawn from
   their HQ. Still no open "what can I help you with".
 
+  ## When the app offered their coding tool first
+
+  Before your first message, the HQ app checks whether the person has the
+  Claude app or the Codex app on this computer and has used it a lot lately.
+  When they have, the app sends the first message for you: the opening of
+  your welcome, then one line asking whether they want to continue setup in
+  that app, with a button that opens the app in their HQ folder with setup
+  ready to go, and a "Keep going here" button. You did not write that
+  message, and the kickoff waits for their answer.
+
+  - When they click "Keep going here", your turn starts with a note from the
+    app saying so, followed by the kickoff. Do the kickoff exactly as "When
+    you receive the kickoff" says, and do not mention the offer.
+  - When they write something else instead, your turn starts with a note
+    from the app saying the offer was made and setup has not started. If they
+    want to continue in that app, tell them in plain words to click
+    the button above your message; never tell them to type a command.
+    Otherwise open the walkthrough as "Your very first message" says.
+  - If they went to that app and come back here later, work out
+    where you are as always: some steps may already be done there.
+
   ## Your progress note
 
   You are a fresh conversation every turn. The only thing that carries across is

package/dist/commands/lanes.js

@@ -37,7 +37,7 @@ import { isSsmRunCommandProcess } from "../lib/lanes/ssm-command-context.js";
 import { runResidentCommandWithPackageLease } from "../utils/resident-package-preload.js";
 import { readLanesFlagLocalOverride, readLanesRegistryFlag, readLanesRegistryFlagFailOff } from "../lib/lanes/registry-flag.js";
 import { LANE_HIRE_GRANT_FINISHED_LANES_FLAG, LANE_LIST_SKIP_REMOTE_REFRESH_FLAG, LANE_MESSAGE_ROUTE_OWNER_HOST_FLAG, LANE_ORPHANED_BARE_ID_DROPBOX_REPAIR_FLAG, LANE_REUSE_REFRESHES_PROFILE_FLAG, } from "../lib/lanes/flag-keys.js";
-import { CODEX_ROLLOUT_RETENTION_FLAG, configuredCodexRolloutHomes, lowDiskGuardEnabledForLane, retainCodexRollouts } from "../lib/lanes/disk-guard.js";
+import { configuredCodexRolloutHomes, lowDiskGuardEnabledForLane, retainCodexRollouts } from "../lib/lanes/disk-guard.js";
 import { isControllerAliasOutpostId } from "../lib/lanes/admission-host.js";
 import { runLeadAutopilotPass } from "../lib/lanes/autopilot.js";
 import { syncOutpostLeadRegistries } from "../lib/lanes/autopilot-registry.js";
@@ -5263,30 +5263,6 @@ async function runCapacity(ctx) {
 async function runGcRollouts(ctx, opts) {
     const hqRoot = ctx.hqRoot();
     const lanes = readAllLanes(hqRoot);
-    const companies = new Map();
-    for (const lane of lanes) {
-        const company = resolveLaneCompany(hqRoot, lane).company;
-        if (company)
-            companies.set(company.uid ?? company.slug, company);
-    }
-    if (companies.size === 0) {
-        const company = await ctx.resolveCompany();
-        companies.set(company.uid ?? company.slug, company);
-    }
-    let enabled = false;
-    for (const company of companies.values()) {
-        enabled ||= await readLanesRegistryFlag(CODEX_ROLLOUT_RETENTION_FLAG, {
-            company,
-            companyUidSource: "resolved_lane_company",
-            env: ctx.env,
-        });
-        if (enabled)
-            break;
-    }
-    if (!enabled) {
-        printJson({ ok: true, action: "gc-rollouts", enabled: false, dry_run: Boolean(opts.dryRun), scanned: 0, compressed: [], deleted: [], bytes_freed: 0 });
-        return;
-    }
     const config = loadLanesConfig(hqRoot);
     const homes = configuredCodexRolloutHomes(hqRoot, config, ctx.hostname());
     const result = await retainCodexRollouts({

package/dist/commands/mcp-serve.js

@@ -73,11 +73,12 @@ export async function runMcpServe(opts = {}) {
             process.emitWarning("hq-cli resident package preload completion failed (class=Error, module=unknown)");
         });
     };
+    // Release before the stdio read can remain open indefinitely. The request
+    // handlers and their declared lazy modules are loaded before this point.
+    startResidentPreload();
     const send = (msg) => {
         const response = `${JSON.stringify({ jsonrpc: "2.0", ...msg })}\n`;
-        if (residentPreloadStarted)
-            return output.write(response);
-        return output.write(response, startResidentPreload);
+        return output.write(response);
     };
     const reply = (id, result) => send({ id, result });
     const replyError = (id, code, message) => send({ id, error: { code, message } });

package/dist/lib/bot/coding-tool-activity.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Does the person already use the Claude app or the Codex app a lot on this
+ * computer?
+ *
+ * The setup bot asks this before its first message: someone who works in one
+ * of those desktop apps is offered to continue setup there. Only the desktop
+ * apps count, never the command-line tools, and only on macOS:
+ *
+ * 1. The app must be installed: `Claude.app` (bundle id
+ *    `com.anthropic.claudefordesktop`), or `ChatGPT.app` / `Codex.app`
+ *    carrying Codex (bundle id `com.openai.codex`), in `/Applications` or
+ *    `~/Applications`. The bundle id is checked, so another OpenAI app such as
+ *    ChatGPT Atlas (`com.openai.atlas`) never counts.
+ * 2. The app must have recent sessions of its own:
+ *    - Claude: the Claude app keeps one small record per Code session at
+ *      `~/Library/Application Support/Claude/claude-code-sessions/<account>/<org>/local_<id>.json`.
+ *      Sessions started with the `claude` command never get one, so CLI use
+ *      does not count. Only the record's `lastActivityAt` / `createdAt`
+ *      numbers and its `cwd` / `cliSessionId` (to skip HQ's bots) are read,
+ *      from the start of the file; the file's mtime is the fallback.
+ *    - Codex: the app and the CLI share `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`
+ *      (`CODEX_HOME` moves `~/.codex`). The first line of each file is a
+ *      `session_meta` record; a session the app ran says
+ *      `"originator":"Codex Desktop"` with `"source":"vscode"`. Sessions from
+ *      `codex` / `codex exec` (other originators, or source `exec`) and
+ *      sub-agent threads (an object source) do not count. Only those two
+ *      fields are read, from the start of the first line; the file's mtime
+ *      is when it was last used.
+ *
+ * Nothing else in a session is read, and nothing about a session leaves this
+ * module except two numbers per app (sessions and distinct days in the window).
+ *
+ * HQ's own bots are not the person. Any session whose id a bot has on file
+ * (`session*.json` in each bot folder) is skipped, and so is a Claude session
+ * whose folder is under the bots' own folder.
+ */
+export type CodingTool = "claude" | "codex";
+export interface ActivityThreshold {
+    windowDays: number;
+    minSessions: number;
+    minDistinctDays: number;
+}
+/**
+ * "Significant recent activity": at least `minSessions` sessions, spread over
+ * at least `minDistinctDays` calendar days, within the last `windowDays` days.
+ */
+export declare const SIGNIFICANT_CODING_TOOL_ACTIVITY: Readonly<ActivityThreshold>;
+export interface ToolActivity {
+    /** Is the desktop app installed? */
+    installed: boolean;
+    /** App sessions used within the window (0 when the app is not installed). */
+    sessions: number;
+    /** Distinct local calendar days those sessions fall on. */
+    days: number;
+}
+export interface CodingToolActivity {
+    claude: ToolActivity;
+    codex: ToolActivity;
+    /** The app to offer, or null when neither qualifies. */
+    pick: CodingTool | null;
+}
+export interface HqBotExclusions {
+    /** HQ folders bots run their turns in (from each bot.json `hqRoot`). */
+    hqRoots: string[];
+    /** Model session ids the bots have on file. */
+    sessionIds: string[];
+}
+export interface DetectCodingToolActivityInput {
+    now: Date;
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Defaults to `process.platform`; the apps are only looked for on macOS. */
+    platform?: NodeJS.Platform;
+    /** Where apps are installed; defaults to `/Applications` and `~/Applications`. */
+    applicationsDirs?: string[];
+    /** Where the bots live; defaults to `botsRoot()`. */
+    botsDir?: string;
+    /** Kept for callers; HQ folders are not used to tell app sessions apart. */
+    extraHqRoots?: string[];
+    threshold?: ActivityThreshold;
+}
+/** The desktop apps, by bundle id, and the bundle names they ship under. */
+export declare const DESKTOP_APPS: Readonly<Record<CodingTool, {
+    bundleId: string;
+    bundles: readonly string[];
+}>>;
+/** `originator` the Codex app writes into its sessions' first line. */
+export declare const CODEX_APP_ORIGINATOR = "Codex Desktop";
+/** Claude Code's project folder name for a working directory. */
+export declare function claudeProjectDirName(cwd: string): string;
+/**
+ * Is `bundleId` this Info.plist's CFBundleIdentifier? An XML plist is read by
+ * key. A binary plist has no readable key/value pairing, so it matches when the
+ * whole id (not a prefix of a longer one, like `com.openai.codex.skill`)
+ * appears in it.
+ */
+export declare function plistBundleIdIs(plist: Buffer, bundleId: string): boolean;
+/**
+ * Is this desktop app installed? Looks for its bundle names in
+ * `/Applications` and `~/Applications` and checks the bundle id in each
+ * candidate's Info.plist (XML or binary: the id is stored as plain text in both).
+ */
+export declare function desktopAppInstalled(tool: CodingTool, opts: {
+    home: string;
+    applicationsDirs?: string[];
+}): boolean;
+/**
+ * The HQ folders and session ids that belong to HQ's bots on this computer.
+ * Reads only the bots' own small config and session files.
+ */
+export declare function collectHqBotExclusions(dir?: string): HqBotExclusions;
+/**
+ * Is this the Codex app's own session? Reads `originator` and `source` from
+ * the start of the rollout's first line (its `session_meta` record).
+ */
+export declare function isCodexAppSession(head: string): boolean;
+/** Sessions and distinct days within the window ending at `now`. */
+export declare function summarizeActivity(times: readonly number[], now: Date, windowDays: number): {
+    sessions: number;
+    days: number;
+};
+export declare function qualifies(activity: {
+    installed?: boolean;
+    sessions: number;
+    days: number;
+}, threshold?: ActivityThreshold): boolean;
+/**
+ * The app to offer: the one that qualifies, or, when both do, the one with
+ * more sessions in the window (Claude on a tie).
+ */
+export declare function pickCodingTool(claude: {
+    installed?: boolean;
+    sessions: number;
+    days: number;
+}, codex: {
+    installed?: boolean;
+    sessions: number;
+    days: number;
+}, threshold?: ActivityThreshold): CodingTool | null;
+/** Look for the Claude and Codex desktop apps and their recent sessions, and pick one to offer, if any. */
+export declare function detectCodingToolActivity(input: DetectCodingToolActivityInput): CodingToolActivity;
+//# sourceMappingURL=coding-tool-activity.d.ts.map

package/dist/lib/bot/coding-tool-activity.js

@@ -0,0 +1,372 @@
+/**
+ * Does the person already use the Claude app or the Codex app a lot on this
+ * computer?
+ *
+ * The setup bot asks this before its first message: someone who works in one
+ * of those desktop apps is offered to continue setup there. Only the desktop
+ * apps count, never the command-line tools, and only on macOS:
+ *
+ * 1. The app must be installed: `Claude.app` (bundle id
+ *    `com.anthropic.claudefordesktop`), or `ChatGPT.app` / `Codex.app`
+ *    carrying Codex (bundle id `com.openai.codex`), in `/Applications` or
+ *    `~/Applications`. The bundle id is checked, so another OpenAI app such as
+ *    ChatGPT Atlas (`com.openai.atlas`) never counts.
+ * 2. The app must have recent sessions of its own:
+ *    - Claude: the Claude app keeps one small record per Code session at
+ *      `~/Library/Application Support/Claude/claude-code-sessions/<account>/<org>/local_<id>.json`.
+ *      Sessions started with the `claude` command never get one, so CLI use
+ *      does not count. Only the record's `lastActivityAt` / `createdAt`
+ *      numbers and its `cwd` / `cliSessionId` (to skip HQ's bots) are read,
+ *      from the start of the file; the file's mtime is the fallback.
+ *    - Codex: the app and the CLI share `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`
+ *      (`CODEX_HOME` moves `~/.codex`). The first line of each file is a
+ *      `session_meta` record; a session the app ran says
+ *      `"originator":"Codex Desktop"` with `"source":"vscode"`. Sessions from
+ *      `codex` / `codex exec` (other originators, or source `exec`) and
+ *      sub-agent threads (an object source) do not count. Only those two
+ *      fields are read, from the start of the first line; the file's mtime
+ *      is when it was last used.
+ *
+ * Nothing else in a session is read, and nothing about a session leaves this
+ * module except two numbers per app (sessions and distinct days in the window).
+ *
+ * HQ's own bots are not the person. Any session whose id a bot has on file
+ * (`session*.json` in each bot folder) is skipped, and so is a Claude session
+ * whose folder is under the bots' own folder.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { botsRoot } from "./paths.js";
+/**
+ * "Significant recent activity": at least `minSessions` sessions, spread over
+ * at least `minDistinctDays` calendar days, within the last `windowDays` days.
+ */
+export const SIGNIFICANT_CODING_TOOL_ACTIVITY = Object.freeze({
+    windowDays: 14,
+    minSessions: 5,
+    minDistinctDays: 3,
+});
+/** The desktop apps, by bundle id, and the bundle names they ship under. */
+export const DESKTOP_APPS = Object.freeze({
+    claude: { bundleId: "com.anthropic.claudefordesktop", bundles: ["Claude.app"] },
+    codex: { bundleId: "com.openai.codex", bundles: ["ChatGPT.app", "Codex.app"] },
+});
+/** `originator` the Codex app writes into its sessions' first line. */
+export const CODEX_APP_ORIGINATOR = "Codex Desktop";
+/** Stop counting after this many session files per app, so a huge history cannot stall a start. */
+const MAX_FILES_PER_TOOL = 20_000;
+/** How much of a file is read to find the few metadata fields used. */
+const HEAD_BYTES = 8 * 1024;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * A Codex session lives in the folder of the day it started, but a resumed one
+ * is still written to later. Dated folders are only skipped when they are this
+ * many days older than the window, so a resumed session is still counted.
+ */
+const CODEX_FOLDER_MARGIN_DAYS = 31;
+/** Claude Code's project folder name for a working directory. */
+export function claudeProjectDirName(cwd) {
+    return path.resolve(cwd).replace(/[^a-zA-Z0-9]/g, "-");
+}
+function codexHome(home, env) {
+    const override = env.CODEX_HOME?.trim();
+    return override ? override : path.join(home, ".codex");
+}
+function readDirSafe(dir) {
+    try {
+        return fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+}
+function mtimeMs(file) {
+    try {
+        return fs.statSync(file).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+/** The first `HEAD_BYTES` of a file as text, or null. */
+function readHead(file) {
+    let fd;
+    try {
+        fd = fs.openSync(file, "r");
+        const buf = Buffer.alloc(HEAD_BYTES);
+        const n = fs.readSync(fd, buf, 0, HEAD_BYTES, 0);
+        return buf.subarray(0, n).toString("utf8");
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                /* already closed */
+            }
+        }
+    }
+}
+function jsonString(head, key) {
+    const m = new RegExp(`"${key}"\\s*:\\s*"((?:[^"\\\\]|\\\\.)*)"`).exec(head);
+    if (!m)
+        return null;
+    try {
+        return JSON.parse(`"${m[1]}"`);
+    }
+    catch {
+        return null;
+    }
+}
+function jsonNumber(head, key) {
+    const m = new RegExp(`"${key}"\\s*:\\s*(\\d+(?:\\.\\d+)?)`).exec(head);
+    return m ? Number(m[1]) : null;
+}
+/**
+ * Is `bundleId` this Info.plist's CFBundleIdentifier? An XML plist is read by
+ * key. A binary plist has no readable key/value pairing, so it matches when the
+ * whole id (not a prefix of a longer one, like `com.openai.codex.skill`)
+ * appears in it.
+ */
+export function plistBundleIdIs(plist, bundleId) {
+    if (plist.subarray(0, 6).toString("latin1") !== "bplist") {
+        const m = /<key>\s*CFBundleIdentifier\s*<\/key>\s*<string>\s*([^<\s]+)\s*<\/string>/.exec(plist.toString("utf8"));
+        return m?.[1] === bundleId;
+    }
+    const needle = Buffer.from(bundleId, "utf8");
+    for (let at = plist.indexOf(needle); at !== -1; at = plist.indexOf(needle, at + 1)) {
+        const next = plist[at + needle.length];
+        if (next === undefined || !/[A-Za-z0-9.-]/.test(String.fromCharCode(next)))
+            return true;
+    }
+    return false;
+}
+/**
+ * Is this desktop app installed? Looks for its bundle names in
+ * `/Applications` and `~/Applications` and checks the bundle id in each
+ * candidate's Info.plist (XML or binary: the id is stored as plain text in both).
+ */
+export function desktopAppInstalled(tool, opts) {
+    const { bundleId, bundles } = DESKTOP_APPS[tool];
+    const dirs = opts.applicationsDirs ?? ["/Applications", path.join(opts.home, "Applications")];
+    for (const dir of dirs) {
+        for (const bundle of bundles) {
+            try {
+                const plist = fs.readFileSync(path.join(dir, bundle, "Contents", "Info.plist"));
+                if (plistBundleIdIs(plist, bundleId))
+                    return true;
+            }
+            catch {
+                /* not there */
+            }
+        }
+    }
+    return false;
+}
+/**
+ * The HQ folders and session ids that belong to HQ's bots on this computer.
+ * Reads only the bots' own small config and session files.
+ */
+export function collectHqBotExclusions(dir = botsRoot()) {
+    const hqRoots = new Set();
+    const sessionIds = new Set();
+    for (const bot of readDirSafe(dir)) {
+        if (!bot.isDirectory())
+            continue;
+        const botDir = path.join(dir, bot.name);
+        try {
+            const config = JSON.parse(fs.readFileSync(path.join(botDir, "bot.json"), "utf8"));
+            if (typeof config.hqRoot === "string" && config.hqRoot.trim())
+                hqRoots.add(config.hqRoot.trim());
+        }
+        catch {
+            /* no usable bot.json */
+        }
+        for (const entry of readDirSafe(botDir)) {
+            if (!entry.isFile() || !/^session.*\.json$/.test(entry.name))
+                continue;
+            try {
+                const session = JSON.parse(fs.readFileSync(path.join(botDir, entry.name), "utf8"));
+                if (typeof session.sessionId === "string" && session.sessionId.trim())
+                    sessionIds.add(session.sessionId.trim());
+            }
+            catch {
+                /* unreadable session file */
+            }
+        }
+    }
+    return { hqRoots: [...hqRoots], sessionIds: [...sessionIds] };
+}
+function isBotSession(name, sessionIds) {
+    return sessionIds.some((id) => name.includes(id));
+}
+function isUnder(child, parent) {
+    const rel = path.relative(path.resolve(parent), path.resolve(child));
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+/** When each of the Claude app's own Code sessions was last used. */
+function claudeAppSessionTimes(home, bots, sessionIds, windowStart) {
+    const times = [];
+    const root = path.join(home, "Library", "Application Support", "Claude", "claude-code-sessions");
+    for (const account of readDirSafe(root)) {
+        if (!account.isDirectory())
+            continue;
+        for (const org of readDirSafe(path.join(root, account.name))) {
+            if (!org.isDirectory())
+                continue;
+            const orgDir = path.join(root, account.name, org.name);
+            for (const file of readDirSafe(orgDir)) {
+                if (!file.isFile() || !file.name.startsWith("local_") || !file.name.endsWith(".json"))
+                    continue;
+                const full = path.join(orgDir, file.name);
+                const mtime = mtimeMs(full);
+                // A record is rewritten whenever its session is used, so one untouched
+                // since before the window cannot hold a use inside it.
+                if (mtime === null || mtime < windowStart)
+                    continue;
+                if (isBotSession(file.name, sessionIds))
+                    continue;
+                const head = readHead(full) ?? "";
+                const cliSessionId = jsonString(head, "cliSessionId");
+                if (cliSessionId && sessionIds.includes(cliSessionId))
+                    continue;
+                const cwd = jsonString(head, "cwd");
+                if (cwd && isUnder(cwd, bots))
+                    continue;
+                const used = jsonNumber(head, "lastActivityAt") ?? jsonNumber(head, "createdAt") ?? mtime;
+                times.push(used);
+                if (times.length >= MAX_FILES_PER_TOOL)
+                    return times;
+            }
+        }
+    }
+    return times;
+}
+/**
+ * Is this the Codex app's own session? Reads `originator` and `source` from
+ * the start of the rollout's first line (its `session_meta` record).
+ */
+export function isCodexAppSession(head) {
+    const firstLine = head.split("\n", 1)[0] ?? "";
+    if (!/"type"\s*:\s*"session_meta"/.test(firstLine))
+        return false;
+    if (jsonString(firstLine, "originator") !== CODEX_APP_ORIGINATOR)
+        return false;
+    // A sub-agent thread has an object source; `codex exec` says "exec".
+    if (/"source"\s*:\s*\{/.test(firstLine))
+        return false;
+    const source = jsonString(firstLine, "source");
+    return source !== "exec";
+}
+/** Last-used times of the Codex app's own sessions. */
+function codexAppSessionTimes(root, sessionIds, oldestDay, windowStart) {
+    const times = [];
+    const walk = (dir, depth, datePrefix) => {
+        for (const entry of readDirSafe(dir)) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (depth >= 3)
+                    continue;
+                const dated = /^\d+$/.test(entry.name);
+                const prefix = dated ? (datePrefix ? `${datePrefix}-${entry.name}` : entry.name) : datePrefix;
+                // sessions/YYYY/MM/DD: a year, month or day wholly before the window is skipped.
+                if (dated && prefix < oldestDay.slice(0, prefix.length))
+                    continue;
+                if (!walk(full, depth + 1, prefix))
+                    return false;
+                continue;
+            }
+            if (!entry.isFile() || !entry.name.startsWith("rollout-") || !entry.name.endsWith(".jsonl"))
+                continue;
+            if (isBotSession(entry.name, sessionIds))
+                continue;
+            const t = mtimeMs(full);
+            if (t === null || t < windowStart)
+                continue;
+            const head = readHead(full);
+            if (!head || !isCodexAppSession(head))
+                continue;
+            times.push(t);
+            if (times.length >= MAX_FILES_PER_TOOL)
+                return false;
+        }
+        return true;
+    };
+    walk(path.join(root, "sessions"), 0, "");
+    return times;
+}
+function localDay(ms) {
+    const d = new Date(ms);
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+/** Sessions and distinct days within the window ending at `now`. */
+export function summarizeActivity(times, now, windowDays) {
+    const end = now.getTime();
+    const start = end - windowDays * DAY_MS;
+    const days = new Set();
+    let sessions = 0;
+    for (const t of times) {
+        if (t < start || t > end)
+            continue;
+        sessions += 1;
+        days.add(localDay(t));
+    }
+    return { sessions, days: days.size };
+}
+export function qualifies(activity, threshold = SIGNIFICANT_CODING_TOOL_ACTIVITY) {
+    if (activity.installed === false)
+        return false;
+    return activity.sessions >= threshold.minSessions && activity.days >= threshold.minDistinctDays;
+}
+/**
+ * The app to offer: the one that qualifies, or, when both do, the one with
+ * more sessions in the window (Claude on a tie).
+ */
+export function pickCodingTool(claude, codex, threshold = SIGNIFICANT_CODING_TOOL_ACTIVITY) {
+    const c = qualifies(claude, threshold);
+    const x = qualifies(codex, threshold);
+    if (c && x)
+        return codex.sessions > claude.sessions ? "codex" : "claude";
+    if (c)
+        return "claude";
+    if (x)
+        return "codex";
+    return null;
+}
+/** Look for the Claude and Codex desktop apps and their recent sessions, and pick one to offer, if any. */
+export function detectCodingToolActivity(input) {
+    const home = input.home ?? os.homedir();
+    const env = input.env ?? process.env;
+    const platform = input.platform ?? process.platform;
+    const threshold = input.threshold ?? SIGNIFICANT_CODING_TOOL_ACTIVITY;
+    const none = { installed: false, sessions: 0, days: 0 };
+    if (platform !== "darwin")
+        return { claude: none, codex: none, pick: null };
+    const bots = input.botsDir ?? botsRoot(home, env);
+    const exclusions = collectHqBotExclusions(bots);
+    const windowStart = input.now.getTime() - threshold.windowDays * DAY_MS;
+    const apps = { home, ...(input.applicationsDirs ? { applicationsDirs: input.applicationsDirs } : {}) };
+    const claudeInstalled = desktopAppInstalled("claude", apps);
+    const codexInstalled = desktopAppInstalled("codex", apps);
+    const claude = claudeInstalled
+        ? {
+            installed: true,
+            ...summarizeActivity(claudeAppSessionTimes(home, bots, exclusions.sessionIds, windowStart), input.now, threshold.windowDays),
+        }
+        : none;
+    const oldestDay = localDay(input.now.getTime() - (threshold.windowDays + CODEX_FOLDER_MARGIN_DAYS) * DAY_MS);
+    const codex = codexInstalled
+        ? {
+            installed: true,
+            ...summarizeActivity(codexAppSessionTimes(codexHome(home, env), exclusions.sessionIds, oldestDay, windowStart), input.now, threshold.windowDays),
+        }
+        : none;
+    return { claude, codex, pick: pickCodingTool(claude, codex, threshold) };
+}
+//# sourceMappingURL=coding-tool-activity.js.map

package/dist/lib/bot/run.d.ts

@@ -49,6 +49,7 @@ import { type BotApi, type InboxItem } from "./api.js";
 import type { BotConfig, BotKind } from "./config.js";
 import { containsNoReplySentinel, type ProgressPosterOptions } from "./progress.js";
 import { type BotLogger } from "./log.js";
+import { type CodingToolActivity, type DetectCodingToolActivityInput } from "./coding-tool-activity.js";
 import { type BotRuntime, type RuntimeTurnInput, type RuntimeTurnResult } from "./runtime/index.js";
 import type { VaultObjectDownloader } from "../agent-kit/attachment-download.js";
 import { type HeartbeatAgentUidSource, type HeartbeatCredsSource, type HeartbeatIdentityMismatchReporter } from "../heartbeat-identity.js";
@@ -166,6 +167,12 @@ export interface BotRunDeps {
      * exit: the place to start a replacement when no supervisor will.
      */
     onCliUpdateRestart?: (update: CliUpdate, log: BotLogger) => void;
+    /**
+     * The setup bot's look at this computer's Claude Code and Codex use before
+     * its first message (coding-tool-activity.ts). Injected in tests so they
+     * never read the real home folder.
+     */
+    detectCodingToolActivity?: (input: DetectCodingToolActivityInput) => CodingToolActivity;
 }
 export declare const KICKOFF_MESSAGE_ID = "kickoff";
 /**