agentbox-app 0.1.11 → 0.1.13

package/README.md

@@ -39,11 +39,17 @@ There are two ways to run it: in the browser, or as a Mac app. Both need Node 22
 npx agentbox-app
 ```
 
-It starts on your machine and opens a tab. Nothing is hosted: it listens only
-on your own computer, and the address carries a key that is new every run. Add
-`--help` to see the options.
+It starts on your machine and opens a tab. On Linux that open goes through `xdg-open`. Nothing is hosted: it listens only on `127.0.0.1`, and the address carries a key that is new every run. Add `--help` to see the options. `--no-open` prints the address and leaves the browser to you.
 
-**As a Mac app.** Build it from this repo:
+From a checkout, build the screen once, then start it the same way:
+
+```
+npm install
+npm run build
+npx agentbox-app
+```
+
+**As a desktop app.** Build it from this repo. `npm start` is the desktop command on Omarchy and on a Mac:
 
 ```
 git clone https://github.com/savannahfeder/agentbox.git
@@ -52,11 +58,11 @@ npm install
 npm start
 ```
 
-`npm start` builds the app and opens it. On first run it walks you through
-connecting Claude Code or Codex and choosing a folder to work in.
+On Linux, `npm install` puts `agentbox` on `~/.local/bin` and adds the app to the launcher. The entry is `$XDG_DATA_HOME/applications/agentbox.desktop` (`~/.local/share/applications` when that variable is unset), and it runs `agentbox`. That command starts this checkout. Open the app from the launcher.
+
+`npm start` builds the app and opens it. On first run it walks you through connecting Claude Code or Codex and choosing a folder to work in.
 
-macOS may ask to let Terminal find devices on your local network. Agentbox
-does not need that, so Don't Allow is fine.
+On macOS, the system may ask to let Terminal find devices on your local network. Agentbox does not need that, so Don't Allow is fine.
 
 ## The chat window is the bottleneck
 
@@ -130,7 +136,7 @@ asked. Code changes open right beside the row.
 Twenty agents means twenty things competing for your attention and for a limited
 number of running sessions. Agentbox keeps one order and uses it for both.
 
-- **Tag a task** Urgent, High, Medium or Low, when you file it or later from `⌘K`.
+- **Tag a task** Urgent, High, Medium or Low, when you file it or later from `⌘K` or `Ctrl+K`.
 - **Rank your projects** once by dragging them into order. A project's place
   counts for more than any single task's tag, so your most important project
   never waits behind a side one.
@@ -146,7 +152,7 @@ number of running sessions. Agentbox keeps one order and uses it for both.
 
 <p align="center">
   <img src="docs/readme/priority-palette.png" alt="The command palette showing Priority Urgent, High, Medium and Low for the selected row" width="60%"><br>
-  <sub>Any row's priority is a <code>⌘K</code> away.</sub>
+  <sub>Any row's priority is a <code>⌘K</code> or <code>Ctrl+K</code> away.</sub>
 </p>
 
 ## Built for the keyboard
@@ -164,10 +170,10 @@ number of running sessions. Agentbox keeps one order and uses it for both.
 | `L` | Later: put a task off until a time you pick |
 | `S` | Show or hide the summary, in an open task |
 | `Z` | Undo |
-| `⌘K` | Everything else |
+| `⌘K` or `Ctrl+K` | Everything else |
 
 Fifteen skins, each in light and dark, from plain slate to woodblock and riso
-prints. Press `⌘K` and type "theme".
+prints. Press `⌘K` or `Ctrl+K` and type "theme". `Ctrl+K` is the same palette on Linux, where there is no Command key.
 
 ## Runs on the plan you already have
 
@@ -191,8 +197,10 @@ nothing new to pay for.
 default works unset and they all live in `main/config.mjs`. The ones that
 matter:
 
-- `storeRoot`: where the store lives. Defaults to a folder named after the app
-  in your home directory.
+- `storeRoot`: where the store lives. On macOS this defaults to a folder
+  named after the app in your home directory. On Linux it defaults to
+  `$XDG_DATA_HOME/agentbox`, which is `~/.local/share/agentbox` when that
+  variable is unset.
 - `claudeBin`: the binary to run. The app finds `claude` itself if you leave
   this alone.
 - `maxConcurrentSessions`: how many agents run at once. The queue absorbs the
@@ -311,8 +319,8 @@ picks which coding agents the fixture Mac has, where nothing is one agent,
 or `?engines=codex` give two.
 
 To open the app as somebody who has never seen it, with its own throwaway home
-and nothing of yours inside it, press `⌘K` and choose "Open Agentbox as a new
-user". `npm run fresh` does the same from a terminal.
+and nothing of yours inside it, press `⌘K` or `Ctrl+K` and choose "Open Agentbox as a new
+user". `npm run fresh` does the same from a terminal. `ZERO_NO_SUPERVISOR=1` applies to `npm start` and to `npx agentbox-app`.
 
 The app is named in exactly one place, `shared/product-name.mjs`. Change it
 there and run `node scripts/product-name.mjs --write`, and everything else

package/bin/agentbox.mjs

@@ -12,11 +12,11 @@
 
 import path from 'node:path';
 import fs from 'node:fs';
-import os from 'node:os';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
 import { bootHeadless, createServer, newToken } from '../main/serve.mjs';
+import { appHome } from '../main/store/home.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const appDir = path.dirname(here);
@@ -43,9 +43,13 @@ if (args.includes('--help') || args.includes('-h')) {
 
 // WHERE THE STORE LIVES. A copy run out of npm has no folder of its own to
 // write into, and writing inside node_modules would be thrown away by the next
-// install. `~/.agentbox` is the plain answer and `--dir` is the escape hatch.
+// install. The default is appHome(): a dot-folder already on disk, else the
+// XDG data directory on Linux and `~/.agentbox` on macOS, where this command
+// has always kept it. Not the desktop config's default, which on macOS is
+// `~/Agentbox` and would open every existing Mac user on an empty inbox.
+// `--dir` and AGENTBOX_HOME are the escape hatches.
 const dataDir = path.resolve(
-  flag('dir', process.env.AGENTBOX_HOME ?? path.join(os.homedir(), '.agentbox')),
+  flag('dir', process.env.AGENTBOX_HOME ?? appHome()),
 );
 fs.mkdirSync(dataDir, { recursive: true });
 
@@ -56,12 +60,17 @@ if (!fs.existsSync(path.join(dist, 'index.html'))) {
 }
 
 const booted = await bootHeadless({ dataDir, appDir, userDir: dataDir });
-// Whoever was signed in to the team last time is signed in again.
-booted.team?.start().then(() => booted.supervisor.wake?.()).catch((err) => console.warn(`team: ${err.message}`));
-// AND THE AGENTS' CLOCK, as the desktop starts it (main/main.mjs). Without it a
-// tab only moved work when something woke the supervisor: a queued thread sat
-// queued and a scheduled one never fired (found 2026-10-01 on a test copy).
-booted.supervisor.start();
+// ZERO_NO_SUPERVISOR: the desktop already honors this (main/main.mjs). This
+// entry is the same inbox, so a launch that asks for no agents must not start
+// them here either.
+if (!process.env.ZERO_NO_SUPERVISOR) {
+  // Whoever was signed in to the team last time is signed in again.
+  booted.team?.start().then(() => booted.supervisor.wake?.()).catch((err) => console.warn(`team: ${err.message}`));
+  // AND THE AGENTS' CLOCK, as the desktop starts it (main/main.mjs). Without it a
+  // tab only moved work when something woke the supervisor: a queued thread sat
+  // queued and a scheduled one never fired (found 2026-10-01 on a test copy).
+  booted.supervisor.start();
+}
 const token = newToken();
 const server = createServer({
   channels: booted.channels,

package/briefs/message-rules.md

@@ -59,10 +59,21 @@ opens beside the message by itself. Not the source files you edited, which are
 no use to them.
 
 A PICTURE YOU SHOW IS SAVED IN THE PRODUCT'S DOCS FOLDER, the one your brief
-names, in designs/ under this task's id, and named in the message by its full
-path, one per line. The app draws it where you name it. Not in your code
-checkout, which is deleted once the work ships, and never in /tmp, which the
-app will not draw at all.
+names, in designs/ under this task's id, and named by its full path. Not in
+your code checkout, which is deleted once the work ships, and never in /tmp,
+which the app will not draw at all.
+
+WHAT THE APP CAN SHOW, so you can lay out what you made the way it reads best:
+- A picture's path, anywhere in the message, is drawn right there at full
+  width, and a click opens it. It is drawn as a block, so inside a sentence or
+  a bullet it splits the line.
+- A folder's path on a line of its own draws its newest six pictures as a grid.
+- An html page in designs/ opens beside the message by itself, so one page can
+  set several options side by side with notes on each.
+- A sound or a film plays where it is named; a localhost address opens beside
+  the message. Headings, lists, tables and bold all draw.
+The arrangement is yours. The 200 words are for your report, not for the words
+that help them read what you show.
 
 Steps they must take are a numbered list, five at most, the first one doable now.
 

package/main/account-tooling.mjs

@@ -198,7 +198,8 @@ function list(names) {
 const identityCache = new Map();
 
 export function accountIdentity(dir, { home = os.homedir() } = {}) {
-  const file = path.join(dir || defaultClaudeHome(home), '.claude.json');
+  let file = path.join(dir || defaultClaudeHome(home), '.claude.json');
+  if (!dir && !fs.existsSync(file)) file = path.join(home, '.claude.json');
   // Cached on the file's own mtime rather than on a timer. That file is ~120 KB
   // on this machine and the settings page re-reads on every poll, so parsing it
   // each time would be real work for an answer that changes about twice a

package/main/acp.mjs

@@ -0,0 +1,296 @@
+/**
+ * ONE TRANSPORT FOR EVERY AGENT THAT SPEAKS THE AGENT CLIENT PROTOCOL.
+ *
+ * Grok (`grok agent stdio`), pi, Gemini CLI and Hermes (`hermes acp`) all speak
+ * it, so this file is what a user of ours asked for when they wrote
+ * github.com/savannahfeder/agentbox/issues/21: one engine instead of one
+ * adapter per tool. ACP is JSON-RPC 2.0 over stdio, one object per line, and
+ * the reason it is worth a file of its own is that permission requests are IN
+ * the protocol — an approval card can carry a real approval rather than one
+ * inferred from the bottom of a terminal.
+ *
+ * WHAT THIS FILE IS AND IS NOT. It is the wire: framing, negotiation, the
+ * session calls, and the two directions of request. It holds no opinion about
+ * which tool is on the other end, no card drawing, and no admission policy. A
+ * tool is not offered to anyone because this file works; see docs/harnesses.md.
+ *
+ * THE RULES IT EXISTS TO KEEP, every one of them a lesson
+ * main/codex-app-server.mjs paid for first:
+ *
+ * - A PERMISSION REQUEST IS ALWAYS ANSWERED. The agent is blocked on us while
+ *   it waits, so a dropped answer is not a missing card, it is a task parked
+ *   forever with nothing on the row. If the asker throws, or never comes back
+ *   inside the deadline, the answer is a refusal rather than silence.
+ * - A REFUSAL IS SPOKEN IN THE AGENT'S OWN WORDS. Option ids belong to the
+ *   tool, so "deny" means finding the option whose KIND rejects. If it offered
+ *   none, the answer is `cancelled`: we never invent an id, and we never
+ *   silently pick `allow_always` for someone who pressed Allow once.
+ * - A CANCELLED TURN ANSWERS `cancelled`, which the protocol requires, so a
+ *   card nobody pressed cannot land as an approval after the fact. And a
+ *   request is answered ONCE.
+ * - A DOOR WE NEVER OPENED IS REFUSED OUT LOUD. We advertise no filesystem and
+ *   no terminal, so `fs/*` and `terminal/*` get a method-not-found error.
+ *   Going quiet on a JSON-RPC request is the same hang in the other direction.
+ * - READING NEVER STOPS WHILE A QUESTION WAITS, because the agent may still be
+ *   streaming, and because its other sessions must not be held up by this one.
+ */
+import { StringDecoder } from 'node:string_decoder';
+
+// The version this client negotiates. ACP numbers its protocol, and an agent
+// that answers with another one has told us something we must not paper over.
+export const ACP_PROTOCOL_VERSION = 1;
+
+// What we lend the agent. Nothing: it has its own filesystem and its own
+// terminal, and anything advertised here is a door we then have to police.
+export const CLIENT_CAPABILITIES = Object.freeze({
+  fs: Object.freeze({ readTextFile: false, writeTextFile: false }),
+  terminal: false,
+});
+
+// The four kinds the protocol defines for a permission option. The ids beside
+// them are the tool's own; only the kind is portable.
+export const PERMISSION_KINDS = Object.freeze(['allow_once', 'allow_always', 'reject_once', 'reject_always']);
+const REJECTIONS = Object.freeze(['reject_once', 'reject_always']);
+
+// How long a question may stand before it is refused on the person's behalf.
+// Matches the Codex spool, because it is the same person and the same patience.
+export const PERMISSION_TIMEOUT_MS = 15 * 60_000;
+export const REQUEST_TIMEOUT_MS = 2 * 60_000;
+// A line that never ends is not a message, it is a leak.
+export const MAX_FRAME_LENGTH = 16 * 1024 * 1024;
+
+/**
+ * THE OPTION THAT MEANS NO, out of the ones this agent actually offered.
+ *
+ * `reject_once` before `reject_always`, because refusing one operation is the
+ * smaller claim and the only one a single card can honestly make: remembering
+ * a refusal forever is a different decision that nobody pressed. Null when the
+ * agent offered no refusal at all, which is answered by cancelling the turn.
+ */
+export function rejectionOption(options = []) {
+  for (const kind of REJECTIONS) {
+    const found = options.find(option => option?.kind === kind);
+    if (found?.optionId) return found.optionId;
+  }
+  return null;
+}
+
+/** Whether an id the asker chose is one the agent really put on the table. */
+export function offeredOption(options = [], optionId) {
+  return options.some(option => option?.optionId === optionId) ? optionId : null;
+}
+
+export function createAcpClient({
+  transport = null,
+  spawn = null,
+  clientInfo = { name: 'agentbox', version: '1.0.0' },
+  onNotification = null,
+  onPermission = null,
+  permissionTimeoutMs = PERMISSION_TIMEOUT_MS,
+  requestTimeoutMs = REQUEST_TIMEOUT_MS,
+  maxFrameLength = MAX_FRAME_LENGTH,
+  stderrLimit = 64 * 1024,
+} = {}) {
+  const child = transport ?? spawn?.();
+  if (!child) throw Error('createAcpClient needs a transport or a spawn that makes one');
+
+  const pending = new Map();      // our request id -> { resolve, reject, timer, method }
+  const permissions = new Map();  // their request id -> { sessionId, options, answer }
+  const decoder = new StringDecoder('utf8');
+  let nextId = 1;
+  let buffer = '';
+  let stderrText = '';
+  let gone = null;                // null while live; the reason once not
+  let negotiated = null;          // what initialize came back with
+
+  /* ------------------------------- writing -------------------------------- */
+
+  function write(message) {
+    if (gone) return false;
+    const line = `${JSON.stringify(message)}\n`;
+    try {
+      // A write that is accepted and then fails reports it in the callback,
+      // and that is the one that matters: a refusal that was "written" and
+      // never arrived cannot be told apart from an approval.
+      child.stdin.write(line, error => { if (error) close(`Write failed: ${error.message}`); });
+    } catch (error) {
+      close(`Write failed: ${error.message}`);
+      return false;
+    }
+    return true;
+  }
+
+  function request(method, params) {
+    if (gone) return Promise.reject(Error(gone));
+    const id = nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        reject(Error(`${method} did not answer within ${requestTimeoutMs}ms`));
+      }, requestTimeoutMs);
+      timer.unref?.();
+      pending.set(id, { resolve, reject, timer, method });
+      if (!write({ jsonrpc: '2.0', id, method, params })) {
+        clearTimeout(timer);
+        pending.delete(id);
+        reject(Error(gone ?? 'The agent connection is gone'));
+      }
+    });
+  }
+
+  const notify = (method, params) => write({ jsonrpc: '2.0', method, params });
+
+  /* ------------------------------ permissions ------------------------------ */
+
+  /**
+   * Answer one permission request, once.
+   *
+   * `optionId` when the person chose one of the offered options; null for
+   * `cancelled`, which is what a cancelled turn and an agent that offered no
+   * refusal both come to. The entry is dropped before the write, so a late
+   * answer from a card, a deadline and a cancellation racing each other still
+   * only ever put one response on the wire.
+   */
+  function settlePermission(id, optionId) {
+    const entry = permissions.get(id);
+    if (!entry) return false;
+    permissions.delete(id);
+    clearTimeout(entry.timer);
+    const outcome = optionId ? { outcome: 'selected', optionId } : { outcome: 'cancelled' };
+    write({ jsonrpc: '2.0', id, result: { outcome } });
+    return true;
+  }
+
+  function askPermission(id, params) {
+    const options = Array.isArray(params?.options) ? params.options : [];
+    const deny = () => settlePermission(id, rejectionOption(options));
+    const timer = setTimeout(deny, permissionTimeoutMs);
+    timer.unref?.();
+    permissions.set(id, { sessionId: params?.sessionId ?? null, options, timer });
+    if (!onPermission) return deny();
+    // The asker may answer whenever: the reading loop is not waiting on it.
+    (async () => onPermission({ requestId: id, ...params }))()
+      .then(chosen => settlePermission(id, offeredOption(options, chosen)))
+      .catch(() => deny());
+    return true;
+  }
+
+  /* ------------------------------- reading -------------------------------- */
+
+  function handle(message) {
+    if (message.id != null && (message.result !== undefined || message.error !== undefined)) {
+      const waiting = pending.get(message.id);
+      if (!waiting) return;                       // a response to something we gave up on
+      pending.delete(message.id);
+      clearTimeout(waiting.timer);
+      if (message.error) waiting.reject(Error(`${waiting.method}: ${message.error.message ?? 'failed'}`));
+      else waiting.resolve(message.result);
+      return;
+    }
+    if (message.id != null && message.method) {
+      if (message.method === 'session/request_permission') return void askPermission(message.id, message.params);
+      // Everything else is a capability we did not advertise. Say so.
+      write({ jsonrpc: '2.0', id: message.id, error: { code: -32601, message: `${message.method} is not supported by this client` } });
+      return;
+    }
+    if (message.method) onNotification?.(message.method, message.params ?? {});
+  }
+
+  function absorb(chunk) {
+    if (gone) return;
+    buffer += decoder.write(chunk);
+    let index;
+    while ((index = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, index).trim();
+      buffer = buffer.slice(index + 1);
+      if (!line) continue;
+      let message = null;
+      try { message = JSON.parse(line); } catch { continue; } // a line we cannot read is not a reason to die
+      if (message && typeof message === 'object') handle(message);
+    }
+    if (buffer.length > maxFrameLength) close(`A frame longer than ${maxFrameLength} bytes was too long to be a message`);
+  }
+
+  function close(reason) {
+    if (gone) return gone;
+    gone = reason;
+    // Every question still standing goes with the connection: an answer whose
+    // asker has quit is worth nothing, and the agent is already gone.
+    for (const id of [...permissions.keys()]) {
+      const entry = permissions.get(id);
+      permissions.delete(id);
+      clearTimeout(entry.timer);
+    }
+    for (const [id, waiting] of [...pending]) {
+      pending.delete(id);
+      clearTimeout(waiting.timer);
+      waiting.reject(Error(reason));
+    }
+    try { child.stdin.end(); } catch {}
+    try { child.kill?.(); } catch {}
+    return gone;
+  }
+
+  child.stdout?.on('data', absorb);
+  child.stdout?.on('end', () => close(gone ?? 'The agent closed its output'));
+  child.stderr?.on('data', chunk => {
+    if (stderrText.length < stderrLimit) stderrText += chunk.toString().slice(0, stderrLimit - stderrText.length);
+  });
+  child.on?.('error', error => close(`The agent could not be run: ${error.message}`));
+  child.on?.('exit', code => close(gone ?? `The agent exited with code ${code}`));
+
+  /* -------------------------------- the API -------------------------------- */
+
+  return {
+    async initialize() {
+      negotiated = await request('initialize', {
+        protocolVersion: ACP_PROTOCOL_VERSION,
+        clientCapabilities: { fs: { ...CLIENT_CAPABILITIES.fs }, terminal: CLIENT_CAPABILITIES.terminal },
+        clientInfo,
+      });
+      return negotiated;
+    },
+    /**
+     * WHAT THE AGENT SAID IT CAN DO, and nothing we assumed. Speaking ACP does
+     * not make a tool resumable: `loadSession` is optional in the protocol, so
+     * a tool that cannot do it must be read as cannot rather than as untested.
+     */
+    can(capability) {
+      const agent = negotiated?.agentCapabilities ?? {};
+      if (capability === 'image' || capability === 'audio' || capability === 'embeddedContext') {
+        return agent.promptCapabilities?.[capability] === true;
+      }
+      return agent[capability] === true;
+    },
+    authMethods: () => negotiated?.authMethods ?? [],
+    authenticate: methodId => request('authenticate', { methodId }),
+    newSession: ({ cwd, mcpServers = [], additionalDirectories }) =>
+      request('session/new', { cwd, mcpServers, ...(additionalDirectories ? { additionalDirectories } : {}) }),
+    loadSession({ sessionId, cwd, mcpServers = [] }) {
+      // Refused before anything reaches the wire, so a thread cannot be
+      // silently restarted as an empty conversation on a tool that cannot
+      // resume. The caller's job is then to say so on the row.
+      if (!this.can('loadSession')) return Promise.reject(Error('This agent cannot resume a session, so there is no thread to load'));
+      return request('session/load', { sessionId, cwd, mcpServers });
+    },
+    prompt: ({ sessionId, text, blocks = null }) =>
+      request('session/prompt', { sessionId, prompt: blocks ?? [{ type: 'text', text }] }),
+    /**
+     * Stop the turn, and answer what it was parked on. The protocol says a
+     * cancelled turn MUST be answered `cancelled`, and this is the only place
+     * that is true of, so it happens here rather than at a call site.
+     */
+    cancel(sessionId) {
+      for (const [id, entry] of [...permissions]) {
+        if (!sessionId || entry.sessionId === sessionId) settlePermission(id, null);
+      }
+      return notify('session/cancel', { sessionId });
+    },
+    /** An answer from a card. False when the question is no longer standing. */
+    answerPermission: (requestId, optionId) => settlePermission(requestId, optionId),
+    openPermissions: () => permissions.size,
+    closed: () => gone,
+    close,
+    diagnostics: () => stderrText,
+  };
+}

package/main/agent-homes.mjs

@@ -0,0 +1,158 @@
+// EVERY FOLDER CLAUDE CODE AND CODEX KEEP SESSIONS IN, so the import reads all
+// of them rather than the one each tool uses by default (w-e46f2e9cea).
+//
+// Claude Code writes a session to `$CLAUDE_CONFIG_DIR/projects`, and to
+// `~/.claude/projects` only when that variable is unset (read out of the 2.1.293
+// binary, 2026-10-11). Codex does the same with `CODEX_HOME` and `~/.codex`.
+// The import read only the two defaults, and on the Mac this was measured on
+// every Claude Code session its owner had run lived in `~/.claude-2`. The walk's
+// last card is drawn only when the finder hands something back, so a finder
+// looking in the wrong folder does not draw an empty card. It draws no card,
+// and the person is never told importing exists.
+//
+// READING THE VARIABLE IS NOT ENOUGH. An app opened from the Dock never sees
+// what a shell profile exports, so somebody with `export CLAUDE_CONFIG_DIR=...`
+// in their .zshrc gets an app whose environment has no such variable. The
+// folders are looked for instead, by the same rule main/account-discovery.mjs
+// uses to find a second login: `.claude` or `.claude-<anything>` directly under
+// home. That module asks whether a folder holds a LOGIN; this one asks whether
+// it holds SESSIONS, which is a different question with a different answer. A
+// backup folder holds no login and may hold the only copy of a conversation,
+// and two folders signed in as one account are one account but two sets of
+// sessions.
+//
+// A FOLDER COUNTS ONLY IF IT HAS SESSIONS IN IT: `projects/` for Claude Code,
+// `sessions/` for Codex. `~/.claude-worktrees` is named like a data folder and
+// is not one. A folder named `claude-src`, with no dot, is somebody's checkout
+// and is never looked at.
+//
+// Duplicates are the reader's to settle, by session id: a backup folder with a
+// copy of a conversation is ordinary, and the newest copy is the one to offer.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { shellDataDirsNow } from './shell-path.mjs';
+
+const isDir = (p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
+
+/** `.claude`, `.claude-work`, `.codex-2`: every directory under home named `.<tool>` or `.<tool>-<anything>`. */
+function shapedUnderHome(home, tool) {
+  let names = [];
+  try { names = fs.readdirSync(home); } catch { return []; }
+  return names
+    .filter((n) => n === `.${tool}` || n.startsWith(`.${tool}-`))
+    .sort()
+    .map((n) => path.join(home, n));
+}
+
+/**
+ * The candidates, in the order given, kept when they hold `inner/` and named
+ *  once each. Two spellings of one folder (a trailing slash, a symlink) are
+ *  one folder. */
+function keepWithSessions(candidates, inner) {
+  const out = [];
+  const seen = new Set();
+  for (const c of candidates) {
+    if (typeof c !== 'string' || !c.trim()) continue;
+    const dir = path.resolve(c.trim());
+    let real = dir;
+    try { real = fs.realpathSync(dir); } catch { continue; }
+    if (seen.has(real)) continue;
+    if (!isDir(path.join(dir, inner))) continue;
+    seen.add(real);
+    out.push(dir);
+  }
+  return out;
+}
+
+/** A configured profile is 'default' (the tool's own default folder) or a folder. */
+const profileDirs = (configured, dflt) => (Array.isArray(configured) ? configured : [configured])
+  .filter((p) => typeof p === 'string' && p.trim())
+  .map((p) => (p === 'default' ? dflt : p));
+
+/**
+ * EVERY CLAUDE CODE DATA FOLDER ON THIS MACHINE THAT HOLDS SESSIONS.
+ *
+ *  `env` is the app's own environment and is passed in rather than read here,
+ *  so a test with a made-up home is not handed the real folder the test runner
+ *  happens to have in CLAUDE_CONFIG_DIR. `configured` is `authProfiles`. The
+ *  last candidate is `~/.config/claude`, where some Claude Code versions kept
+ *  their data; 2.1.293 no longer does, but a machine that still has sessions
+ *  there gets them read. */
+export function claudeDataDirs({ home = os.homedir(), env = {}, configured = [] } = {}) {
+  const dflt = path.join(home, '.claude');
+  const xdg = env?.XDG_CONFIG_HOME ? path.join(env.XDG_CONFIG_HOME, 'claude') : path.join(home, '.config', 'claude');
+  return keepWithSessions([
+    env?.CLAUDE_CONFIG_DIR,
+    ...profileDirs(configured, dflt),
+    dflt,
+    ...shapedUnderHome(home, 'claude'),
+    xdg,
+  ], 'projects');
+}
+
+/**
+ * BOTH LISTS, AS THE RUNNING APP SEES THEM: its own environment, the Claude
+ *  profiles it was configured with, and the Codex homes its supervisor runs on.
+ *  The one call the import card, the Codex watch and the import answer share,
+ *  so the three cannot disagree about where somebody's sessions are. */
+export function sessionFolders({ claudeProfiles = [], codexHomes = [], env = process.env, home = os.homedir() } = {}) {
+  return {
+    dirs: claudeDataDirs({ home, env, configured: claudeProfiles }),
+    codexDirs: codexDataDirs({ home, env, configured: codexHomes }),
+  };
+}
+
+/**
+ * THE CODEX HOMES THE SUPERVISOR RUNS ON, or as many of them as can be named.
+ *  Each profile is resolved on its own, so one that throws costs that one home
+ *  and not the list (found by Codex's review of this change, 2026-10-11). */
+export function codexHomesOf(supervisor) {
+  let profiles = [];
+  try { profiles = supervisor?._codexProfiles?.() ?? []; } catch { profiles = []; }
+  if (!Array.isArray(profiles)) return [];
+  const out = [];
+  for (const p of profiles) {
+    try {
+      const h = supervisor._codexProfileHome(p);
+      if (typeof h === 'string' && h.trim()) out.push(h);
+    } catch { /* that one home is unknown; the rest still count */ }
+  }
+  return out;
+}
+
+/**
+ * WHAT THE RUNNING APP HANDS EVERY READER: its own config and supervisor, made
+ *  safe. A missing config, a supervisor without the Codex methods, or a home
+ *  that will not resolve each lose only their own part. The first draft built
+ *  both lists inside one try, so any one of those left the import reading
+ *  nothing beyond the defaults, and without the app's own CLAUDE_CONFIG_DIR or
+ *  CODEX_HOME either. */
+export function appSessionFolders({ config = null, supervisor = null, env = process.env, shellEnv = shellDataDirsNow(), home = os.homedir() } = {}) {
+  let claudeProfiles = [];
+  try { claudeProfiles = config?.authProfiles ?? []; } catch { claudeProfiles = []; }
+  if (!Array.isArray(claudeProfiles)) claudeProfiles = [claudeProfiles];
+  // AND WHAT THE LOGIN SHELL EXPORTS (main/shell-path.mjs), which an app opened
+  // from the Dock never sees in its own environment.
+  return sessionFolders({
+    claudeProfiles: [...claudeProfiles, shellEnv?.CLAUDE_CONFIG_DIR],
+    codexHomes: [...codexHomesOf(supervisor), shellEnv?.CODEX_HOME],
+    env,
+    home,
+  });
+}
+
+/**
+ * EVERY CODEX DATA FOLDER ON THIS MACHINE THAT HOLDS SESSIONS. Same rule:
+ *  `CODEX_HOME`, whatever the app was configured with, `~/.codex` and every
+ *  `~/.codex-<name>`. */
+export function codexDataDirs({ home = os.homedir(), env = {}, configured = [] } = {}) {
+  const dflt = path.join(home, '.codex');
+  return keepWithSessions([
+    env?.CODEX_HOME,
+    ...profileDirs(configured, dflt),
+    dflt,
+    ...shapedUnderHome(home, 'codex'),
+  ], 'sessions');
+}