allaboard 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 duqaXxX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# allaboard
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Your Claude Code workspace in Slack.
+
+All your projects, all your sessions and all your Macs, in the one app you already keep open.
+Connect every Mac you work on and every Claude Code account you use to the same Slack, and each
+of them is one message away. Each project is a channel, each session is a thread: follow the work
+as Claude writes it, approve a command with one tap, and pick any session up again days later.
+Claude Code keeps running on each Mac, with its own files and its own setup.
+
+## Install
+
+```sh
+npm install -g allaboard
+```
+
+The [setup guide](https://github.com/duqaXxX/allaboard/blob/v0.4.0/docs/setup.md) says which
+systems this version supports, and takes you through
+[creating the Slack app](https://github.com/duqaXxX/allaboard/blob/v0.4.0/docs/setup.md#part-1-the-slack-app)
+from [`slack-app-manifest.json`](https://github.com/duqaXxX/allaboard/blob/v0.4.0/slack-app-manifest.json),
+the settings, and the service that starts allaboard at login:
+
+```sh
+allaboard service install
+```
+
+To bring another Mac or another Claude Code account into the same Slack, see
+[the guide's Part 6](https://github.com/duqaXxX/allaboard/blob/v0.4.0/docs/setup.md#part-6-a-second-instance).
+
+## Update
+
+When a new version is out, the bot's Home tab offers it with an Update button, and
+`!allaboard update` offers it in any channel. Running turns finish first, then allaboard restarts
+on the new version. From a terminal:
+
+```sh
+allaboard update
+```
+
+## More
+
+- Documentation and source: [github.com/duqaXxX/allaboard](https://github.com/duqaXxX/allaboard)
+- Security model: [SECURITY.md](https://github.com/duqaXxX/allaboard/blob/v0.4.0/SECURITY.md)
+- License: MIT

package/dist/agent/claude/backend.js

@@ -0,0 +1,124 @@
+/**
+ * The Claude back end: what the core asks of an agent, answered over the Agent SDK and over
+ * Claude Code's own records on disk. The only module a caller builds; the trust gate for a
+ * session's start is the core's (`folderTrusted` is its question to ask), not this class's.
+ */
+import { homedir } from "node:os";
+import { shellQuote } from "../../text.js";
+import { CAPABILITIES } from "./capabilities.js";
+import { chromeEnabled } from "./chrome.js";
+import { aliveSessions, byLastActivity, directorySessions, projectsDir } from "./listing.js";
+import { ClaudeSession } from "./session.js";
+import { trustedRepository, workspaceTrusted } from "./trust.js";
+import { UsageProbe } from "./usage-probe.js";
+export const NAME = "Claude Code";
+/** The shell line that forks a session in a terminal; `environment` is what precedes `claude`. */
+function terminalWith(environment) {
+    return `cd {directory} && ${environment}claude --resume {session} --fork-session`;
+}
+export const WORDS = Object.freeze({
+    author: "Claude",
+    command: "claude",
+    examples: "`!compact`, `!model opus`",
+    // `/clear` starts a new session under any of its names (aliases `/reset` and `/new`: commands
+    // reference, code.claude.com/docs/en/commands, read 2026-10-02, and the list SDK 0.2.163
+    // reports); `/login` and `/logout` act on the host's own login.
+    newSession: ["clear", "reset", "new"],
+    login: "login",
+    logout: "logout",
+    terminal: terminalWith(""),
+});
+/**
+ * `WORDS` for a back end whose sessions use the login in `configDir`: the line that continues a
+ * session in a terminal names that folder, since a terminal reads `~/.claude` without it. The
+ * folder is quoted for a shell as `{directory}` is; a brace in it is kept out of reach of the
+ * template's fields, `'"{"'` being the same word to a shell.
+ */
+function wordsFor(configDir) {
+    if (configDir === undefined)
+        return WORDS;
+    const folder = shellQuote(configDir).replaceAll("{", `'"{"'`);
+    return Object.freeze({ ...WORDS, terminal: terminalWith(`CLAUDE_CONFIG_DIR=${folder} `) });
+}
+export class ClaudeBackend {
+    name = NAME;
+    words;
+    capabilities = CAPABILITIES;
+    #query;
+    #home;
+    #variables;
+    #configDir;
+    #projects;
+    #probe;
+    constructor(options = {}) {
+        this.#query = options.query;
+        this.#home = options.home ?? homedir();
+        this.#variables = options.variables ?? {};
+        // An empty variable is no folder, as Claude Code reads it.
+        this.#configDir = options.configDir ?? (process.env.CLAUDE_CONFIG_DIR || undefined);
+        this.#projects = projectsDir(this.#configDir, this.#home);
+        this.words = wordsFor(this.#configDir);
+        const bare = options.bareStart ?? ((folder, requests) => this.startBare(folder, requests));
+        this.#probe = new UsageProbe(this.#home, bare, { clock: options.clock });
+    }
+    /**
+     * Starts Claude Code and returns once it answered. Rejects with `ResumeRefused` when it
+     * refuses to resume `options.resume`, and with the failure itself when it cannot start.
+     * Whether the owner trusted the folder is the caller's to check first (`folderTrusted`).
+     */
+    async start(options, requests) {
+        // Read at every start, so a change in `/chrome` holds from a session's next start.
+        const chrome = await chromeEnabled(this.#home, this.#configDir);
+        const session = new ClaudeSession({ ...options, chrome, variables: this.#variables }, requests, this.#query);
+        await session.ready();
+        return session;
+    }
+    /**
+     * Starts a session for the daemon's own use, the usage probe's: the folder and no setting
+     * source, without the permission to bypass and without the Chrome flag, which only a thread's
+     * session is given. Fails as `start` does.
+     */
+    async startBare(folder, requests) {
+        const session = new ClaudeSession({
+            folder,
+            resume: null,
+            settingsSources: [],
+            model: null,
+            effort: null,
+            chrome: false,
+            bare: true,
+        }, requests, this.#query);
+        await session.ready();
+        return session;
+    }
+    /** The sessions of `folder` alone, newest first by their files' times. */
+    listSessions(folder) {
+        return directorySessions(folder);
+    }
+    /**
+     * `sessions` of `folder` by their last message, newest first, as the terminal's picker shows
+     * them. Dating reads files, so a caller that shows only some of a folder's sessions passes
+     * those alone.
+     */
+    datedSessions(folder, sessions) {
+        return byLastActivity(folder, sessions, { projects: this.#projects });
+    }
+    /** The session ids alive in `folder`, or null when it cannot tell (the pruning keeps them). */
+    aliveSessions(folder) {
+        return aliveSessions(folder, this.#projects);
+    }
+    folderTrusted(folder) {
+        return workspaceTrusted(folder, this.#home, this.#configDir);
+    }
+    trustedRepository(folder) {
+        return trustedRepository(folder, this.#home, this.#configDir);
+    }
+    /** The limits `/usage` reports now, read by a session of the back end's own. */
+    usageLimits() {
+        return this.#probe.read();
+    }
+    /** Stops the usage probe: its session is closed and no read starts another. */
+    close() {
+        return this.#probe.stop();
+    }
+}

package/dist/agent/claude/capabilities.js

@@ -0,0 +1,30 @@
+export const CAPABILITIES = Object.freeze({
+    // The SDK's `EffortLevel`.
+    effortLevels: Object.freeze(["low", "medium", "high", "xhigh", "max"]),
+    // The CLI's word for the model's default, set with `/effort auto`: not an `EffortLevel`.
+    effortDefault: "auto",
+    // The TypeScript SDK changes the effort of a live session (`applyFlagSettings`, no reconnect,
+    // SDK 0.3.296): 36 ms in the spike's measurement, 28 ms in the back end's own live check, both
+    // on 2026-10-10.
+    liveEffort: true,
+    permissionModes: Object.freeze({
+        default: "default",
+        auto: "auto",
+        bypass: "bypassPermissions",
+    }),
+    subagents: true,
+    backgroundTasks: true,
+    // A notification folded into a running turn is replayed as a `user` record whose origin names
+    // the run (`SDKMessageOrigin.runId`, recorded 2026-10-15, issue #317).
+    foldedNotifications: true,
+    compaction: true,
+    // `session_state_changed`, which a session emits when asked to (`SESSION_SIGNALS`).
+    declaredState: true,
+    questions: true,
+    usageLimits: true,
+    models: true,
+    commands: true,
+    promptDuringTurn: true,
+    sessionListing: true,
+    folderTrust: true,
+});

package/dist/agent/claude/chrome.js

@@ -0,0 +1,42 @@
+/**
+ * Claude Code's Chrome integration, for the sessions the daemon starts.
+ *
+ * Claude Code turns the integration on in an interactive session when the owner chose "Enabled by
+ * default" in `/chrome`: the key `claudeInChromeDefaultEnabled` of `~/.claude.json` (settings
+ * reference, read 2026-10-09). A session the Agent SDK starts is not interactive, and there the key
+ * connects nothing: the built-in `claude-in-chrome` server is listed only when Claude Code is
+ * started with `--chrome` (measured 2026-10-09, CLI 2.1.292). The daemon passes the flag when the
+ * key is on, so a session from Slack has the browser where the terminal has it.
+ *
+ * Nothing else is the daemon's. Which sites Claude may act on is the extension's own setting, and
+ * whether an action asks first is the session's permission mode, as in the terminal: a browser
+ * call that asks reaches Slack through `canUseTool` like any other tool (measured the same day,
+ * SDK 0.2.164).
+ */
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { getLogger } from "../../log.js";
+import { errorName } from "../../values.js";
+import { recordPath } from "./record.js";
+export const logger = getLogger("allaboard.agent.claude.chrome");
+// Strict UTF-8, and a BOM stays in the text, where `JSON.parse` refuses it.
+const STRICT_UTF8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+/**
+ * Whether the owner turned Chrome on by default in Claude Code; false when its record cannot be
+ * read. The record is the config folder's when the login has one (`recordPath`). Read at every
+ * call, so a change in `/chrome` holds from a session's next start.
+ */
+export async function chromeEnabled(home = homedir(), configDir) {
+    let record;
+    try {
+        record = JSON.parse(STRICT_UTF8.decode(await readFile(recordPath(home, configDir))));
+    }
+    catch (error) {
+        logger.warning(`could not read Claude Code's Chrome setting: ${errorName(error)}`);
+        return false;
+    }
+    return (typeof record === "object" &&
+        record !== null &&
+        !Array.isArray(record) &&
+        record.claudeInChromeDefaultEnabled === true);
+}

package/dist/agent/claude/hooks.js

@@ -0,0 +1,37 @@
+/**
+ * The inputs of the three hooks the daemon registers, into session events.
+ *
+ * The Stop hook's input carries the effort level Claude Code runs at: the footer's only source
+ * for it, since no message reports it. Every hook input carries the `cwd` the session works in;
+ * PostToolUse reports it after each tool, so a turn stopped or failed before its Stop still
+ * moves the footer's branch. PostModelSwitch reports a model change before the command's result,
+ * while the context usage still names the model before it.
+ */
+import { isRecord } from "../../values.js";
+import { string, words } from "./wire.js";
+function folderChanged(input) {
+    const folder = isRecord(input) ? words(input.cwd) : null;
+    return folder === null ? [] : [{ type: "folder_changed", folder }];
+}
+/**
+ * A Stop hook's input: the effort the session runs at, then its folder. The effort is always
+ * said: `effort` is in the CLI's Stop input since Claude Code 2.1.280 and absent when the model
+ * takes no effort parameter, which reads as null.
+ */
+export function stopHookEvents(input) {
+    const effort = isRecord(input) && isRecord(input.effort) ? input.effort : {};
+    return [{ type: "effort_observed", level: string(effort.level) }, ...folderChanged(input)];
+}
+/** A PostToolUse hook's input: the folder the session works in after the tool. */
+export function postToolUseHookEvents(input) {
+    return folderChanged(input);
+}
+/**
+ * A PostModelSwitch hook's input: the model the session runs after the switch. Every `source`
+ * counts (command, picker, sdk, auto, resume): each is a change of the model the footer names,
+ * and the one the daemon's own `setModel` makes is true as well.
+ */
+export function postModelSwitchHookEvents(input) {
+    const model = isRecord(input) ? words(input.to_model) : null;
+    return model === null ? [] : [{ type: "model_changed", model }];
+}

package/dist/agent/claude/info.js

@@ -0,0 +1,61 @@
+import { isRecord, records } from "../../values.js";
+import { number, string, words } from "./wire.js";
+function strings(value) {
+    return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+}
+function modelOf(entry) {
+    // The setup keys every option on `value`: an entry without one is left out here, so a CLI
+    // that lists one cannot stop every first prompt.
+    const value = words(entry.value);
+    if (value === null)
+        return null;
+    const supportsEffort = entry.supportsEffort === true;
+    return {
+        value,
+        resolvedModel: words(entry.resolvedModel),
+        displayName: words(entry.displayName) ?? value,
+        description: words(entry.description),
+        supportsEffort,
+        supportedEffortLevels: supportsEffort ? strings(entry.supportedEffortLevels) : [],
+    };
+}
+function commandOf(entry) {
+    const name = words(entry.name);
+    if (name === null)
+        return null;
+    return {
+        name,
+        description: string(entry.description) ?? "",
+        argumentHint: string(entry.argumentHint) ?? "",
+        aliases: strings(entry.aliases),
+    };
+}
+function known(entries) {
+    return entries.filter((entry) => entry !== null);
+}
+/** The answer to the initialize request as the models, commands and mode the core reads. */
+export function agentInfo(info) {
+    const answer = isRecord(info) ? info : {};
+    return {
+        models: known(records(answer.models).map(modelOf)),
+        commands: known(records(answer.commands).map(commandOf)),
+        permissionMode: words(answer.current_permission_mode),
+    };
+}
+/** The context usage as the footer reads it: the model and the share of its window in use. */
+export function contextUsage(usage) {
+    const answer = isRecord(usage) ? usage : {};
+    return { model: string(answer.model), percentage: number(answer.percentage) };
+}
+/** A session the SDK lists, as a row of `!resume`. */
+export function listedSession(session) {
+    return {
+        id: session.sessionId,
+        title: session.summary,
+        customTitle: session.customTitle ?? null,
+        // Empty outside a repository's branch: the row then shows none.
+        branch: session.gitBranch || null,
+        size: session.fileSize ?? null,
+        lastModified: session.lastModified,
+    };
+}

package/dist/agent/claude/listing.js

@@ -0,0 +1,230 @@
+/**
+ * Claude Code's sessions of one folder: the SDK's listing, their dates as the terminal's picker
+ * shows them, and the ids that are alive.
+ *
+ * What the public SDK does not give. `SDKSessionInfo.lastModified` is the transcript file's
+ * mtime, and `getSessionMessages` returns messages without a time (`SessionMessage` has no
+ * timestamp field, SDK 0.3.296 `sdk.d.ts`); no public function names a session's transcript path
+ * or a folder's project directory either, so the folder is derived here the way the package
+ * itself derives it (read in `sdk.mjs` 0.3.296, the functions that build `<config dir>/projects/<key>`): the real path, composed to NFC on
+ * macOS; every character that is not an ASCII letter or digit turned into `-`; past 200
+ * characters, the first 200, a `-` and the base-36 form of the absolute value of the 32-bit
+ * string hash `h = 31 * h + unit`. `test/agent/claude/listing.test.ts` writes a transcript where
+ * this derivation puts it and has the SDK's own `listSessions` find it, so a change in the
+ * package fails a test.
+ */
+import { constants } from "node:fs";
+import { open, readdir, realpath, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { listSessions as sdkListSessions } from "@anthropic-ai/claude-agent-sdk";
+import { getLogger } from "../../log.js";
+import { isRecord } from "../../values.js";
+import { listedSession } from "./info.js";
+import { string } from "./wire.js";
+export const logger = getLogger("allaboard.agent.claude.listing");
+/** The rows `!resume` lists: dating stops once the rest cannot enter them. */
+export const RESUME_ROWS = 20;
+/** The end of a transcript that is read for its last message. */
+export const TAIL_BYTES = 256 * 1024;
+// Past this many characters the CLI names a project folder with a hash (see the module doc).
+export const LONG_PROJECT_KEY = 200;
+/**
+ * Where Claude Code keeps every project's transcripts: "Claude Code stores session transcripts
+ * locally in plaintext under `~/.claude/projects/`" (https://code.claude.com/docs/en/data-usage,
+ * read 2026-09-28), under `CLAUDE_CONFIG_DIR` when that is set. `configDir` is that folder: the
+ * daemon's environment's when the caller gives none, so the probe, which builds no module, reads
+ * what a terminal would.
+ */
+export function projectsDir(configDir = process.env.CLAUDE_CONFIG_DIR, home = homedir()) {
+    const config = configDir ? configDir : join(home, ".claude");
+    return join(process.platform === "darwin" ? config.normalize("NFC") : config, "projects");
+}
+/** The real path of `directory`; the path itself when it cannot be resolved. */
+async function canonical(directory) {
+    let path = directory;
+    try {
+        path = await realpath(directory);
+    }
+    catch {
+        // A folder that does not exist keeps the name it was given.
+    }
+    return process.platform === "darwin" ? path.normalize("NFC") : path;
+}
+function stringHash(text) {
+    let hash = 0;
+    for (let index = 0; index < text.length; index += 1) {
+        hash = ((hash << 5) - hash + text.charCodeAt(index)) | 0;
+    }
+    return hash;
+}
+/** The name of `directory`'s folder under the projects directory. */
+export async function projectKey(directory) {
+    const path = await canonical(directory);
+    const sanitized = path.replace(/[^a-zA-Z0-9]/g, "-");
+    if (sanitized.length <= LONG_PROJECT_KEY)
+        return sanitized;
+    return `${sanitized.slice(0, LONG_PROJECT_KEY)}-${Math.abs(stringHash(path)).toString(36)}`;
+}
+/**
+ * Whether `path` is a directory; null when its `stat` fails for a reason other than the path not
+ * being there (`ENOENT`, `ENOTDIR`), such as `EACCES`: the folder may well be there.
+ */
+async function directoryState(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch (error) {
+        const code = isRecord(error) ? error.code : undefined;
+        return code === "ENOENT" || code === "ENOTDIR" ? false : null;
+    }
+}
+async function isDirectory(path) {
+    return (await directoryState(path)) === true;
+}
+/**
+ * The folder that holds `directory`'s transcripts, or null when there is none. The hash of a long
+ * name is the CLI's to compute and may differ from ours, so the first folder with the same first
+ * 200 characters stands in for it.
+ */
+export async function projectFolder(directory, projects) {
+    const key = await projectKey(directory);
+    const exact = join(projects, key);
+    if (await isDirectory(exact))
+        return exact;
+    if (key.length <= LONG_PROJECT_KEY)
+        return null;
+    const prefix = key.slice(0, LONG_PROJECT_KEY + 1);
+    try {
+        for (const entry of await readdir(projects, { withFileTypes: true })) {
+            if (entry.isDirectory() && entry.name.startsWith(prefix))
+                return join(projects, entry.name);
+        }
+    }
+    catch {
+        // No projects directory: no folder.
+    }
+    return null;
+}
+/** The sessions of `directory` alone, newest first. */
+export async function directorySessions(directory) {
+    // The terminal's picker also starts from the current worktree (sessions reference, read
+    // 2026-09-25). The programmatic sessions stay in: the daemon's own are among them.
+    const found = await sdkListSessions({ dir: directory, includeWorktrees: false });
+    return found.map(listedSession).sort((a, b) => b.lastModified - a.lastModified);
+}
+/**
+ * The time of the last user or assistant entry in a transcript, read from its end; null when
+ * there is none or the file cannot be read.
+ *
+ * `listSessions` dates a session by its file's mtime, and Claude Code appends bookkeeping
+ * entries with no timestamp to old transcripts (artifact ledgers, seen 2026-09-25 with the
+ * bundled CLI 2.1.280): a session untouched for days then reads as minutes old. The terminal's
+ * picker shows the last activity, so this reads it. The transcript format is not documented.
+ */
+export async function lastMessageMs(path) {
+    let tail;
+    try {
+        // As `trust.ts` opens its small files: a link is not followed and a FIFO is not waited on.
+        // The flags do not exist on Windows.
+        const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+        try {
+            const found = await file.stat();
+            if (!found.isFile())
+                return null;
+            const { size } = found;
+            const start = Math.max(0, size - TAIL_BYTES);
+            const buffer = Buffer.alloc(size - start);
+            const { bytesRead } = await file.read(buffer, 0, buffer.length, start);
+            tail = buffer.subarray(0, bytesRead).toString("utf8");
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch {
+        return null;
+    }
+    for (const line of tail.split(/\r\n|\r|\n/).reverse()) {
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue; // the first line of the tail may be cut
+        }
+        if (isRecord(entry) && (entry.type === "user" || entry.type === "assistant")) {
+            const stamp = string(entry.timestamp);
+            if (stamp === null)
+                continue;
+            const time = Date.parse(stamp);
+            return Number.isNaN(time) ? null : time;
+        }
+    }
+    return null;
+}
+/**
+ * `sessions` ordered by their last message, as the terminal's picker shows them: every session
+ * that can be among the newest `rows` is dated, the rest keep their file's mtime.
+ */
+export async function byLastActivity(directory, sessions, options = {}) {
+    const { projects = projectsDir(), rows = RESUME_ROWS, readStamp = lastMessageMs } = options;
+    const folder = await projectFolder(directory, projects);
+    if (folder === null) {
+        // Also what a change in the package's naming would look like: say so.
+        logger.warning("found no transcript folder: session dates fall back to file times");
+        return [...sessions];
+    }
+    const byMtime = [...sessions].sort((a, b) => b.lastModified - a.lastModified);
+    const dated = [];
+    const newest = []; // the `rows` newest stamps dated so far, largest first
+    for (const [index, session] of byMtime.entries()) {
+        // A file's mtime bounds its last message from above: once `rows` dated sessions are at or
+        // above this mtime, no file left can enter the list, so none is read.
+        const oldest = newest[rows - 1];
+        if (oldest !== undefined && oldest >= session.lastModified) {
+            return [...newestFirst(dated), ...byMtime.slice(index)];
+        }
+        const stamp = (await readStamp(join(folder, `${session.id}.jsonl`))) || session.lastModified;
+        dated.push({ ...session, lastModified: stamp });
+        newest.push(stamp);
+        newest.sort((a, b) => b - a);
+        newest.length = Math.min(newest.length, rows);
+    }
+    return newestFirst(dated);
+}
+function newestFirst(sessions) {
+    return [...sessions].sort((a, b) => b.lastModified - a.lastModified);
+}
+/**
+ * The session ids alive in `directory`, for the state's pruning: those the listing shows,
+ * unioned with every transcript file actually there. The listing skips sidechain and
+ * metadata-only sessions (the SDK's own rules): a session real enough to be stored in a thread
+ * must never be pruned just because it has not built up a title yet. Null is "cannot tell", and
+ * the pruning then keeps the folder's threads: past `LONG_PROJECT_KEY` characters the CLI names
+ * the folder with a hash we may not reproduce, so a missing folder there proves nothing; and a
+ * folder that is there and cannot be read, or whose presence cannot be checked, cannot tell either
+ * (a listing reads an unreadable folder as an empty one, and every session would look gone).
+ */
+export async function aliveSessions(directory, projects = projectsDir()) {
+    const alive = new Set((await directorySessions(directory)).map((session) => session.id));
+    const key = await projectKey(directory);
+    const folder = join(projects, key);
+    const there = await directoryState(folder);
+    if (there === null)
+        return null;
+    if (!there)
+        return key.length > LONG_PROJECT_KEY ? null : alive;
+    let names;
+    try {
+        names = await readdir(folder);
+    }
+    catch {
+        return null;
+    }
+    for (const name of names) {
+        if (name.endsWith(".jsonl"))
+            alive.add(name.slice(0, -".jsonl".length));
+    }
+    return alive;
+}