howtofixcli 0.7.24 → 0.7.26

package/dist/session-retention.js

@@ -0,0 +1,111 @@
+import { readdir, rmdir, stat, unlink } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { RETENTION_DAYS } from "./checkpoint.js";
+import { AGENT_DIR } from "./paths.js";
+/**
+ * Unlink session files idle for longer than `RETENTION_DAYS`, across every
+ * project directory — the store's whole problem is that it is per-cwd and
+ * nothing ever looked outside the current one.
+ *
+ * The SDK writes `<agentDir>/sessions/--<encoded-cwd>--/<timestamp>_<id>.jsonl`
+ * and never removes one: `SessionManager` only appends, the TUI's delete is a
+ * single user-chosen session (and prefers `trash`), and the CLI had no sweep at
+ * all, so a machine that uses the product for a year keeps a transcript of every
+ * folder it was ever pointed at. Rewind's shadow store already sweeps at 30 days
+ * (checkpoint.ts, `RETENTION_DAYS`) — same window here on purpose, so "old" means
+ * one thing across both stores and a session whose snapshots are gone does not
+ * linger as a transcript.
+ *
+ * Age is the file's mtime, not the timestamp in its name: a session resumed last
+ * week was written last week and must survive, while its filename still says the
+ * day it was created. `keep` is the stronger rule on top of that — `--continue`
+ * and `/resume` exist to bring an old session back, so the file this process just
+ * opened is kept whatever its age.
+ *
+ * Housekeeping, so it never throws and never reports to the user: every step is
+ * per-file, an error only leaves the store larger than it needed to be. Files are
+ * unlinked rather than trashed — the TUI's `trash` path is a person deleting one
+ * session they chose, this is a bulk sweep they did not ask to watch.
+ */
+export async function sweepStaleSessions(options = {}) {
+    const result = { removed: [], failed: [], removedDirs: [] };
+    const root = join(options.agentDir ?? AGENT_DIR, "sessions");
+    const cutoff = (options.now ?? Date.now()) - RETENTION_DAYS * 24 * 60 * 60 * 1000;
+    const keep = options.keep ? resolve(options.keep) : undefined;
+    let projects;
+    try {
+        projects = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        // No store, or an unreadable one: nothing to sweep and nothing to say.
+        return result;
+    }
+    for (const project of projects) {
+        if (!project.isDirectory())
+            continue;
+        const dir = join(root, project.name);
+        let files;
+        try {
+            files = await readdir(dir);
+        }
+        catch {
+            continue;
+        }
+        // What will still be in the directory when the sweep is done. Sidecars a
+        // stale session left behind (`plan.md`, `plan_mode.json`) count and keep the
+        // directory on purpose: they are project state a later session of the same
+        // folder still restores.
+        const surviving = files.filter((file) => !file.endsWith(".jsonl"));
+        for (const file of files) {
+            if (!file.endsWith(".jsonl"))
+                continue;
+            const path = join(dir, file);
+            let stale;
+            try {
+                if (keep && resolve(path) === keep)
+                    stale = false;
+                else {
+                    // mtime, not the timestamp in the name: a session resumed last week
+                    // was written last week, whatever its filename says.
+                    stale = (await stat(path)).mtimeMs < cutoff;
+                }
+            }
+            catch {
+                // Raced with another sweeper (two processes starting at once).
+                stale = false;
+            }
+            if (!stale) {
+                surviving.push(file);
+                continue;
+            }
+            try {
+                await unlink(path);
+                result.removed.push(path);
+            }
+            catch {
+                // A directory called `x.jsonl`, a permission wall, a file another
+                // process holds oddly: count it and keep going.
+                result.failed.push(path);
+                surviving.push(file);
+            }
+        }
+        // Drop the per-project directory when nothing is left in it, so the encoded
+        // cwd names stop piling up too.
+        if (surviving.length === 0) {
+            // Never drop the directory the live session writes into. On a fresh start
+            // the session file does not exist yet, so the directory looks empty and
+            // the sweep removed it — the next prompt then failed with ENOENT because
+            // the writer's parent had been deleted underneath it.
+            if (keep && dirname(keep) === dir)
+                continue;
+            try {
+                await rmdir(dir);
+                result.removedDirs.push(dir);
+            }
+            catch {
+                // Non-empty after all, or racing a writer: the directory stays.
+            }
+        }
+    }
+    return result;
+}

package/dist/session.js

@@ -0,0 +1,460 @@
+import { join } from "node:path";
+import { hostname } from "node:os";
+import { createAgentSession, createCodemodeExtension, createMcpExtension, DefaultResourceLoader, ProjectTrustStore, SessionManager, SettingsManager } from "@netrodev/hxf-coding-agent";
+import { APP_VERSION, SYSTEM_APPEND, scrubHarnessMessage } from "./brand.js";
+import { promptAppendBlocks } from "./prompt-files.js";
+import { createBrandExtension } from "./brand-extension.js";
+import { createHooksExtension } from "./hooks-extension.js";
+import { AGENT_DIR, additionalSkillPaths } from "./paths.js";
+import { readCliCredential, renewCliCredentialIfNeeded } from "./cli-credentials.js";
+import { createPermissionExtension } from "./permissions.js";
+import { loadMcpConfiguration } from "./mcp-config.js";
+/** Session entry type the running build stamps itself under. */
+export const BUILD_ENTRY = "howtofix.build";
+import { createRtkExtension } from "./rtk.js";
+import { readWorkbenchSettings } from "./settings.js";
+import { askTool, claimTool, sessionsTool, setClaimsContext, thinkTool } from "./tools.js";
+import { repoMapTool, setRepoRoot } from "./repo-map.js";
+import { SESSIONS_DIR_NAME, PRESENCE_TTL_MS, announce, withdraw } from "./sessions.js";
+import { todoTool } from "./todo.js";
+import { contextTool } from "./notes.js";
+import { goalTool } from "./goal.js";
+import { createPlanGateExtension, createPlanPromptExtension, enterPlanModeTool, exitPlanModeTool } from "./plan-mode.js";
+import { createCompactionGuardExtension } from "./compaction-guard.js";
+import { createGoalExtension } from "./goal-extension.js";
+import { createContextExtension } from "./context-extension.js";
+import { createPresetExtension } from "./preset-extension.js";
+import { createDcpExtension, createCompressTool, getDcpState, activeDcpSession, snapshotFor } from "./dcp/index.js";
+import { createWorkflowTool } from "./workflow.js";
+import { createTaskTool } from "./subagent.js";
+import { loadAgentDefs } from "./agent-defs.js";
+import { agents } from "./agents.js";
+import { defaultModelFor, resolveModel } from "./model-resolve.js";
+import { HOWTOFIX_PROVIDERS } from "./howtofix-account.js";
+import { activateExtraBuiltins, settleExtensionTools } from "./tool-loadout.js";
+import { webFetchTool, webSearchTool } from "./web-tools.js";
+import { lspTool } from "./lsp-tools.js";
+import { qualityTool } from "./quality-tool.js";
+import { slopTool } from "./slop-tool.js";
+import { disposeAllLsp } from "./lsp.js";
+import { disposeAgentSession } from "./session-lifecycle.js";
+import { sweepStaleSessions } from "./session-retention.js";
+/**
+ * Every tool this product offers, as documentation of the surface.
+ *
+ * The loadout is NOT applied from here: it is the exclusion in `toolLoadout()`
+ * plus the activation in `tool-loadout.ts`. An allowlist was tried and removed —
+ * it applies to *every* registered tool including extension ones, so it discarded
+ * `mcp__<server>__<tool>` names that cannot be known in advance and undid the MCP
+ * extension's `codemode` activation. See the decisions log.
+ *
+ * It is deliberately not exported or referenced: if it ever becomes the thing
+ * that decides the loadout again, the MCP regressions come back. The active set is
+ * asserted by `scripts/check-tool-loadout.mjs`.
+ */
+export const MAIN_TOOLS = [
+    "read",
+    "repo_map",
+    "bash",
+    "edit",
+    "write",
+    "grep",
+    "find",
+    "ls",
+    "bash_output",
+    "kill_shell",
+    "task",
+    "think",
+    "ask",
+    "claim",
+    "sessions",
+    "todo",
+    "context",
+    "goal",
+    "enter_plan_mode",
+    "exit_plan_mode",
+    "workflow",
+    "web_search",
+    "web_fetch",
+    "lsp",
+    "quality",
+    "compress",
+    "slop",
+];
+/**
+ * The tool loadout for this platform, expressed as an exclusion rather than an
+ * allowlist.
+ *
+ * `tools:` is an allowlist that filters *every* registered tool, extension ones
+ * included (`_refreshToolRegistry` → `_isAllowedTool`), so naming only our own
+ * tools silently drops any tool an extension registers later under a name we
+ * cannot know — `mcp__<server>__<tool>` above all. Measured: an MCP server
+ * connected, `/mcp` reported "14 tools", and the model could call none of them
+ * because the allowlist had already discarded every one.
+ *
+ * `codemode` was the same bug in miniature. The MCP extension activates it at
+ * `session_start` whenever a server's tools are only reachable from scripts (the
+ * default `exposure: "codemode"`), but the allowlist filter runs when the tool
+ * registry is rebuilt, after that activation, so a static list undid it — and the
+ * user got "MCP tools are only reachable from the codemode or tool_search tool,
+ * but neither is active" on a fully connected server.
+ *
+ * Without `tools:`, the SDK enables its default set plus everything extensions
+ * register, and activation sticks. The one piece of policy left — the SDK's
+ * `powershell` tool, which throws "only available on Windows" everywhere else,
+ * while `bash` resolves to Git Bash that Windows does not ship — becomes an
+ * exclusion.
+ */
+const toolLoadout = () => ({
+    exclude: process.platform === "win32" ? [] : ["powershell"],
+});
+/**
+ * Every way the CLI can start — the workbench, `--print`, `-c`, `--session-path`
+ * — reaches `openSession`, so the session-file retention sweep hangs here rather
+ * than in the workbench alone: a scripted run is exactly the thing that used to
+ * leave a transcript behind. Once per process, because a `/new` or `/resume`
+ * swap opens another session in the same process and the store does not need a
+ * second walk to know it is stale.
+ */
+let sessionsSwept = false;
+export async function openSession(options) {
+    // Trust is a decision the user made about this directory, not a constant.
+    //
+    // This used to pass `projectTrusted: true` unconditionally, which loaded the
+    // project's own settings, `SYSTEM.md`, `APPEND_SYSTEM.md` and extensions from
+    // `.hxf/` in whatever directory the CLI was started in. Cloning a repository
+    // and running `howtofix` in it was therefore enough to replace the system
+    // prompt: a `.hxf/SYSTEM.md` saying "ignore all previous instructions" was
+    // read as trusted configuration. The store is what the harness consults, and
+    // the answer is only "yes" for a directory the user trusted.
+    const trustStore = new ProjectTrustStore(AGENT_DIR);
+    const settingsManager = SettingsManager.create(options.cwd, AGENT_DIR, {
+        projectTrusted: trustStore.get(options.cwd) === true,
+    });
+    // Read once at open and refreshed by the slash command. The extension consults this
+    // variable per tool result, so a change applies immediately without reopening the
+    // session — which is what a toggle should do.
+    let rtkEnabled = readWorkbenchSettings(AGENT_DIR).compressToolOutput;
+    const sessionManager = options.sessionPath ? SessionManager.open(options.sessionPath) : options.noSession ? SessionManager.inMemory(options.cwd) : options.continueSession ? SessionManager.continueRecent(options.cwd) : SessionManager.create(options.cwd);
+    // A session written by a different build is a compatibility question the user
+    // should not have to guess at. The file header records the *format* version
+    // (the SDK's), not the product's, so a session from another release loads
+    // silently and any behaviour that changed between them reads as a bug. Read
+    // the stamp the previous build left and say when it differs.
+    // Read the stamp off the session that was opened, whatever route opened it:
+    // `--continue` and `/resume` reach the same file as `--session`, and keying
+    // this on `sessionPath` alone meant the warning never fired for the two ways
+    // a user actually returns to an old session.
+    const buildNote = (() => {
+        try {
+            const previous = sessionManager.getEntries().find((entry) => entry.type === "custom" && entry.customType === BUILD_ENTRY);
+            const was = previous?.data?.version;
+            if (!was || was === APP_VERSION)
+                return undefined;
+            return `this session was written by HowToFix ${was}; you are running ${APP_VERSION}`;
+        }
+        catch {
+            // An unreadable or older file is not a reason to refuse to open it.
+            return undefined;
+        }
+    })();
+    const resourceLoader = new DefaultResourceLoader({
+        cwd: options.cwd,
+        agentDir: AGENT_DIR,
+        settingsManager,
+        appendSystemPrompt: promptAppendBlocks(SYSTEM_APPEND, options.interactive ?? true),
+        // The SDK discovers `<agentDir>/skills` itself through the package manager,
+        // and the project dir is its own `.hxf`, so both the user's
+        // `.howtofix/skills` and the bundled suite are handed over here. The user's
+        // dir comes first (first-wins on a name collision), and the bundled suite
+        // drops out of the list entirely when the antislop switch resolves off.
+        additionalSkillPaths: additionalSkillPaths(options.cwd),
+        extensionFactories: [
+            // The plan gate must come first: the SDK returns on the first `block`, so
+            // registering it ahead of the approval gate is what makes plan mode hold in
+            // every approval mode, `full-auto` included.
+            createPlanGateExtension(),
+            createPermissionExtension(),
+            createBrandExtension(),
+            createHooksExtension(),
+            // DCP sits between brand and the notes, and both neighbours matter.
+            // Before brand and the id tags it writes into the prompt are scrubbed
+            // back out; after context-extension and the shared notes become keep-set
+            // candidates and get pruned. `check-dcp.mjs` asserts the order with three
+            // handlers that overwrite each other — acceptance covers it, but if you
+            // move this line, that check fails and it is right to fail.
+            createDcpExtension(),
+            createContextExtension(),
+            // After the notes so a preset's rules are appended last, and after brand
+            // so the harness scrub has already run over the sections it owns.
+            createPresetExtension(options.cwd),
+            createGoalExtension(),
+            createPlanPromptExtension(),
+            createCompactionGuardExtension(),
+            createCodemodeExtension(),
+            // Reads the setting per tool result, so `/rtk on` takes effect on the next tool
+            // call rather than on the next process.
+            createRtkExtension({ enabled: () => rtkEnabled }),
+            // A loader that re-reads `mcp.json` each time the extension asks, so a
+            // server removed from the preset menu is seen as gone and its transport is
+            // closed. The SDK reads the file once on `session_start` otherwise, which
+            // left the removed server's process running until the CLI exited.
+            createMcpExtension({
+                loadConfig: (ctx) => loadMcpConfiguration({
+                    cwd: ctx.cwd,
+                    projectTrusted: ctx.isProjectTrusted?.() ?? false,
+                }),
+            }),
+        ],
+    });
+    await resourceLoader.reload();
+    // Subagent definitions the user wrote, read before the session is built so the
+    // `task` tool's description can name them: a definition the model is never told
+    // about is a definition that does not exist. Problems are reported as notes
+    // rather than thrown — a typo in one file must not stop the CLI from opening.
+    const agentDefs = loadAgentDefs(options.cwd, agents);
+    // Built after the definitions are in the map, so the description names them.
+    const taskTool = createTaskTool();
+    // Claims are held per session and written under the session's workspace. The
+    // holder id has to be stable for the whole session — a claim that cannot be
+    // renewed or released by the agent that took it is worse than no claim — so it
+    // is derived from the session the manager opened, not from the process.
+    const sessionId = sessionManager.getSessionId();
+    setRepoRoot(() => options.cwd);
+    const presenceDir = join(AGENT_DIR, SESSIONS_DIR_NAME);
+    setClaimsContext({
+        root: () => options.cwd,
+        holder: () => `session:${sessionId}`,
+        presenceDir: () => presenceDir,
+        selfId: () => sessionId,
+    });
+    // Announce this session so another one in the same workspace can see it and ask
+    // for a file it holds. Heartbeat, not a one-shot write: liveness is decided by the
+    // freshness of the file, so a session that is killed drops out on its own without
+    // anything having to reap it.
+    const beat = () => {
+        try {
+            announce({ dir: presenceDir }, { id: sessionId, cwd: options.cwd, host: hostname(), pid: process.pid, at: Date.now() });
+        }
+        catch {
+            // A session that cannot write its presence still works; it is simply invisible
+            // to the others. Failing the session over this would be the worse trade.
+        }
+    };
+    beat();
+    const heartbeat = setInterval(beat, Math.max(5_000, Math.floor(PRESENCE_TTL_MS / 3)));
+    // A background interval must not hold the process open on its own.
+    heartbeat.unref?.();
+    const result = await createAgentSession({
+        cwd: options.cwd,
+        agentDir: AGENT_DIR,
+        settingsManager,
+        sessionManager,
+        resourceLoader,
+        excludeTools: toolLoadout().exclude,
+        customTools: [
+            taskTool,
+            repoMapTool,
+            thinkTool,
+            askTool,
+            claimTool,
+            sessionsTool,
+            todoTool,
+            contextTool,
+            goalTool,
+            enterPlanModeTool,
+            exitPlanModeTool,
+            createWorkflowTool(),
+            webSearchTool,
+            webFetchTool,
+            lspTool,
+            qualityTool,
+            slopTool,
+            // The compress tool resolves its boundaries against the ref snapshot the
+            // handler published on the last prompt pass. Registering it here rather
+            // than inside the extension is the pattern this file uses for every
+            // custom tool, and the SDK enables a custom tool only when it is named in
+            // `tools` too - which is why `compress` also appears in MAIN_TOOLS.
+            createCompressTool({
+                state: () => getDcpState(activeDcpSession() ?? "dcp-sessionless"),
+                messages: () => snapshotFor(activeDcpSession() ?? "dcp-sessionless"),
+            }),
+        ],
+        thinkingLevel: options.thinking,
+    });
+    // Activate the built-in search tools the product relies on.
+    //
+    // The harness now enables `grep`, `find` and `ls` by default, so this is a
+    // belt-and-braces pass rather than the only thing making them callable: the
+    // product names its active set explicitly, and a harness default that changes
+    // again must not silently cost the model tools that `permissions.ts` carries
+    // approval tiers for and `agents.ts` tells every subagent to use. Before the
+    // harness default existed, the model reported `read, bash, edit, write, task, …`
+    // and answered "NO GREP TOOL" while the implementations sat in the registry.
+    //
+    // This has to happen here, through the public session API, and NOT in an
+    // extension. An extension's `session_start` handler runs inside
+    // `bindExtensions()`, which the SDK follows with `_refreshToolRegistry()` — so
+    // anything `setActiveTools` did there is silently overwritten before the first
+    // turn. Measured: the extension ran, `setActiveTools` was called, and the
+    // active set was still `bash, edit, read, write`.
+    //
+    // Bind the extensions here, once, for every way the CLI can be started.
+    //
+    // `bindExtensions()` is what emits `session_start`, and `session_start` is where
+    // extensions do their work: the MCP extension connects its servers and turns on
+    // `codemode`, the hooks extension installs its handlers. It used to be called
+    // only from the workbench's `bindUI`, so a `--print` run (`-p`, which is what
+    // scripts and CI use) never emitted `session_start` at all: MCP servers were
+    // never connected, hooks never ran, and `codemode` was inactive.
+    //
+    // The mode is `"print"` so an extension asks through text instead of opening an
+    // overlay the workbench cannot host. `uiContext` is passed when a caller has
+    // one (the workbench does, after this returns, via `bindUI`); here it is the
+    // dialog-free context the SDK expects for non-interactive runs.
+    //
+    // This runs BEFORE `activateExtraBuiltins`: `bindExtensions` ends in the SDK's
+    // `_refreshToolRegistry()`, which resets the active set, so activating first
+    // would be undone.
+    await result.session.bindExtensions({ mode: "print", onError: () => { } });
+    // A short-lived access token has to be renewed before it is used, and this is
+    // the one place every way of starting the CLI goes through — the workbench
+    // renews again before each prompt, but `--print` never touches the workbench,
+    // so without this a scripted run on an expired token fails on its first call
+    // with nothing to explain it.
+    //
+    // A terminal refusal is reported as a note rather than thrown: the stored key
+    // may still work (the panel could be briefly unreachable, or the local clock
+    // could be ahead), and refusing to start would turn a recoverable state into a
+    // dead CLI.
+    const storedCredential = readCliCredential(AGENT_DIR);
+    const credentialNotes = [];
+    if (storedCredential) {
+        const renewed = await renewCliCredentialIfNeeded(AGENT_DIR, storedCredential);
+        if (renewed.renewed) {
+            await result.session.modelRuntime.setRuntimeApiKey("howtofix", renewed.credential.accessToken);
+        }
+        else if (renewed.terminal && renewed.message) {
+            credentialNotes.push(renewed.message);
+        }
+        else if (renewed.message) {
+            credentialNotes.push(renewed.message);
+        }
+    }
+    // `session_start` handlers are async and the runner does not await them, so
+    // give the ones that register tools (MCP's `codemode`) a moment to land before
+    // the first turn reads the loadout. This is bounded and only waits while the
+    // work is still in flight.
+    await settleExtensionTools(result.session);
+    // Only now, on the settled set, add the built-ins the SDK leaves inactive.
+    activateExtraBuiltins(result.session);
+    let model = result.session.model;
+    if (options.model) {
+        const available = await result.session.modelRuntime.getAvailable();
+        const requested = resolveModel(available, options.model);
+        if (!requested) {
+            await disposeAgentSession(result.session);
+            throw new Error(`unknown model '${options.model}'`);
+        }
+        if (model?.id !== requested.id || model.provider !== requested.provider) {
+            await result.session.setModel(requested);
+            model = result.session.model;
+        }
+    }
+    else {
+        // Nothing was asked for, so the runtime's own default stands — and that
+        // default is the catalogue's, not this account's. The runtime ships a
+        // built-in provider catalogue, so a fresh session can start on
+        // `opencode/kimi-k2.6`, a provider with no credential here: the first prompt
+        // then goes nowhere and comes back as an empty assistant message, with
+        // nothing in the transcript to say why it looks hung. Start on a model the
+        // account can actually reach instead, preferring HowToFix's own providers.
+        //
+        // Available is not the same as reachable — the catalogue lists every provider
+        // it knows — so each provider is asked for its credential, once.
+        const available = await result.session.modelRuntime.getAvailable();
+        const withKey = new Map();
+        const reachable = [];
+        for (const entry of available) {
+            let ok = withKey.get(entry.provider);
+            if (ok === undefined) {
+                ok = Boolean((await result.session.modelRuntime.getAuth(entry.provider))?.auth?.apiKey);
+                withKey.set(entry.provider, ok);
+            }
+            if (ok)
+                reachable.push(entry);
+        }
+        // A credential in the runtime is not proof the provider answers: the built-in
+        // catalogue carries providers whose key is absent at request time, which is
+        // how a session ends up on `opencode/kimi-k2.6` and gets a 401 with nothing
+        // in the transcript. So the account's own provider wins whenever it has any
+        // model at all — an install signed in to HowToFix should run HowToFix models.
+        const ownProviders = HOWTOFIX_PROVIDERS;
+        const startedOnOwn = ownProviders.includes(model?.provider ?? "");
+        if (!startedOnOwn) {
+            const chosen = defaultModelFor(reachable.filter((entry) => ownProviders.includes(entry.provider)), ownProviders);
+            if (chosen) {
+                await result.session.setModel(chosen);
+                model = result.session.model;
+            }
+        }
+    }
+    // Stamp this build into a session it is allowed to write. A read-only open
+    // (`--print`, a resumed file) is left untouched: the stamp belongs to the
+    // build that owns the session, not to whoever glanced at it.
+    if (!options.noSession && sessionManager.getEntries().every((entry) => entry.type !== "custom" || entry.customType !== BUILD_ENTRY)) {
+        try {
+            sessionManager.appendCustomEntry(BUILD_ENTRY, { version: APP_VERSION });
+        }
+        catch {
+            // A session that cannot be written (read-only file, full disk) still works.
+        }
+    }
+    // Retention sweep, once per process and off the critical path: session files
+    // under `~/.howtofix/agent/sessions/` only ever grow — the SDK appends and
+    // never prunes, and the TUI's delete is one session a person picked — so files
+    // idle for longer than RETENTION_DAYS are unlinked for *every* project, not
+    // just this one. The file just opened is kept whatever its age: `--continue`
+    // and `/resume` exist to bring an old session back, and a sweep that ate its
+    // own argument would break them. Not awaited — startup must not pay for a walk
+    // of every session directory, and a failed sweep leaves the store merely
+    // larger. See session-retention.ts.
+    if (!sessionsSwept) {
+        sessionsSwept = true;
+        void sweepStaleSessions({ keep: result.session.sessionFile }).catch(() => {
+            // Housekeeping: the store is larger, not wrong.
+        });
+    }
+    const modelLabel = model ? `${model.provider}/${model.id}` : "no model";
+    // A model with no declared rates reports $0 forever, which is what makes a
+    // budget unenforceable on it. See `priced` on `OpenedSession`.
+    const priced = Boolean(model && model.cost && (model.cost.input > 0 || model.cost.output > 0));
+    const notes = [scrubHarnessMessage(result.modelFallbackMessage), ...credentialNotes, ...agentDefs.notes, ...agentDefs.problems].filter((note) => Boolean(note));
+    if (!model) {
+        notes.push(`no model configured. run \`howtofix\` and use /login, or edit ${join(AGENT_DIR, "models.json")}`);
+    }
+    return {
+        session: result.session,
+        dispose: async () => {
+            // The lsp client pool is process-wide and shared with subagents; the main
+            // session is the owner that tears it down (process `exit` is the backstop).
+            disposeAllLsp();
+            // Await the extension shutdown so MCP servers stop before the session
+            // that hosts their tools goes away.
+            await disposeAgentSession(result.session);
+            // Take this session out of the registry on a clean exit. A crash is covered
+            // by the heartbeat going stale, so this only makes the common case immediate.
+            clearInterval(heartbeat);
+            withdraw({ dir: presenceDir }, sessionId);
+        },
+        modelLabel,
+        priced,
+        // Exposed so the `/rtk` command can flip the flag the extension reads. Passing a
+        // setter rather than the variable keeps the two in one place: there is no way to
+        // change the setting without changing what the extension sees.
+        setCompressToolOutput: (on) => {
+            rtkEnabled = on;
+        },
+        note: [buildNote, ...notes].filter(Boolean).join("\n") || undefined,
+    };
+}

package/dist/sessions.js

@@ -0,0 +1,100 @@
+/**
+ * A registry of other HowToFix CLI sessions on this machine.
+ *
+ * One process can only see the agents it started. Two sessions open on the same
+ * project — the user in one terminal and a long run in another — are invisible to each
+ * other, so neither can see what the other is holding, and a file claim taken by one
+ * cannot be explained to the other. This module is the smallest thing that closes that
+ * gap: each session writes one file describing itself, and any session can read them
+ * all.
+ *
+ * File-based for the same reason claims are: the sessions are separate processes, so
+ * there is no shared object to read and a broker would need something running. A file
+ * per session is what all of them can agree on without a daemon.
+ *
+ * A session that crashed must not appear as live. Liveness is the freshness of the
+ * heartbeat, not the presence of the file, so a killed process drops out on its own
+ * after {@link PRESENCE_TTL_MS} without anything having to clean up.
+ */
+import { mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/** How long a session stays "live" without refreshing its file. */
+export const PRESENCE_TTL_MS = 3 * 60 * 1000;
+/**
+ * Directory under the agent dir holding one file per live session.
+ *
+ * Deliberately not `sessions`: `session-retention.ts` owns that one and sweeps it,
+ * so a presence file written there would sit among per-project session files and — far
+ * worse — be a candidate for its sweep. A live session whose presence is deleted looks
+ * to every other session like one that died.
+ */
+export const SESSIONS_DIR_NAME = "presence";
+function file(options, id) {
+    // The id comes from the session, not from user input, but a path separator in it
+    // would still write the file somewhere else, so it is stripped rather than trusted.
+    return join(options.dir, `${id.replace(/[^A-Za-z0-9._-]/g, "_")}.json`);
+}
+/**
+ * Read every session's file, dropping the ones that are stale or unreadable.
+ *
+ * Unreadable means "not there": a half-written file from a session that is starting up
+ * must not make a reader fail, and a reader that cannot list sessions is worse than one
+ * that lists fewer.
+ */
+export function listSessions(options, now = Date.now()) {
+    let names;
+    try {
+        names = readdirSync(options.dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        if (!name.endsWith(".json"))
+            continue;
+        try {
+            const raw = JSON.parse(readFileSync(join(options.dir, name), "utf8"));
+            if (typeof raw?.id !== "string" || typeof raw?.cwd !== "string" || typeof raw?.at !== "number")
+                continue;
+            if (now - raw.at >= PRESENCE_TTL_MS)
+                continue;
+            out.push({
+                id: raw.id,
+                cwd: raw.cwd,
+                host: typeof raw.host === "string" ? raw.host : "",
+                pid: typeof raw.pid === "number" ? raw.pid : 0,
+                at: raw.at,
+                ...(typeof raw.activity === "string" && raw.activity ? { activity: raw.activity } : {}),
+            });
+        }
+        catch {
+            // Starting up, or dying. Either way there is nothing to report yet.
+        }
+    }
+    // Newest first: a caller showing the list wants the busy sessions at the top.
+    return out.sort((a, b) => b.at - a.at);
+}
+/** Write or refresh one session's presence, replacing the file atomically. */
+export function announce(options, presence) {
+    mkdirSync(options.dir, { recursive: true });
+    const target = file(options, presence.id);
+    const tmp = `${target}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(presence, null, 2));
+    // A reader can be listing while this runs; rename means it sees either the old
+    // file or the new one, never a partial write it would have to skip.
+    renameSync(tmp, target);
+}
+/** Remove a session's file, on a clean exit. */
+export function withdraw(options, id) {
+    try {
+        unlinkSync(file(options, id));
+    }
+    catch {
+        // Already gone, or never written. Nothing to undo.
+    }
+}
+/** The sessions working in one workspace, excluding this one if asked. */
+export function sessionsIn(options, cwd, exceptId, now = Date.now()) {
+    return listSessions(options, now).filter((s) => s.cwd === cwd && s.id !== exceptId);
+}