allaboard 0.5.0 → 0.6.0

package/dist/core/sessions/title.js

@@ -0,0 +1,98 @@
+/**
+ * The session's title on its thread's root: at the end of each turn the agent is asked for the
+ * title it shows for the session (generated, or set by the owner), and the chat makes the root
+ * show it. The root's own words are kept in `state.json` first (`rootPrompt`), for `!status`. Both
+ * sides are optional capabilities; without either nothing happens.
+ */
+import { ChatError } from "../../chat/seam.js";
+import { getLogger } from "../../log.js";
+import { errorName } from "../../values.js";
+export const logger = getLogger("allaboard.core.sessions.title");
+export class ThreadTitle {
+    #deps;
+    #channel;
+    #thread;
+    #directory;
+    // True once the daemon is stopping: a title resolving after that touches neither the chat nor
+    // the state.
+    #stopped;
+    // The last title the chat was given, in memory only: after a restart the first turn asks the
+    // chat again, which skips an edit that would change nothing.
+    #shown = null;
+    // Reads of one thread run one after another, so a slow one cannot land after a newer one.
+    #tail = Promise.resolve();
+    constructor(deps, channel, thread, directory, stopped = () => false) {
+        this.#stopped = stopped;
+        this.#deps = deps;
+        this.#channel = channel;
+        this.#thread = thread;
+        this.#directory = directory;
+    }
+    /**
+     * Shows the session's current title on the root, once the earlier call is done. The promise
+     * never rejects; a turn does not await it, so a title neither delays a turn nor fails it.
+     */
+    refresh() {
+        // Caught here as well as in `#show`: a rejected link would skip every later refresh.
+        this.#tail = this.#tail
+            .then(() => this.#show())
+            .catch((error) => {
+            logger.warning(`could not show the session's title of ${this.#channel}/${this.#thread}: ${errorName(error)}`);
+        });
+        return this.#tail;
+    }
+    /**
+     * The agent's title for the session `session`, or null when it has none or the agent offers
+     * none (`sessionTitles`). Rejects when the agent cannot read it.
+     */
+    async read(session) {
+        const { agent } = this.#deps;
+        if (!agent.capabilities.sessionTitles || agent.sessionTitle === undefined)
+            return null;
+        return agent.sessionTitle(this.#directory, session);
+    }
+    async #show() {
+        const { chat, state } = this.#deps;
+        // The agent's side is `read`'s: it answers null for an agent with no titles.
+        if (!chat.capabilities.threadTitles || chat.titleThread === undefined)
+            return;
+        if (this.#stopped())
+            return;
+        let title = null;
+        let stored = false;
+        try {
+            const id = state.thread(this.#channel, this.#thread)?.sessionId;
+            if (id === null || id === undefined)
+                return;
+            title = await this.read(id);
+            if (title === null || title === this.#shown || this.#stopped())
+                return;
+            const ref = { channel: this.#channel, thread: this.#thread };
+            // What the root says is kept before the chat replaces it, so that no crash between the two
+            // steps loses it: the chat reads the root once and runs `keep` before its edit. A stored
+            // prompt, even an empty one, means the root was replaced already: it is never overwritten,
+            // and a title is never kept as the prompt.
+            // `keep` runs inside the chat's serialized task and stores only if nothing is stored by
+            // then (`setRootPrompt` never replaces): a second session object for the thread, reading
+            // the root after the first replaced it, keeps nothing.
+            const keep = state.thread(this.#channel, this.#thread)?.rootPrompt === null
+                ? (text) => {
+                    stored = state.setRootPrompt(this.#channel, this.#thread, text);
+                }
+                : undefined;
+            await chat.titleThread(ref, title, keep);
+            this.#shown = title;
+        }
+        catch (error) {
+            // A refusal that cannot change is not asked again until the title does. If the words were
+            // kept for this edit and the edit is refused for good, the root still holds them.
+            if (error instanceof ChatError && error.permanent) {
+                this.#shown = title;
+                if (stored)
+                    state.clearRootPrompt(this.#channel, this.#thread);
+            }
+            // The name only: a title is the owner's content.
+            logger.warning(`could not show the session's title of ${this.#channel}/${this.#thread}: ${errorName(error)}`);
+        }
+    }
+}

package/dist/core/state.js

@@ -32,6 +32,7 @@ export function threadState(directory, fields = {}) {
         requestKinds: {},
         status: null,
         ended: null,
+        rootPrompt: null,
         ...fields,
     };
 }
@@ -163,6 +164,7 @@ export function parseThread(raw) {
         requestKinds: requestKinds(raw.request_kinds, requests),
         status: statusOrNull(raw.status),
         ended: statusOrNull(raw.ended),
+        rootPrompt: stringOrNull(raw.root_prompt),
     };
 }
 function parseChannels(raw) {
@@ -360,6 +362,28 @@ export class StateStore {
             this.setThread(channelId, threadId, { ...current, bypass: on });
         }
     }
+    /**
+     * Record the text the thread's root had before it was titled. Never replaces one already
+     * stored, empty or not: that text is what the root held before the daemon replaced it, and
+     * a later one would be the title. Returns whether it stored; a no-op, false, for an unknown thread.
+     */
+    setRootPrompt(channelId, threadId, prompt) {
+        const current = this.thread(channelId, threadId);
+        if (current === null || current.rootPrompt !== null)
+            return false;
+        this.setThread(channelId, threadId, { ...current, rootPrompt: prompt });
+        return true;
+    }
+    /**
+     * Forget the stored root text, for a root that kept its words after all (the daemon's edit was
+     * refused for good); a no-op for an unknown thread or none stored.
+     */
+    clearRootPrompt(channelId, threadId) {
+        const current = this.thread(channelId, threadId);
+        if (current !== null && current.rootPrompt !== null) {
+            this.setThread(channelId, threadId, { ...current, rootPrompt: null });
+        }
+    }
     /** Record the effort level a command set for a thread; a no-op for an unknown thread. */
     setEffort(channelId, threadId, effort) {
         const current = this.thread(channelId, threadId);
@@ -681,6 +705,7 @@ export class StateStore {
                             request_kinds: { ...t.requestKinds },
                             status: t.status,
                             ended: t.ended,
+                            root_prompt: t.rootPrompt,
                         },
                     ])),
                 },

package/dist/core/texts.js

@@ -68,6 +68,10 @@ export const AUTH_FAILED_NO_LOGIN = naming("{agent} is not logged in on the host
     "The login is never done from {chat}.");
 export const LOGIN_ON_HOST = naming("Log in on the host: on that machine, run `{cli}`, then `/{login}`. " +
     "The login is never done from {chat}.");
+// `!name` for a command of the agent's terminal that a session from the chat does not offer
+// (`AgentWords.notOffered`): answered by the daemon, so that no turn of the agent's is spent on it.
+export const NOT_OFFERED = naming("`!{command}` is a command of {agent} that a session started from {chat} does not offer.");
+export const NOT_OFFERED_SEE = "What differs from the terminal: {link}";
 export const LOGOUT_ON_HOST = naming("Log out on the host: on that machine, run `{cli}`, then `/{logout}`. " +
     "It is never done from {chat}.");
 export const DIRECTORY_MISSING = "The directory `{directory}` no longer exists. Restore it to keep using this thread, or, in " +
@@ -87,6 +91,19 @@ export const NOT_A_SESSION = "This thread holds no session. In the channel, send
 export const OPEN_TOP_LEVEL = "Opening a file belongs to one session: send `!open` inside its thread.";
 // Shown only by a chat that cannot share a file into a thread.
 export const OPEN_UNAVAILABLE = naming("{chat} cannot show a file here, so `!open` does nothing.");
+export const TAG_TOP_LEVEL = "A tag belongs to one session: send `!tag <name>` or `!untag` inside its thread.";
+// Shown only by a chat that cannot tag a thread.
+export const TAG_UNAVAILABLE = naming("{chat} cannot tag a thread here, so `!tag` and `!untag` do nothing.");
+// The chat refused the tag: nothing changed, and the agent's tag was not asked for.
+export const TAG_FAILED = naming("{chat} refused the tag: `{error}`. The thread may show part of the change; `!untag` takes it away.");
+// After the chat took the word: the agent's own tag is a second step that can fail alone.
+export const TAG_AGENT_FAILED = naming("{chat} shows the change, but {agent}'s own tag for this session did not change.");
+export const DELETE_THREAD_TOP_LEVEL = "Deleting a thread belongs to one session: send `!delete-thread` inside its thread.";
+// Shown only by a chat that cannot delete a thread.
+export const DELETE_THREAD_UNAVAILABLE = naming("{chat} cannot delete a thread here, so `!delete-thread` does nothing.");
+// The same rule as the chat's index: a thread that works or waits is never deleted.
+export const DELETE_THREAD_BUSY = "Not deleted: this thread is working or waiting for you. Send `!stop` first, then " +
+    "`!delete-thread` again.";
 export const WORD_IN_THREAD = "`!{word}` works in the channel, not inside a thread.";
 // `!stop` typed in a thread that holds no session: it would have stopped the whole channel.
 export const STOP_OUTSIDE_SESSION = "This thread holds no session. Send `!stop` in the channel to stop every session, or inside " +
@@ -229,8 +246,11 @@ export const BIND_UNAVAILABLE = "Bound this channel to `{directory}`, but no ses
 // Shown, ephemeral, before every prompt in a thread whose folder differs from the channel's.
 export const OLD_THREAD_FOLDER = naming("This session works in `{old}`, the folder it was created in: {agent} resumes a session " +
     "only there. New messages in the channel use `{new}`.");
-export const BIND_OUTSIDE = "`{path}` is not a folder under `{root}`. Give its path relative to that folder, for " +
-    "example `!bind my-project`.";
+export const BIND_MISSING = "`{path}` does not exist. Give the path of an existing folder under `{root}`, for example " +
+    "`!bind my-project`.";
+export const BIND_FILE = "`{path}` is a file, not a folder.";
+export const BIND_OUTSIDE = "`{path}` is outside `{root}`, the folder `!bind` binds under. Give its path relative to " +
+    "that folder, for example `!bind my-project`.";
 export const SESSION_CLOSED = "Nothing was done: this session closed while it ran (idle for a while, or the daemon " +
     "restarted). Send it again if it is still meant.";
 export const BIND_LIST = naming("Folders under `{root}` that {agent} trusts:");
@@ -280,6 +300,10 @@ export const SETUP_EFFORT_DEFAULT = "Default";
 /** The effort the footer shows for a model a turn reported takes none. */
 export const EFFORT_NOT_SUPPORTED = "not supported";
 export const STATUS = "Directory: `{directory}`\nSession: `{session}`";
+// The session's title, when the agent has one, and the root as the owner wrote it before the daemon
+// titled it (`rootPrompt`). `quote` is that text, each line marked as quoted.
+export const STATUS_TITLE = "Title: {title}";
+export const STATUS_PROMPT = "Prompt:\n{quote}";
 export const STATUS_STATE = naming("Mode: `{mode}`\n{agent}: `{version}`\nNow: {activity}");
 // The line between the two once the thread has a session id (issue #12). Claude Code leaves a
 // session created through the Agent SDK out of the terminal's picker; a fork made in the
@@ -289,6 +313,14 @@ export const STATUS_STATE = naming("Mode: `{mode}`\n{agent}: `{version}`\nNow: {
 // whose picker lists it. `directory` arrives quoted for the shell, and `command` as a code
 // span, or escaped as plain text when it holds a backtick.
 export const STATUS_TERMINAL = "Terminal: {command}";
+// The repositories below a session's folder that the agent's record of trust does not cover
+// (issue #247): the daemon's own git runs in none of them, and only the agent gives that trust,
+// in a terminal. Said after `!bind` and in a thread's `!status`; one line per repository below.
+export const UNTRUSTED_REPOSITORIES = naming("{agent} has not trusted these repositories yet, so the footer and `!open` show no git " +
+    "changes in them. Before you trust one, read its settings and hooks for {agent}: they run " +
+    "without asking once it is trusted. To trust it, run its line in the terminal and accept " +
+    "the trust dialog:");
+export const UNTRUSTED_MORE = "…and {count} more.";
 export const ACTIVITY_IDLE = "idle";
 export const VERSION_PENDING = "started, version shown after the first turn";
 export const STATUS_BACKGROUND = "Background: `{counts}`";
@@ -314,8 +346,12 @@ export const ACTIVITY_BUSY = "running a turn, {queued} queued";
 // `!status` sent to the channel (top-level, or a thread that holds no session): the channel's
 // folder, then one line per live session, each with a link to its thread.
 export const STATUS_CHANNEL_HEADER = "Directory: `{directory}`";
-export const STATUS_CHANNEL_EMPTY = "No live session in this channel.";
+export const STATUS_CHANNEL_EMPTY = "No session in this channel.";
+// The threads past `STATUS_ROWS`, the oldest by their last message.
+export const STATUS_CHANNEL_MORE = "+{count} older, not listed";
 export const STATUS_CHANNEL_ROW = "{link}: {activity}";
+// With a chat that marks a root with its status: the same mark leads the row, in place of the word.
+export const STATUS_CHANNEL_MARKED_ROW = "{mark} {link}{since}";
 export const STATUS_CHANNEL_WAITING = "waiting for you";
 export const STATUS_CHANNEL_BUSY = "busy";
 export const STATUS_CHANNEL_IDLE = "idle";
@@ -345,6 +381,14 @@ export const HELP_WORDS = [
     "`!open [file]` share a file of the session's folder into the thread, where {chat} opens it in " +
         "its file viewer: a picker alone, or a path or part of a name; inside a thread, refused in " +
         "the channel",
+    "`!tag <name>` mark this session's thread with a tag, 1 to 40 letters, digits, `.`, `_` or " +
+        "`-`: {chat} shows it on the thread's first message and keeps the thread at hand, and " +
+        "{agent} gets it on the session; inside a thread, refused in the channel",
+    "`!untag` take the tag and the mark away, with or without the tag's name after it; inside a " +
+        "thread, refused in the channel",
+    "`!delete-thread` delete every message of this session's thread from {chat}, once you confirm; " +
+        "the session stays in {agent} and `!resume` lists it again; refused while the thread works " +
+        "or waits for you; inside a thread, refused in the channel",
     "`!allaboard [update|restart]` the version that runs and the latest one; `update` offers the " +
         "latest and installs it on your click, `restart` restarts allaboard, both once running turns " +
         "finish; `update` and `restart` in the channel, refused inside a thread",
@@ -442,6 +486,17 @@ export const GUIDE_BYPASS = naming("**Bypass**\n" +
     "`!bypass on`, sent inside a session's thread, lets {agent} run every tool without asking in " +
     "that session, until `!bypass off`; a restart of allaboard keeps it. The footer shows ⚡ " +
     "bypass while it is on.");
+export const GUIDE_TAGS = naming("**Tags**\n" +
+    "`!tag <name>`, sent inside a session's thread, marks it: {chat} shows `[name]` at the start " +
+    "of the thread's first message and keeps the thread at hand, and where {agent} can tag a " +
+    "session it gets the same tag. The name is 1 to 40 letters, digits, `.`, `_` or `-`; a new " +
+    "`!tag` replaces the old one. `!untag` takes the tag and the mark away. A thread whose " +
+    "session has not started yet is marked in {chat} alone.");
+export const GUIDE_DELETE = naming("**Deleting a thread**\n" +
+    "`!delete-thread`, sent inside a session's thread, asks you to confirm, then deletes every " +
+    "message of the thread from {chat}, yours and the bot's. The session stays in {agent}: " +
+    "`!resume` lists it again. A thread that is working or waiting for you is not deleted: " +
+    "`!stop` it first.");
 // Joined to the guide only where allaboard can update itself (`GuideOffer.updates`).
 export const GUIDE_UPDATES = "**Updates**\n" +
     "`!allaboard` shows the version that runs and the latest one. `!allaboard update`, typed in the " +

package/dist/core/wizard.js

@@ -0,0 +1,306 @@
+/**
+ * `allaboard setup`: the terminal wizard that writes an instance's `.env`. The flow is the core's
+ * (refuse a file that exists, ask, check each answer and ask again when it is refused, list what
+ * the file will hold, write it, offer the service); what to ask for the chat and the agent is each
+ * module's (`ModuleSetup`), and how a line is read from the terminal is the host's (`Prompter`).
+ */
+import { randomBytes } from "node:crypto";
+import { closeSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, unlinkSync, writeSync, } from "node:fs";
+import { join, sep } from "node:path";
+import { parseEnv } from "node:util";
+import { errorCode } from "../values.js";
+import { allowedRootOf, ConfigError, REQUIRED, SELECTORS } from "./config.js";
+import { configDirOf } from "./instance.js";
+/** The status a shell reports for a process ended by Ctrl-C. */
+export const INTERRUPTED = 130;
+const [VARIABLE_ALLOWED_ROOT] = REQUIRED;
+/** The variables the wizard itself writes: a test holds them against the core's own lists. */
+export const CORE_VARIABLES = [...SELECTORS, VARIABLE_ALLOWED_ROOT];
+/** One `NAME=value` line, the value quoted when a bare one would not read back as written. */
+function envLine(name, value) {
+    if (/[\r\n]/.test(value) || value.includes("${")) {
+        throw new Error(`${name} cannot be written to .env: it holds a line break or "\${"`);
+    }
+    let written = value;
+    if (/[\s#'"`]/.test(value)) {
+        const quote = ['"', "'", "`"].find((mark) => !value.includes(mark));
+        if (quote === undefined)
+            throw new Error(`${name} cannot be written to .env: it holds every quote`);
+        written = `${quote}${value}${quote}`;
+    }
+    return `${name}=${written}`;
+}
+/**
+ * The text of a `.env` that holds `values` and nothing else. Reads it back through `parseEnv`, the
+ * parser the daemon uses, and throws when a value does not come back as it went in.
+ */
+export function envText(values) {
+    const text = `${Object.entries(values)
+        .map(([name, value]) => envLine(name, value))
+        .join("\n")}\n`;
+    const back = parseEnv(text);
+    for (const [name, value] of Object.entries(values)) {
+        if (back[name] !== value)
+            throw new Error(`${name} does not read back from .env as written`);
+    }
+    return text;
+}
+/**
+ * Creates `file` holding `text`, readable by its owner alone, and fails with `EEXIST` rather than
+ * replace one that is there. The text goes to a temporary file in the same folder first and is
+ * linked to its name, which is atomic and never overwrites; the temporary name is removed either
+ * way. The text is flushed to disk before the link. On Windows Node ignores the modes (as `loadConfig` does not check them there).
+ */
+export function createPrivateFile(file, folder, text) {
+    mkdirSync(folder, { recursive: true, mode: 0o700 });
+    const temporary = join(folder, `.env.${randomBytes(6).toString("hex")}.tmp`);
+    try {
+        const descriptor = openSync(temporary, "wx", 0o600);
+        try {
+            writeSync(descriptor, text);
+            // On disk before the name exists: a power loss must not leave an empty .env that blocks setup.
+            fsyncSync(descriptor);
+        }
+        finally {
+            closeSync(descriptor);
+        }
+        linkSync(temporary, file);
+    }
+    finally {
+        try {
+            unlinkSync(temporary);
+        }
+        catch {
+            // Never created: the write itself failed, and that error is the one to report.
+        }
+    }
+}
+/** Whether `path` exists; throws `Unreadable` for any failure but absence. */
+function exists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT" || errorCode(error) === "ENOTDIR")
+            return false;
+        throw new Unreadable(error);
+    }
+}
+/** `exists` could not tell: the folder is not readable or the path is broken. */
+class Unreadable extends Error {
+    reason;
+    constructor(reason) {
+        super("unreadable");
+        this.reason = reason;
+    }
+}
+/** `path` with the home written as `~`, keeping the system's separator after it. */
+function shown(path, home) {
+    return path === home || path.startsWith(`${home}${sep}`) ? `~${path.slice(home.length)}` : path;
+}
+const instanceFlag = (instance) => instance.name === null ? "" : ` --instance ${instance.name}`;
+/** What a secret answer shows on screen: never its length. */
+const HIDDEN = "********";
+/** The line that stands for an answered question: `? message shown   verdict`. */
+function answerLine(message, shown, verdict) {
+    const head = [`?`, message, shown].filter((part) => part !== "").join(" ");
+    return `${head}${verdict === "" ? "" : `   ${verdict}`}\n`;
+}
+/** Thrown inside the wizard when the owner ends it; never leaves `answerWizard`. */
+class Ended extends Error {
+}
+/**
+ * Asks `message` until `check` accepts the answer, and returns the answer with what the check
+ * set; `value` is what is written for the question's variable (the check's, else the answer). Null
+ * when an optional question is skipped. Throws `Ended` when the owner ends the wizard.
+ */
+async function ask(host, output, question) {
+    for (;;) {
+        const typed = await host.prompter.ask(question.message, question.secret);
+        if (typed === null)
+            throw new Ended();
+        const value = typed.trim() === "" ? (question.default ?? "") : typed.trim();
+        const shown = question.secret ? HIDDEN : value;
+        if (value === "") {
+            if (question.optional) {
+                output.out(answerLine(question.message, "skipped", ""));
+                return null;
+            }
+            output.out(answerLine(question.message, "", "✖ Nothing was typed; this one is needed."));
+            continue;
+        }
+        const checked = await question.check(value);
+        if ("refusal" in checked) {
+            output.out(answerLine(question.message, shown, `✖ ${checked.refusal}`));
+            continue;
+        }
+        // Refused here, not at the write step after every token was pasted.
+        const set = checked.set ?? {};
+        const written = checked.value ?? value;
+        try {
+            envText({ ...set, [question.variable]: written });
+        }
+        catch (error) {
+            output.out(answerLine(question.message, shown, `✖ ${error instanceof Error ? error.message : String(error)}`));
+            continue;
+        }
+        output.out(answerLine(question.message, shown, checked.note === undefined ? "✔" : `✔ ${checked.note}`));
+        return { value: written, set };
+    }
+}
+/** The root question: the same rule the daemon applies when it starts. */
+const ALLOWED_ROOT_QUESTION = {
+    variable: VARIABLE_ALLOWED_ROOT,
+    message: "Folder your projects live under (ALLOWED_ROOT):",
+    secret: false,
+    optional: false,
+    check: async (answer) => {
+        try {
+            allowedRootOf(answer);
+            return {};
+        }
+        catch (error) {
+            if (error instanceof ConfigError)
+                return { refusal: error.message };
+            throw error;
+        }
+    },
+};
+/** Ends the wizard for the owner's Ctrl-C: nothing is written. */
+function cancelled(output) {
+    output.out("\nCancelled: nothing was written.\n");
+    return INTERRUPTED;
+}
+/** Asks which of `entries` to use, `preselected` first, and prints the answer line; null when ended. */
+async function pick(host, output, message, entries, preselected) {
+    const chosen = await host.prompter.choose(message, Object.keys(entries), preselected);
+    if (chosen === null)
+        return null;
+    output.out(answerLine(message, chosen, "✔"));
+    return chosen;
+}
+/**
+ * Asks `questions` in order, adding to `values`. A variable an earlier answer settled is not
+ * asked; a check that sets a variable its question did not declare is a defect of the module.
+ */
+async function asked(questions, values, host, output) {
+    for (const question of questions) {
+        if (Object.hasOwn(values, question.variable))
+            continue;
+        const answered = await ask(host, output, question);
+        if (answered === null)
+            continue;
+        const undeclared = Object.keys(answered.set).filter((name) => !question.sets?.includes(name));
+        if (undeclared.length > 0) {
+            throw new Error(`the check of ${question.variable} set ${undeclared.join(", ")} without declaring it in "sets"`);
+        }
+        values[question.variable] = answered.value;
+        Object.assign(values, answered.set);
+    }
+}
+/**
+ * Answers `allaboard setup` for `instance`: asks which chat and which agent to use and writes the
+ * two selectors, asks what the chat needs, the allowed root, then what the agent needs, lists the
+ * file's variables, writes `.env` and offers the service. Refuses before asking anything when
+ * there is no terminal or the file exists; refuses after the two picks when the chosen chat
+ * offers no setup. Returns the exit status: 0, 1 for a refusal or a failed write, 130 when the
+ * owner ended it.
+ */
+export async function answerWizard(instance, modules, output, host) {
+    const refuse = (sentence) => {
+        output.err(`allaboard setup: ${sentence}\n`);
+        return 1;
+    };
+    const { defaults } = modules;
+    if (!host.interactive)
+        return refuse("it needs a terminal to ask on.");
+    const folder = configDirOf(instance, host.home);
+    const file = join(folder, ".env");
+    const name = shown(file, host.home);
+    try {
+        if (exists(file)) {
+            return refuse(`${name} exists already. Edit it, or move it away to run setup again.`);
+        }
+    }
+    catch (error) {
+        if (!(error instanceof Unreadable))
+            throw error;
+        return refuse(`cannot look at ${name} (${errorCode(error.reason) ?? "unknown error"}).`);
+    }
+    output.out(`\nallaboard setup: writes ${name}\n\n`);
+    const [agentSelector, chatSelector] = SELECTORS;
+    // A list of one is still shown: the owner sees what the build holds and confirms it.
+    const chatName = await pick(host, output, `Chat (${chatSelector}):`, modules.chats, defaults.chat);
+    if (chatName === null)
+        return cancelled(output);
+    const agentName = await pick(host, output, `Agent (${agentSelector}):`, modules.agents, defaults.agent);
+    if (agentName === null)
+        return cancelled(output);
+    const chat = modules.chats[chatName];
+    if (chat.setup === undefined) {
+        return refuse(`the chat ${chatName} offers no setup; write .env by hand (docs/setup.md).`);
+    }
+    const chatSetup = chat.setup(instance);
+    const agentSetup = modules.agents[agentName].setup?.();
+    output.out("\n");
+    for (const line of chatSetup.intro)
+        output.out(`${line}\n`);
+    output.out("\n");
+    const values = {
+        [agentSelector]: agentName,
+        [chatSelector]: chatName,
+    };
+    // Secret is known from the question that asks for the variable, never from its value.
+    const secrets = new Set([...chatSetup.questions, ...(agentSetup?.questions ?? [])]
+        .filter((q) => q.secret)
+        .map((q) => q.variable));
+    try {
+        await asked([...chatSetup.questions, ALLOWED_ROOT_QUESTION], values, host, output);
+        if (agentSetup !== undefined) {
+            for (const line of agentSetup.intro)
+                output.out(`${line}\n`);
+            await asked(agentSetup.questions, values, host, output);
+        }
+    }
+    catch (error) {
+        if (!(error instanceof Ended))
+            throw error;
+        return cancelled(output);
+    }
+    output.out("\nThe file holds:\n");
+    for (const [variable, value] of Object.entries(values)) {
+        output.out(`  ${variable}=${secrets.has(variable) ? HIDDEN : shown(value, host.home)}\n`);
+    }
+    try {
+        createPrivateFile(file, folder, envText(values));
+    }
+    catch (error) {
+        return refuse(errorCode(error) === "EEXIST"
+            ? `${name} appeared while you answered; nothing was changed.`
+            : `could not write ${name}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    output.out(`\nWrote ${name}${process.platform === "win32" ? "" : " (readable by you only)"}.\n\n`);
+    const later = `Start it with \`allaboard${instanceFlag(instance)}\`.\n`;
+    if (host.installService === null) {
+        output.out(later);
+        return 0;
+    }
+    const message = "Start allaboard now and at every login?";
+    const picked = await host.prompter.choose(message, ["Yes", "No"], "Yes");
+    if (picked === null) {
+        output.out("\nThe file is written; the service is not installed.\n");
+        return INTERRUPTED;
+    }
+    output.out(answerLine(message, picked, "✔"));
+    if (picked !== "Yes") {
+        output.out(`Not installed. \`allaboard service install${instanceFlag(instance)}\` does it later.\n`);
+        return 0;
+    }
+    const report = host.installService();
+    for (const line of report.out)
+        output.out(`${line}\n`);
+    for (const line of report.err)
+        output.err(`${line}\n`);
+    return report.code;
+}

package/dist/daemon.js

@@ -68,9 +68,9 @@
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { AgentConfigError } from "./agent/seam.js";
-import { answer, answerUpdate, parseArguments } from "./cli.js";
+import { answer, answerSetup, answerUpdate, parseArguments } from "./cli.js";
 import { monotonicClock, systemClock } from "./clock.js";
-import { CLEAN_EVERY_SECONDS, clean } from "./core/cleanup.js";
+import { CLEAN_EVERY_SECONDS, Cleanups, clean } from "./core/cleanup.js";
 import { ConfigError, loadConfig } from "./core/config.js";
 import { buildFlows } from "./core/flows/flows.js";
 import { postUpgradeNotices, rewriteRestartNotice } from "./core/flows/notices.js";
@@ -345,15 +345,18 @@ export async function run(options = {}) {
             now: () => wall.time(),
             updates,
         });
-        core = { sessions, state, approvals, holds, agent: backend, updates };
-        const cleanOnce = () => clean((channel) => chat.channelState(channel), state, {
+        const isStopping = () => sessions.draining || (stop?.received.length ?? 0) > 0;
+        // Every pass goes through `Cleanups`: the start's, the schedule's and the owner's Refresh never
+        // overlap, and none begins once a stop has.
+        const cleanups = new Cleanups(() => clean((channel) => chat.channelState(channel), state, {
             threadLookup: (ref) => chat.threadState(ref),
-            stopping: () => sessions.draining || (stop?.received.length ?? 0) > 0,
+            stopping: isStopping,
             alive: async (directory) => backend.capabilities.sessionListing ? backend.aliveSessions(directory) : null,
             live: () => sessions.liveThreads(),
             chat: chat.name,
             openedAt: (ref) => chat.openedAt(ref),
-        });
+        }), isStopping);
+        core = { sessions, state, approvals, holds, agent: backend, updates, cleanup: cleanups };
         const cleaning = new AbortController();
         let cleaned = null;
         let checked = null;
@@ -376,10 +379,10 @@ export async function run(options = {}) {
             // known to its workspace) works without it, and opening it is what starts delivering
             // events. A pruned thread's leftovers must be repaired first.
             await repair(chat, state);
-            await cleanOnce();
+            await cleanups.request();
             cleaned = cleanEvery({
                 seconds: CLEAN_EVERY_SECONDS,
-                clean: cleanOnce,
+                clean: () => cleanups.request(),
                 sessions,
                 clock: steady,
                 signal: cleaning.signal,
@@ -427,8 +430,12 @@ export async function run(options = {}) {
             // Past the drain (or with none: a SIGINT, a failure) an install is not waited for: npm is
             // sent SIGTERM and the stop goes on once it has put the old folder back.
             await step("end the install", () => endInstall(updates, steady, progress, options.waitingForInstall), progress);
-            if (cleaned !== null)
-                await step("stop the cleanup", () => cleaned, progress);
+            // The schedule, and a pass the owner's Refresh started: neither may ask Slack once the chat
+            // has stopped or prune once the sessions have closed.
+            await step("stop the cleanup", async () => {
+                await cleaned;
+                await cleanups.settled();
+            }, progress);
             // The connection, and the clips' waits, whose timers would keep the process alive.
             await step("stop the chat", async () => {
                 try {
@@ -559,8 +566,13 @@ export async function start() {
         err: (text) => process.stderr.write(text),
     };
     // An exit code, not `process.exit`: a write to a pipe can still be pending on macOS.
+    if (invocation.kind === "setup") {
+        const { chats, agents, defaults } = REGISTRY;
+        process.exitCode = await answerSetup(invocation, { chats, agents, defaults }, output);
+        return;
+    }
     process.exitCode =
         invocation.kind === "update"
             ? await answerUpdate(invocation, output)
-            : answer(invocation, output);
+            : answer(invocation, output, REGISTRY.agents);
 }