sfora-cli 0.12.0 → 0.13.0

package/dist/api-client.d.ts

@@ -576,6 +576,37 @@ export declare class SforaApiClient {
     sendRoomMessage(roomId: string, body: string): Promise<{
         messageId: string;
     }>;
+    /**
+     * `POST /api/presence` with `{ roomId?, client? }` — one presence beat.
+     *
+     * `client` is a short slug ("cli", "claude-code") that names what kind of
+     * client is on the line; the app reads it out next to the online dot. The
+     * server sanitizes and owns the field on every beat, so a beat without a
+     * label also clears a stale one.
+     */
+    heartbeat(params?: {
+        roomId?: string;
+        client?: string;
+    }): Promise<void>;
+    /**
+     * `POST /api/asks` — post a coordination ask, or (with `options`) a
+     * QUESTION: 2–4 short answers for a human to pick from. `target` is a
+     * member NAME (or id), resolved server-side; an ambiguous name comes back
+     * as a 400 listing the candidates. Only humans can answer a question —
+     * enforced in the mutation, not here.
+     */
+    createAsk(params: {
+        text: string;
+        options?: string[];
+        /** Member name or id the question is for — a human. */
+        target?: string;
+        /** Project slug the ask belongs to. */
+        project?: string;
+        /** Room to announce the ask into. */
+        roomId?: string;
+    }): Promise<{
+        askId: string;
+    }>;
     /** `GET /v1/fs/inbox/mentions.md` — markdown summary of unread mentions. */
     readInbox(): Promise<string>;
     /** `GET /v1/fs/me/api-key` — text identity (no key material). */

package/dist/api-client.js

@@ -637,6 +637,37 @@ export class SforaApiClient {
         const res = await this.#request("POST", `/api/rooms/${encodeURIComponent(roomId)}/messages`, JSON.stringify({ body }), undefined, "application/json");
         return this.#jsonFrom(res);
     }
+    /**
+     * `POST /api/presence` with `{ roomId?, client? }` — one presence beat.
+     *
+     * `client` is a short slug ("cli", "claude-code") that names what kind of
+     * client is on the line; the app reads it out next to the online dot. The
+     * server sanitizes and owns the field on every beat, so a beat without a
+     * label also clears a stale one.
+     */
+    async heartbeat(params = {}) {
+        await this.#request("POST", "/api/presence", JSON.stringify(params), undefined, "application/json");
+    }
+    /**
+     * `POST /api/asks` — post a coordination ask, or (with `options`) a
+     * QUESTION: 2–4 short answers for a human to pick from. `target` is a
+     * member NAME (or id), resolved server-side; an ambiguous name comes back
+     * as a 400 listing the candidates. Only humans can answer a question —
+     * enforced in the mutation, not here.
+     */
+    async createAsk(params) {
+        const body = { text: params.text };
+        if (params.options)
+            body.options = params.options;
+        if (params.target)
+            body.target = params.target;
+        if (params.project)
+            body.project = params.project;
+        if (params.roomId)
+            body.roomId = params.roomId;
+        const res = await this.#request("POST", "/api/asks", JSON.stringify(body), undefined, "application/json");
+        return this.#jsonFrom(res);
+    }
     /** `GET /v1/fs/inbox/mentions.md` — markdown summary of unread mentions. */
     async readInbox() {
         return this.#text("/v1/fs/inbox/mentions.md");

package/dist/ask.d.ts

@@ -0,0 +1,75 @@
+/**
+ * `sfora ask` — an agent asks a human, from the terminal.
+ *
+ * An ask with options is a QUESTION: 2–4 short answers for a human to pick
+ * from, optionally aimed at one person with `--for`. Only humans can answer —
+ * the server enforces that in the mutation, this module just says it in the
+ * error copy. Everything decision-shaped lives here as pure functions
+ * (validation, the wait loop, the ambiguity reformat) so it can be tested with
+ * canned data; `cli.ts` owns the process — signals, the real streams.
+ *
+ * The wait loop rides `/v1/events`, the same long-poll `sfora watch` and
+ * `sfora chat` use: the feed carries an `ask` event for every state change of
+ * an ask the caller created, and a resolved one carries `chosenOption` (the
+ * picked answer) and `resolution`. So waiting is a wake, not a poll schedule.
+ */
+import type { AgentEventsPage } from "./api-client.js";
+export declare const ASK_OPTIONS_MIN = 2;
+export declare const ASK_OPTIONS_MAX = 4;
+export declare const ASK_OPTION_MAX_LENGTH = 80;
+/**
+ * The options as they will be sent, or a thrown explanation.
+ *
+ * Mirrors the server's write-door rule (2–4 entries, trimmed nonempty, ≤80
+ * chars) so a typo fails at the prompt with a usable message instead of as a
+ * 400 after a round trip. The server still validates — this is a courtesy,
+ * not the gate.
+ */
+export declare function validateAskOptions(raw: string[]): string[];
+/**
+ * A server refusal that lists candidates, reshaped for a terminal.
+ *
+ * The `/api/asks` door answers an ambiguous `--for` with one line:
+ * `Ambiguous target 'sam' (candidates: Sam One <id>, Sam Two <id>)`. Reshaped
+ * to the same say-which layout `sfora join` uses for rooms — one candidate per
+ * line, so the retype is a copy. Any message without the candidates suffix is
+ * returned unchanged.
+ */
+export declare function reshapeCandidatesError(message: string): string;
+/** Everything the wait loop needs from the outside world. */
+export interface AskWaitDeps {
+    /** One `/v1/events` long-poll. Rejects on a drop — the loop backs off. */
+    poll(since: number): Promise<AgentEventsPage>;
+    /** A warning, on stderr — never mixed into stdout. */
+    warn(text: string): void;
+    sleep(ms: number): Promise<void>;
+    /** The clock, injectable for tests. */
+    now?(): number;
+}
+export interface AskWaitOptions {
+    askId: string;
+    /** Events cursor to start from — BEFORE the ask was created, with slack. */
+    since: number;
+    /** Absolute deadline (ms epoch); absent means wait forever. */
+    deadlineMs?: number;
+    stopped?: () => boolean;
+    backoffMs?: number;
+}
+export type AskWaitResult = {
+    outcome: "answered";
+    chosenOption?: string;
+    resolution?: string;
+} | {
+    outcome: "timeout";
+} | {
+    outcome: "stopped";
+};
+/**
+ * Poll until the ask resolves, the deadline passes, or the caller stops.
+ *
+ * The same rules the other loops hold: the cursor survives reconnects and
+ * only moves forward, drops back off (doubling to {@link MAX_BACKOFF_MS}) and
+ * recover fast. Only a `resolved` event for THIS ask ends the wait — claims
+ * and other asks' traffic pass through silently.
+ */
+export declare function askWaitLoop(deps: AskWaitDeps, options: AskWaitOptions): Promise<AskWaitResult>;

package/dist/ask.js

@@ -0,0 +1,119 @@
+/**
+ * `sfora ask` — an agent asks a human, from the terminal.
+ *
+ * An ask with options is a QUESTION: 2–4 short answers for a human to pick
+ * from, optionally aimed at one person with `--for`. Only humans can answer —
+ * the server enforces that in the mutation, this module just says it in the
+ * error copy. Everything decision-shaped lives here as pure functions
+ * (validation, the wait loop, the ambiguity reformat) so it can be tested with
+ * canned data; `cli.ts` owns the process — signals, the real streams.
+ *
+ * The wait loop rides `/v1/events`, the same long-poll `sfora watch` and
+ * `sfora chat` use: the feed carries an `ask` event for every state change of
+ * an ask the caller created, and a resolved one carries `chosenOption` (the
+ * picked answer) and `resolution`. So waiting is a wake, not a poll schedule.
+ */
+import { MAX_BACKOFF_MS } from "./watch.js";
+// ─── Option validation (the client-side half of the write gate) ──────
+export const ASK_OPTIONS_MIN = 2;
+export const ASK_OPTIONS_MAX = 4;
+export const ASK_OPTION_MAX_LENGTH = 80;
+/**
+ * The options as they will be sent, or a thrown explanation.
+ *
+ * Mirrors the server's write-door rule (2–4 entries, trimmed nonempty, ≤80
+ * chars) so a typo fails at the prompt with a usable message instead of as a
+ * 400 after a round trip. The server still validates — this is a courtesy,
+ * not the gate.
+ */
+export function validateAskOptions(raw) {
+    const options = raw.map((o) => o.trim());
+    const empty = options.findIndex((o) => !o);
+    if (empty !== -1) {
+        throw new Error(`option ${empty + 1} is empty — every option needs text`);
+    }
+    if (options.length < ASK_OPTIONS_MIN || options.length > ASK_OPTIONS_MAX) {
+        throw new Error(`a question carries ${ASK_OPTIONS_MIN}–${ASK_OPTIONS_MAX} options — you gave ${options.length}. ` +
+            'Repeat --option for each answer: --option "Basic" --option "Business"');
+    }
+    const long = options.find((o) => o.length > ASK_OPTION_MAX_LENGTH);
+    if (long) {
+        throw new Error(`an option is a short answer, not a paragraph — keep each under ${ASK_OPTION_MAX_LENGTH} characters ` +
+            `("${long.slice(0, 40)}…" is ${long.length})`);
+    }
+    const seen = new Set();
+    for (let i = 0; i < options.length; i++) {
+        if (seen.has(options[i])) {
+            throw new Error(`option ${i + 1} repeats "${options[i]}" — every option must be distinct`);
+        }
+        seen.add(options[i]);
+    }
+    return options;
+}
+/**
+ * A server refusal that lists candidates, reshaped for a terminal.
+ *
+ * The `/api/asks` door answers an ambiguous `--for` with one line:
+ * `Ambiguous target 'sam' (candidates: Sam One <id>, Sam Two <id>)`. Reshaped
+ * to the same say-which layout `sfora join` uses for rooms — one candidate per
+ * line, so the retype is a copy. Any message without the candidates suffix is
+ * returned unchanged.
+ */
+export function reshapeCandidatesError(message) {
+    const m = /^(.*?)\s*\(candidates:\s*(.+)\)\s*$/.exec(message);
+    if (!m)
+        return message;
+    return (`${m[1].trim()} — say which:\n` +
+        m[2]
+            .split(", ")
+            .map((c) => `  ${c}`)
+            .join("\n"));
+}
+/**
+ * Poll until the ask resolves, the deadline passes, or the caller stops.
+ *
+ * The same rules the other loops hold: the cursor survives reconnects and
+ * only moves forward, drops back off (doubling to {@link MAX_BACKOFF_MS}) and
+ * recover fast. Only a `resolved` event for THIS ask ends the wait — claims
+ * and other asks' traffic pass through silently.
+ */
+export async function askWaitLoop(deps, options) {
+    const stopped = options.stopped ?? (() => false);
+    const now = deps.now ?? Date.now;
+    const firstBackoff = options.backoffMs ?? 1_000;
+    let cursor = options.since;
+    let backoff = firstBackoff;
+    while (!stopped()) {
+        if (options.deadlineMs !== undefined && now() >= options.deadlineMs) {
+            return { outcome: "timeout" };
+        }
+        let page;
+        try {
+            page = await deps.poll(cursor);
+        }
+        catch (error) {
+            if (stopped())
+                break;
+            const message = error instanceof Error ? error.message : String(error);
+            deps.warn(`reconnecting in ${Math.round(backoff / 1000)}s — ${message}`);
+            await deps.sleep(backoff);
+            backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+            continue;
+        }
+        backoff = firstBackoff;
+        for (const event of page.events) {
+            if (event.type !== "ask" || event.askId !== options.askId)
+                continue;
+            if (event.askState !== "resolved")
+                continue;
+            return {
+                outcome: "answered",
+                chosenOption: typeof event.chosenOption === "string" ? event.chosenOption : undefined,
+                resolution: typeof event.resolution === "string" ? event.resolution : undefined,
+            };
+        }
+        // Never backwards: an empty page holds the cursor where it was.
+        cursor = Math.max(cursor, page.cursor);
+    }
+    return { outcome: "stopped" };
+}

package/dist/chat.d.ts

@@ -17,6 +17,33 @@
  * print twice.
  */
 import type { AgentEventsPage, ChatMessage, Room } from "./api-client.js";
+/**
+ * A presence client label as the server stores it: lowercase, `[a-z0-9-]`
+ * only, at most 32 chars. Anything that sanitizes to nothing is nothing —
+ * the caller falls through to its next guess.
+ */
+export declare function sanitizeClientSlug(raw: string | undefined): string | undefined;
+/**
+ * The client slugs sfora knows by name — the shared vocabulary with the web
+ * app's client marks. Unknown slugs stay valid everywhere; they just render
+ * the generic terminal glyph in the app.
+ */
+export declare const KNOWN_CLIENTS: readonly ["claude-code", "codex", "cursor", "gemini", "windsurf", "aider", "opencode", "cli"];
+/**
+ * What kind of client is on the line, for the presence label.
+ *
+ * Order: an explicit `--client` flag wins; then the per-client env markers in
+ * {@link CLIENT_MARKERS}; then `AI_AGENT` (the part before the first
+ * underscore — `claude-code_2-1-233_agent` names "claude-code"); then
+ * `CLAUDE_CODE_ENTRYPOINT` or `CLAUDECODE` being set at all means Claude Code
+ * is driving (kept below `AI_AGENT`, its long-standing rung); then
+ * `CURSOR_TRACE_ID` — set by Cursor's integrated TERMINAL and inherited by
+ * everything launched from it, so it sits at the bottom: Claude Code run
+ * inside Cursor must read as claude-code, not as the window around it. Else
+ * this is a plain terminal — "cli". Env is passed in, not read, so every rung
+ * is testable.
+ */
+export declare function detectClient(env: Record<string, string | undefined>, flag?: string): string;
 /** How `sfora rooms` and `sfora join` spell a room name as an argument. */
 export declare function roomSlug(name: string): string;
 export type RoomMatch = {

package/dist/chat.js

@@ -19,6 +19,85 @@
 import { colors } from "./render.js";
 import { MAX_BACKOFF_MS } from "./watch.js";
 const dim = (text) => `${colors.dim}${text}${colors.reset}`;
+// ─── Client identity (presence label) ────────────────────────────────
+/**
+ * A presence client label as the server stores it: lowercase, `[a-z0-9-]`
+ * only, at most 32 chars. Anything that sanitizes to nothing is nothing —
+ * the caller falls through to its next guess.
+ */
+export function sanitizeClientSlug(raw) {
+    if (!raw)
+        return undefined;
+    const slug = raw.toLowerCase().replace(/[^a-z0-9-]/g, "").slice(0, 32);
+    return slug || undefined;
+}
+/**
+ * The client slugs sfora knows by name — the shared vocabulary with the web
+ * app's client marks. Unknown slugs stay valid everywhere; they just render
+ * the generic terminal glyph in the app.
+ */
+export const KNOWN_CLIENTS = [
+    "claude-code",
+    "codex",
+    "cursor",
+    "gemini",
+    "windsurf",
+    "aider",
+    "opencode",
+    "cli",
+];
+/**
+ * Env markers the coding agents actually set, checked in order.
+ *
+ * Only markers verified in the wild are listed — naming the wrong client is
+ * worse than falling through to the generic label, so windsurf / aider /
+ * opencode (no reliable marker known) rely on `--client` or `AI_AGENT`.
+ * Being set at all counts, even empty, matching the Claude Code rung below.
+ *
+ *   CODEX_SANDBOX / CODEX_SANDBOX_NETWORK_DISABLED — OpenAI's Codex CLI sets
+ *     these on the commands it runs.
+ *   GEMINI_CLI — Google's Gemini CLI sets `GEMINI_CLI=1` in its shell tool.
+ *   CURSOR_AGENT — Cursor's agent CLI names itself this way.
+ */
+const CLIENT_MARKERS = [
+    ["CODEX_SANDBOX", "codex"],
+    ["CODEX_SANDBOX_NETWORK_DISABLED", "codex"],
+    ["GEMINI_CLI", "gemini"],
+    ["CURSOR_AGENT", "cursor"],
+];
+/**
+ * What kind of client is on the line, for the presence label.
+ *
+ * Order: an explicit `--client` flag wins; then the per-client env markers in
+ * {@link CLIENT_MARKERS}; then `AI_AGENT` (the part before the first
+ * underscore — `claude-code_2-1-233_agent` names "claude-code"); then
+ * `CLAUDE_CODE_ENTRYPOINT` or `CLAUDECODE` being set at all means Claude Code
+ * is driving (kept below `AI_AGENT`, its long-standing rung); then
+ * `CURSOR_TRACE_ID` — set by Cursor's integrated TERMINAL and inherited by
+ * everything launched from it, so it sits at the bottom: Claude Code run
+ * inside Cursor must read as claude-code, not as the window around it. Else
+ * this is a plain terminal — "cli". Env is passed in, not read, so every rung
+ * is testable.
+ */
+export function detectClient(env, flag) {
+    const fromFlag = sanitizeClientSlug(flag);
+    if (fromFlag)
+        return fromFlag;
+    for (const [envVar, slug] of CLIENT_MARKERS) {
+        if (env[envVar] !== undefined)
+            return slug;
+    }
+    const fromAgent = sanitizeClientSlug(env.AI_AGENT?.split("_")[0]);
+    if (fromAgent)
+        return fromAgent;
+    if (env.CLAUDE_CODE_ENTRYPOINT !== undefined ||
+        env.CLAUDECODE !== undefined) {
+        return "claude-code";
+    }
+    if (env.CURSOR_TRACE_ID !== undefined)
+        return "cursor";
+    return "cli";
+}
 // ─── Room resolution ─────────────────────────────────────────────────
 /** How `sfora rooms` and `sfora join` spell a room name as an argument. */
 export function roomSlug(name) {

package/dist/cli-args.d.ts

@@ -26,7 +26,12 @@ export interface CliArgs {
     block?: string;
     self: boolean;
     wait?: number;
+    waitFlag: boolean;
     message?: string;
     limit?: number;
+    client?: string;
+    option: string[];
+    target?: string;
+    room?: string;
 }
 export declare function parseArgs(argv: string[]): CliArgs;

package/dist/cli-args.js

@@ -6,7 +6,7 @@
  * process — argv in, a parsed shape out.
  */
 export function parseArgs(argv) {
-    const args = { rest: [], cwd: "/", mcp: false, help: false, draft: false, json: false, local: false, cloud: false, self: false };
+    const args = { rest: [], cwd: "/", mcp: false, help: false, draft: false, json: false, local: false, cloud: false, self: false, waitFlag: false, option: [] };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === "--mcp")
@@ -65,10 +65,22 @@ export function parseArgs(argv) {
             args.block = a.slice("--block=".length);
         else if (a === "--self")
             args.self = true;
-        else if (a === "--wait")
-            args.wait = Number.parseInt(argv[++i] ?? "", 10);
-        else if (a.startsWith("--wait="))
+        // `--wait` doubles as a bare flag (`ask --wait` blocks until the answer)
+        // and a valued one (`watch --wait 10`, `ask --wait 300`). The next token
+        // is consumed only when it is a number, so `ask --wait --json` keeps its
+        // `--json` — the historical "missing value means NaN" shape survives as
+        // `wait: undefined` (every reader already treats non-finite as unset).
+        else if (a === "--wait") {
+            args.waitFlag = true;
+            const next = argv[i + 1];
+            if (next !== undefined && /^\d+$/.test(next)) {
+                args.wait = Number.parseInt(argv[++i], 10);
+            }
+        }
+        else if (a.startsWith("--wait=")) {
+            args.waitFlag = true;
             args.wait = Number.parseInt(a.slice("--wait=".length), 10);
+        }
         else if (a === "-m" || a === "--message")
             args.message = argv[++i];
         else if (a.startsWith("--message="))
@@ -77,6 +89,25 @@ export function parseArgs(argv) {
             args.limit = Number.parseInt(argv[++i] ?? "", 10);
         else if (a.startsWith("--limit="))
             args.limit = Number.parseInt(a.slice("--limit=".length), 10);
+        else if (a === "--client")
+            args.client = argv[++i];
+        else if (a.startsWith("--client="))
+            args.client = a.slice("--client=".length);
+        else if (a === "--option") {
+            const value = argv[++i];
+            if (value !== undefined)
+                args.option.push(value);
+        }
+        else if (a.startsWith("--option="))
+            args.option.push(a.slice("--option=".length));
+        else if (a === "--for")
+            args.target = argv[++i];
+        else if (a.startsWith("--for="))
+            args.target = a.slice("--for=".length);
+        else if (a === "--room")
+            args.room = argv[++i];
+        else if (a.startsWith("--room="))
+            args.room = a.slice("--room=".length);
         else if (!a.startsWith("-")) {
             if (!args.command)
                 args.command = a;

package/dist/cli.js

@@ -11,7 +11,8 @@ import { spawn } from "node:child_process";
 import { readFile as readLocalFile } from "node:fs/promises";
 import { basename } from "node:path";
 import { taskUploadFilename } from "./format/taskUploadFilename.js";
-import { createSforaShell, createLocalShell, } from "./index.js";
+import { createSforaShell, createLocalShell, SforaApiError, } from "./index.js";
+import { askWaitLoop, reshapeCandidatesError, validateAskOptions, } from "./ask.js";
 import { openerCommand } from "./opener.js";
 import { blocksCommand, presenceNotice, putCommand, } from "./block-commands.js";
 import { colors, ndjson, presenceRecords, renderPresence, renderWriteEffect, urlLine, PRESENCE_NOTE, } from "./render.js";
@@ -20,7 +21,7 @@ import { LocalWorkspace, initWorkspace, findWorkspace, migrateWorkspaceStages, }
 import { runMcpServer } from "./mcp-server.js";
 import { readConfig, writeConfig, resolveSettings, upsertProfile, effectiveProfiles, DEFAULT_URL, } from "./config.js";
 import { parseArgs } from "./cli-args.js";
-import { chatTailLoop, renderChatMessage, renderRoomList, resolveRoomRef, roomSlug, } from "./chat.js";
+import { capitalizeName, chatTailLoop, detectClient, renderChatMessage, renderRoomList, resolveRoomRef, roomSlug, } from "./chat.js";
 const HELP = `sfora — the CLI for your sfora workspace
 
 Get started (no account needed):
@@ -69,6 +70,23 @@ Chat:
   sfora chat <room> -m "text"         Send one message and exit (for scripts
                                       and agents)
 
+  Chat shows others what's on the line: the CLI reports itself in presence,
+  and a coding agent is named automatically (Claude Code, Codex, Cursor and
+  Gemini set their own environment). Add --client <name> to say it yourself.
+
+Ask a human:
+  sfora ask "<question>" --option "A" --option "B"
+                                      Post a question with 2–4 answers to
+                                      pick from — only humans can answer
+  sfora ask "…" --option … --for <member>
+                                      Aim it at one person (any human may
+                                      still answer)
+  sfora ask "…" --option … --wait [secs]
+                                      Block until someone answers, then print
+                                      the choice (give secs to stop waiting)
+  Add --project <slug> or --room <room> to say where it belongs; --json for
+  scripts (--wait prints a second JSON line when the answer lands).
+
 Write, and watch others write:
   sfora blocks <path>                 List a document's addressable blocks
   sfora put <path> <file.md>          Write a file (add --block <id> for one block)
@@ -362,6 +380,7 @@ const VERBS = new Set([
     "rooms",
     "join",
     "chat",
+    "ask",
 ]);
 async function runVerb(args, fs, client) {
     const ok = (msg) => console.log(`${colors.green}✓${colors.reset} ${msg}`);
@@ -524,6 +543,9 @@ async function runVerb(args, fs, client) {
         }
         return runChat(args, client);
     }
+    if (args.command === "ask") {
+        return runAsk(args, client);
+    }
     if (args.command === "me" || args.command === "whoami") {
         const text = (await client.readMe()).trim();
         if (args.json) {
@@ -801,11 +823,19 @@ async function runChat(args, client) {
         await client.joinRoom(room._id);
         console.log(`${colors.green}✓${colors.reset} Joined ${tag}`);
     }
+    // Presence is decoration: a beat that fails changes nothing about the
+    // conversation, so every beat here is best-effort and silent. The label
+    // says WHAT is on the line — "cli", or "claude-code" when a coding agent
+    // is driving — so the app can show the terminal next to the online dot.
+    const clientLabel = detectClient(process.env, args.client);
+    const beat = () => client.heartbeat({ roomId: room._id, client: clientLabel }).catch(() => { });
     // One-shot send.
     if (args.message !== undefined) {
         const text = args.message.trim();
         if (!text)
             throw new Error('usage: sfora chat <room> -m "text"');
+        // One beat alongside the send — a script that speaks was here, briefly.
+        void beat();
         const { messageId } = await client.sendRoomMessage(room._id, text);
         if (args.json) {
             console.log(JSON.stringify({ messageId, roomId: room._id }, null, 2));
@@ -831,6 +861,12 @@ async function runChat(args, client) {
     for (const msg of messages)
         console.log(renderChatMessage(msg, Date.now()));
     process.stderr.write(`${colors.dim}${tag} — type to send · /quit (or ^C) to leave${colors.reset}\n`);
+    // Sitting in the room is being present in it: beat now, then every ~45s
+    // (presence expires server-side, so the cadence just has to outrun the
+    // timeout). `unref` so the timer never keeps the process alive on its own.
+    void beat();
+    const pulse = setInterval(() => void beat(), 45_000);
+    pulse.unref?.();
     // The prompt and the tail share one screen: an arriving message clears the
     // prompt line, prints, and readline redraws the prompt with whatever was
     // being typed. `readline.clearLine` over anything fancier — robust beats
@@ -904,10 +940,162 @@ async function runChat(args, client) {
     stop = true;
     inFlight.abort();
     rl.close();
+    clearInterval(pulse);
+    // A parting beat, best-effort — awaited so quitting doesn't race process
+    // exit, but never allowed to hold the door.
+    await beat();
     await tail.catch(() => { });
     if (isTty)
         console.log("");
 }
+/**
+ * `sfora ask` — how an agent asks a human, wired to the real process.
+ *
+ * With `--option` flags the ask is a QUESTION: 2–4 short answers a human
+ * picks from in the app — only humans can answer, and the server enforces
+ * that in the mutation, not the UI. `--for` aims it at one person by name
+ * (resolved server-side; any human may still answer). Everything
+ * decision-shaped (validation, the wait loop, the ambiguity reformat) lives
+ * in `ask.ts` where it is tested; this owns signals and the streams.
+ */
+async function runAsk(args, client) {
+    const text = args.rest.join(" ").trim();
+    if (!text) {
+        throw new Error('usage: sfora ask "<question>" --option "A" --option "B" ' +
+            "[--for <member>] [--project <slug>] [--room <room>] [--wait [secs]] [--json]");
+    }
+    const options = args.option.length > 0 ? validateAskOptions(args.option) : undefined;
+    let roomId;
+    let roomTag;
+    if (args.room) {
+        const room = await resolveRoomOrThrow(client, args.room);
+        roomId = room._id;
+        roomTag = `#${roomSlug(room.name)}`;
+    }
+    // The wait cursor is taken BEFORE the create, with generous skew slack: an
+    // answer landing between the create and the first poll must not fall into a
+    // blind window, and overlap is harmless — the loop matches on this ask's id
+    // and resolved state only.
+    const since = Date.now() - 5 * 60_000;
+    let created;
+    try {
+        created = await client.createAsk({
+            text,
+            options,
+            target: args.target,
+            project: args.project,
+            roomId,
+        });
+    }
+    catch (e) {
+        // An ambiguous `--for` comes back as a 400 listing the candidates on one
+        // line — reshape it to the say-which layout `sfora join` uses for rooms.
+        if (e instanceof SforaApiError && e.status === 400) {
+            throw new Error(reshapeCandidatesError(e.message));
+        }
+        throw e;
+    }
+    const { url } = client.takeResponseInfo();
+    const where = [
+        args.project ? `project ${args.project}` : undefined,
+        roomTag,
+    ]
+        .filter(Boolean)
+        .join(" · ");
+    if (args.json) {
+        // NDJSON-shaped under --wait: this line says it landed; a second line
+        // (below) says how it resolved. A script reads each as it arrives.
+        console.log(JSON.stringify({
+            askId: created.askId,
+            ...(url ? { url } : {}),
+            ...(options ? { options } : {}),
+            ...(args.target ? { for: args.target } : {}),
+        }));
+    }
+    else {
+        console.log(`${colors.green}✓${colors.reset} Asked${where ? ` in ${where}` : ""} · ${created.askId}`);
+        if (options) {
+            console.log(`  ${colors.dim}options: ${options.join(" · ")}${colors.reset}`);
+        }
+        if (args.target) {
+            console.log(`  ${colors.dim}for ${capitalizeName(args.target)} — only a human can answer${colors.reset}`);
+        }
+        if (url)
+            process.stderr.write(`  ${urlLine(url)}\n`);
+    }
+    if (!args.waitFlag)
+        return;
+    // `--wait [secs]`: block on the events long-poll until a human answers.
+    // ^C has to reach the socket, same as `watch`: the poll hangs for tens of
+    // seconds, and a flag alone would leave a terminal that says it stopped and
+    // hasn't. Second ^C stands down and lets the default behaviour end things.
+    const deadlineMs = Number.isFinite(args.wait) && args.wait > 0
+        ? Date.now() + args.wait * 1000
+        : undefined;
+    let stop = false;
+    const inFlight = new AbortController();
+    let signalled = false;
+    const onSignal = (signal) => {
+        stop = true;
+        inFlight.abort();
+        if (signalled) {
+            process.off("SIGINT", onSignal);
+            process.off("SIGTERM", onSignal);
+            process.kill(process.pid, signal);
+            return;
+        }
+        signalled = true;
+    };
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
+    if (!args.json) {
+        process.stderr.write(`${colors.dim}waiting for an answer${deadlineMs ? ` (up to ${args.wait}s)` : ""} — ^C to stop${colors.reset}\n`);
+    }
+    try {
+        const result = await askWaitLoop({
+            // With a deadline, cap each poll's server-side budget to what is left
+            // so the last poll returns near the deadline instead of long after it.
+            poll: (cursor) => client.pollEvents({
+                since: cursor,
+                wait: deadlineMs
+                    ? Math.max(1, Math.ceil((deadlineMs - Date.now()) / 1000))
+                    : undefined,
+                signal: inFlight.signal,
+            }),
+            warn: (t) => process.stderr.write(`${colors.dim}${t}${colors.reset}\n`),
+            sleep,
+        }, { askId: created.askId, since, deadlineMs, stopped: () => stop });
+        if (result.outcome === "answered") {
+            const answer = result.chosenOption ?? result.resolution;
+            if (args.json) {
+                console.log(JSON.stringify({
+                    askId: created.askId,
+                    state: "resolved",
+                    chosenOption: result.chosenOption ?? null,
+                    resolution: result.resolution ?? null,
+                }));
+            }
+            else {
+                console.log(`${colors.green}✓${colors.reset} Answered${answer ? `: ${answer}` : ""}`);
+            }
+        }
+        else if (result.outcome === "timeout") {
+            if (args.json) {
+                console.log(JSON.stringify({ askId: created.askId, state: "open", timedOut: true }));
+            }
+            else {
+                process.stderr.write(`${colors.dim}no answer within ${args.wait}s — the ask stays open${colors.reset}\n`);
+            }
+            // A script waiting on an answer needs to branch on not getting one.
+            process.exitCode = 1;
+        }
+        // stopped (^C): say nothing — the ask stays open and the app still has it.
+    }
+    finally {
+        process.off("SIGINT", onSignal);
+        process.off("SIGTERM", onSignal);
+    }
+}
 /**
  * A shared command's result, on the real streams.
  *

package/dist/index.d.ts

@@ -69,3 +69,5 @@ export { blocksCommand, putCommand, urlCommand, resolveFsPath, presenceNotice, t
 export { sforaShellCommands, parseShellArgs } from "./shell-commands.js";
 export { watchLoop, parseWatchTarget, MAX_BACKOFF_MS, type WatchDeps, type WatchOptions, type WatchTarget, } from "./watch.js";
 export { renderPing, renderBlocks, renderBlockConflict, renderWriteEffect, ndjson, type DocPing, } from "./render.js";
+export { KNOWN_CLIENTS, detectClient, sanitizeClientSlug } from "./chat.js";
+export { validateAskOptions, reshapeCandidatesError, askWaitLoop, ASK_OPTIONS_MIN, ASK_OPTIONS_MAX, ASK_OPTION_MAX_LENGTH, type AskWaitDeps, type AskWaitOptions, type AskWaitResult, } from "./ask.js";

package/dist/index.js

@@ -57,3 +57,5 @@ export { blocksCommand, putCommand, urlCommand, resolveFsPath, presenceNotice, }
 export { sforaShellCommands, parseShellArgs } from "./shell-commands.js";
 export { watchLoop, parseWatchTarget, MAX_BACKOFF_MS, } from "./watch.js";
 export { renderPing, renderBlocks, renderBlockConflict, renderWriteEffect, ndjson, } from "./render.js";
+export { KNOWN_CLIENTS, detectClient, sanitizeClientSlug } from "./chat.js";
+export { validateAskOptions, reshapeCandidatesError, askWaitLoop, ASK_OPTIONS_MIN, ASK_OPTIONS_MAX, ASK_OPTION_MAX_LENGTH, } from "./ask.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sfora-cli",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "type": "module",
   "description": "Your sfora workspace as a markdown filesystem — a CLI + MCP server. Post/task/doc, ls/cat/grep, and a shell so agents operate sfora natively.",
   "keywords": [