sfora-cli 0.13.0 → 0.14.0

package/dist/api-client.d.ts

@@ -260,6 +260,12 @@ export interface ChatMessage {
     _creationTime: number;
     /** Null when the author's member row is gone. */
     author: ChatAuthor | null;
+    /**
+     * The client slug the message was sent through ("claude-code"), when the
+     * sending door stamped one. Absent on app sends and on servers that do not
+     * surface it yet.
+     */
+    sentVia?: string;
 }
 /** A page of messages, NEWEST FIRST — the server paginates backwards. */
 export interface MessagesPage {
@@ -297,6 +303,14 @@ export interface SforaApiConfig {
      * key per agent.
      */
     actAs?: string;
+    /**
+     * What kind of client is on the line — a short slug ("claude-code", "cli").
+     * Sent as `X-Sfora-Client` on every request so creation doors can stamp the
+     * things they make ("sent via Claude Code" on a message or post). Sent
+     * always, including the plain "cli" — a terminal is honest attribution too.
+     * The server sanitizes it and ignores it where it means nothing.
+     */
+    clientLabel?: string;
 }
 /** Non-2xx response from the fs API. Carries the HTTP status + machine code so SforaFs can map it to an errno. */
 export declare class SforaApiError extends Error {
@@ -550,6 +564,12 @@ export declare class SforaApiClient {
         doc?: string;
         project?: string;
         includeSelf?: boolean;
+        /**
+         * Deliver message events for the caller's OWN messages too — how a tail
+         * hears the same member speaking from the app. Distinct from
+         * `includeSelf`, which is about document writes.
+         */
+        includeOwn?: boolean;
         signal?: AbortSignal;
     }): Promise<AgentEventsPage>;
     /**
@@ -573,7 +593,9 @@ export declare class SforaApiClient {
     /** `GET /api/rooms/:id/messages` — history, newest first (server cap: 100). */
     listRoomMessages(roomId: string, limit?: number): Promise<MessagesPage>;
     /** `POST /api/rooms/:id/messages` with `{ body }` — send markdown. */
-    sendRoomMessage(roomId: string, body: string): Promise<{
+    sendRoomMessage(roomId: string, body: string, 
+    /** Terminal client slug — stamped on the message ("sent via Claude Code"). */
+    client?: string): Promise<{
         messageId: string;
     }>;
     /**

package/dist/api-client.js

@@ -89,6 +89,7 @@ export class SforaApiClient {
     #baseUrl;
     #apiKey;
     #actAs;
+    #clientLabel;
     /**
      * What the LAST response said about itself, beyond the data it carried.
      *
@@ -108,6 +109,7 @@ export class SforaApiClient {
         this.#baseUrl = config.baseUrl.replace(/\/+$/, "");
         this.#apiKey = config.apiKey;
         this.#actAs = config.actAs;
+        this.#clientLabel = config.clientLabel;
     }
     /** What the last response said about itself, consumed. */
     takeResponseInfo() {
@@ -148,6 +150,8 @@ export class SforaApiClient {
         headers.Authorization = `Bearer ${this.#apiKey}`;
         if (this.#actAs)
             headers["X-Sfora-Act-As"] = this.#actAs;
+        if (this.#clientLabel)
+            headers["X-Sfora-Client"] = this.#clientLabel;
         if (body !== undefined)
             headers["Content-Type"] = contentType;
         let res;
@@ -445,16 +449,7 @@ export class SforaApiClient {
         const slug = encodeURIComponent(projectSlug);
         // The server slugifies `name` to derive the directory; we send it as a
         // single-field JSON body to keep the spec consistent with future fields.
-        const res = await fetch(`${this.#baseUrl}/v1/fs/projects/${slug}/board`, {
-            method: "POST",
-            headers: {
-                Authorization: `Bearer ${this.#apiKey}`,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify({ name }),
-        });
-        if (!res.ok)
-            throw await this.#toError(res);
+        const res = await this.#request("POST", `/v1/fs/projects/${slug}/board`, JSON.stringify({ name }), undefined, "application/json");
         return await this.#jsonFrom(res);
     }
     /**
@@ -464,16 +459,7 @@ export class SforaApiClient {
     async renameColumn(projectSlug, columnDir, newName) {
         const slug = encodeURIComponent(projectSlug);
         const col = encodeURIComponent(columnDir);
-        const res = await fetch(`${this.#baseUrl}/v1/fs/projects/${slug}/board/${col}/_rename`, {
-            method: "POST",
-            headers: {
-                Authorization: `Bearer ${this.#apiKey}`,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify({ name: newName }),
-        });
-        if (!res.ok)
-            throw await this.#toError(res);
+        const res = await this.#request("POST", `/v1/fs/projects/${slug}/board/${col}/_rename`, JSON.stringify({ name: newName }), undefined, "application/json");
         return await this.#jsonFrom(res);
     }
     /** `DELETE …/board/:column` — column must be empty. */
@@ -490,31 +476,13 @@ export class SforaApiClient {
         const slug = encodeURIComponent(projectSlug);
         const from = encodeURIComponent(fromCol);
         const file = encodeURIComponent(filename);
-        const res = await fetch(`${this.#baseUrl}/v1/fs/projects/${slug}/board/${from}/${file}/_move`, {
-            method: "POST",
-            headers: {
-                Authorization: `Bearer ${this.#apiKey}`,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify({ toColumn: toCol }),
-        });
-        if (!res.ok)
-            throw await this.#toError(res);
+        const res = await this.#request("POST", `/v1/fs/projects/${slug}/board/${from}/${file}/_move`, JSON.stringify({ toColumn: toCol }), undefined, "application/json");
         return await this.#jsonFrom(res);
     }
     // ─── Post actions (comment / react) ─────────────────────────────
     /** `POST /v1/posts/:postId/comments` — add a comment to a post. */
     async createComment(postId, body) {
-        const res = await fetch(`${this.#baseUrl}/v1/posts/${encodeURIComponent(postId)}/comments`, {
-            method: "POST",
-            headers: {
-                Authorization: `Bearer ${this.#apiKey}`,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify({ body }),
-        });
-        if (!res.ok)
-            throw await this.#toError(res);
+        const res = await this.#request("POST", `/v1/posts/${encodeURIComponent(postId)}/comments`, JSON.stringify({ body }), undefined, "application/json");
         const data = await this.#jsonFrom(res);
         return { id: data.comment?._id ?? "" };
     }
@@ -523,16 +491,7 @@ export class SforaApiClient {
      * Returns whether the reaction is now on (`reacted: true`) or off.
      */
     async reactToPost(postId, emoji) {
-        const res = await fetch(`${this.#baseUrl}/v1/posts/${encodeURIComponent(postId)}/reactions`, {
-            method: "POST",
-            headers: {
-                Authorization: `Bearer ${this.#apiKey}`,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify({ emoji }),
-        });
-        if (!res.ok)
-            throw await this.#toError(res);
+        const res = await this.#request("POST", `/v1/posts/${encodeURIComponent(postId)}/reactions`, JSON.stringify({ emoji }), undefined, "application/json");
         const data = await this.#jsonFrom(res);
         return data.reaction ?? { content: emoji, reacted: true };
     }
@@ -600,6 +559,9 @@ export class SforaApiClient {
         // own writes, matching the message branch's "don't wake on your own".
         if (params.includeSelf)
             query.set("self", "include");
+        // `?includeOwn=1` — exactly "1", the server's spelling.
+        if (params.includeOwn)
+            query.set("includeOwn", "1");
         return this.#json(`/v1/events?${query.toString()}`, params.signal);
     }
     /**
@@ -631,10 +593,12 @@ export class SforaApiClient {
         return this.#json(`/api/rooms/${encodeURIComponent(roomId)}/messages?limit=${limit}`);
     }
     /** `POST /api/rooms/:id/messages` with `{ body }` — send markdown. */
-    async sendRoomMessage(roomId, body) {
+    async sendRoomMessage(roomId, body, 
+    /** Terminal client slug — stamped on the message ("sent via Claude Code"). */
+    client) {
         // Through #request like every other call, so network failures surface as
         // SforaApiError(0, "network_error") and `--as` rides the shared headers.
-        const res = await this.#request("POST", `/api/rooms/${encodeURIComponent(roomId)}/messages`, JSON.stringify({ body }), undefined, "application/json");
+        const res = await this.#request("POST", `/api/rooms/${encodeURIComponent(roomId)}/messages`, JSON.stringify({ body, client }), undefined, "application/json");
         return this.#jsonFrom(res);
     }
     /**

package/dist/chat.d.ts

@@ -82,6 +82,14 @@ export declare function renderChatBody(markdown: string): string;
  * context, not content.
  */
 export declare function renderChatMessage(msg: ChatMessage, now: number): string;
+/**
+ * One message as an NDJSON line — the machine half of `chat --follow --json`
+ * and `--await-reply --json`. A small, stable shape rather than the wire row:
+ * `{ author, body, at, sentVia? }`, `at` in ISO 8601. `sentVia` appears only
+ * when the sending door stamped one; the author's name is passed through raw —
+ * capitalization is a display rule, and this line is for a program.
+ */
+export declare function chatMessageJson(msg: ChatMessage): string;
 /** `sfora rooms` — one row per room; unjoined rows carry their join hint. */
 export declare function renderRoomList(rooms: Room[]): string;
 /** Everything the tail loop needs from the outside world. */
@@ -114,3 +122,50 @@ export interface ChatTailOptions {
  * `seen` set is the single ledger, shared with the prompt's own sends.
  */
 export declare function chatTailLoop(deps: ChatTailDeps, options: ChatTailOptions): Promise<number>;
+/** Everything the reply wait needs from the outside world. */
+export interface AwaitReplyDeps {
+    /**
+     * One `/v1/events` long-poll — the caller's poll passes `includeOwn`, so
+     * the same member answering from the app rings the doorbell too.
+     */
+    poll(since: number): Promise<AgentEventsPage>;
+    /** The room's recent page, any order — refetched when the doorbell rings. */
+    fetchRecent(): Promise<ChatMessage[]>;
+    /** 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 AwaitReplyOptions {
+    roomId: string;
+    /**
+     * Message ids that are NOT the reply: the history before the send, and the
+     * send itself. The reply is picked by id, not author — the same human
+     * answering from the app IS the reply.
+     */
+    seen: Set<string>;
+    /** Events cursor to start from — BEFORE the send, on server time. */
+    since: number;
+    /** Absolute deadline (ms epoch); absent means wait forever. */
+    deadlineMs?: number;
+    stopped?: () => boolean;
+    backoffMs?: number;
+}
+export type AwaitReplyResult = {
+    outcome: "reply";
+    message: ChatMessage;
+} | {
+    outcome: "timeout";
+} | {
+    outcome: "stopped";
+};
+/**
+ * Poll until the room speaks back, the deadline passes, or the caller stops.
+ *
+ * The same rules the tail holds — forward-only cursor, doubling backoff to
+ * {@link MAX_BACKOFF_MS}, the doorbell-then-refetch shape — but instead of
+ * printing forever, the FIRST unseen message ends the wait. Oldest wins when
+ * several land at once: the reply is the next thing said, not the latest.
+ */
+export declare function awaitReplyLoop(deps: AwaitReplyDeps, options: AwaitReplyOptions): Promise<AwaitReplyResult>;

package/dist/chat.js

@@ -199,6 +199,21 @@ export function renderChatMessage(msg, now) {
     const header = `${colors.bold}${author}${colors.reset}  ${dim(relativeTime(msg._creationTime, now))}`;
     return `${header}\n${renderChatBody(msg.body)}`;
 }
+/**
+ * One message as an NDJSON line — the machine half of `chat --follow --json`
+ * and `--await-reply --json`. A small, stable shape rather than the wire row:
+ * `{ author, body, at, sentVia? }`, `at` in ISO 8601. `sentVia` appears only
+ * when the sending door stamped one; the author's name is passed through raw —
+ * capitalization is a display rule, and this line is for a program.
+ */
+export function chatMessageJson(msg) {
+    return JSON.stringify({
+        author: msg.author?.name ?? null,
+        body: msg.body,
+        at: new Date(msg._creationTime).toISOString(),
+        ...(msg.sentVia ? { sentVia: msg.sentVia } : {}),
+    });
+}
 /** `sfora rooms` — one row per room; unjoined rows carry their join hint. */
 export function renderRoomList(rooms) {
     if (rooms.length === 0)
@@ -266,3 +281,63 @@ export async function chatTailLoop(deps, options) {
     }
     return cursor;
 }
+/**
+ * Poll until the room speaks back, the deadline passes, or the caller stops.
+ *
+ * The same rules the tail holds — forward-only cursor, doubling backoff to
+ * {@link MAX_BACKOFF_MS}, the doorbell-then-refetch shape — but instead of
+ * printing forever, the FIRST unseen message ends the wait. Oldest wins when
+ * several land at once: the reply is the next thing said, not the latest.
+ */
+export async function awaitReplyLoop(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;
+        const rang = page.events.some((e) => e.type === "message" && e.roomId === options.roomId);
+        if (rang) {
+            let recent;
+            try {
+                recent = await deps.fetchRecent();
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                deps.warn(`could not fetch new messages — ${message}`);
+                // The doorbell rang and the refetch failed: do NOT advance the
+                // cursor, or the reply's event is consumed and the wait can hang
+                // forever if nothing else is ever said (reviewer MAJOR). Back off
+                // briefly and let the next poll re-deliver the same event.
+                await deps.sleep(backoff);
+                backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+                continue;
+            }
+            const fresh = recent
+                .filter((m) => !options.seen.has(m._id))
+                .sort((a, b) => a._creationTime - b._creationTime);
+            if (fresh.length > 0)
+                return { outcome: "reply", message: fresh[0] };
+        }
+        // Never backwards: an empty page holds the cursor where it was.
+        cursor = Math.max(cursor, page.cursor);
+    }
+    return { outcome: "stopped" };
+}

package/dist/cli-args.d.ts

@@ -29,6 +29,9 @@ export interface CliArgs {
     waitFlag: boolean;
     message?: string;
     limit?: number;
+    follow: boolean;
+    awaitReply: boolean;
+    timeout?: number;
     client?: string;
     option: string[];
     target?: string;

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, waitFlag: false, option: [] };
+    const args = { rest: [], cwd: "/", mcp: false, help: false, draft: false, json: false, local: false, cloud: false, self: false, waitFlag: false, follow: false, awaitReply: false, option: [] };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === "--mcp")
@@ -89,6 +89,14 @@ 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 === "--follow")
+            args.follow = true;
+        else if (a === "--await-reply")
+            args.awaitReply = true;
+        else if (a === "--timeout")
+            args.timeout = Number.parseInt(argv[++i] ?? "", 10);
+        else if (a.startsWith("--timeout="))
+            args.timeout = Number.parseInt(a.slice("--timeout=".length), 10);
         else if (a === "--client")
             args.client = argv[++i];
         else if (a.startsWith("--client="))

package/dist/cli.js

@@ -21,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 { capitalizeName, chatTailLoop, detectClient, renderChatMessage, renderRoomList, resolveRoomRef, roomSlug, } from "./chat.js";
+import { awaitReplyLoop, capitalizeName, chatMessageJson, chatTailLoop, detectClient, renderChatMessage, renderRoomList, resolveRoomRef, roomSlug, } from "./chat.js";
 const HELP = `sfora — the CLI for your sfora workspace
 
 Get started (no account needed):
@@ -69,10 +69,18 @@ Chat:
                                       new messages stream in live
   sfora chat <room> -m "text"         Send one message and exit (for scripts
                                       and agents)
+  sfora chat <room> --follow          Tail the room without a prompt — for
+                                      logs and pipes (--json for NDJSON)
+  sfora chat <room> -m "text" --await-reply
+                                      Send, then wait for the next message
+                                      back and print it — --timeout <secs>
+                                      stops waiting (exit code 2)
 
   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.
+  Everything the CLI creates — messages, posts, tasks, docs — carries the
+  same name, so the feed says what sent it.
 
 Ask a human:
   sfora ask "<question>" --option "A" --option "B"
@@ -178,6 +186,16 @@ async function runInit(args) {
     console.log(`${colors.green}✓${colors.reset} Saved ${path} ${colors.dim}(${profile})${colors.reset}`);
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** A backoff sleep that a stop check can cut short: sliced into 250ms
+ *  intervals so ^C during a 30s reconnect backoff exits promptly instead of
+ *  waiting the sleep out (reviewer catch — --follow/--await-reply are
+ *  unattended surfaces where a hung shutdown means a hung supervisor). */
+const stoppableSleep = (stopped) => async (ms) => {
+    const until = Date.now() + ms;
+    while (Date.now() < until && !stopped()) {
+        await sleep(Math.min(250, until - Date.now()));
+    }
+};
 function openBrowser(url) {
     const { command, args } = openerCommand(process.platform, url);
     try {
@@ -539,7 +557,7 @@ async function runVerb(args, fs, client) {
     }
     if (args.command === "chat") {
         if (!args.rest[0]) {
-            throw new Error('usage: sfora chat <room> [-n <count>] [-m "text"]');
+            throw new Error('usage: sfora chat <room> [-n <count>] [-m "text"] [--follow] [--await-reply]');
         }
         return runChat(args, client);
     }
@@ -767,7 +785,7 @@ async function runWatch(args, client, target) {
             write: (text) => process.stdout.write(text),
             // Warnings on stderr so `--json` stdout stays parseable NDJSON.
             warn: (text) => process.stderr.write(`${colors.dim}${text}${colors.reset}\n`),
-            sleep,
+            sleep: stoppableSleep(() => stop),
         }, { json: args.json, since, stopped: () => stop });
     }
     finally {
@@ -829,14 +847,17 @@ async function runChat(args, client) {
     // 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.
+    // One-shot send — with --await-reply, the wait for what comes back.
     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.awaitReply) {
+            return runSendAwaitReply(args, client, room, tag, text, clientLabel);
+        }
+        const { messageId } = await client.sendRoomMessage(room._id, text, clientLabel);
         if (args.json) {
             console.log(JSON.stringify({ messageId, roomId: room._id }, null, 2));
             return;
@@ -844,6 +865,12 @@ async function runChat(args, client) {
         console.log(`${colors.green}✓${colors.reset} Sent to ${tag}`);
         return;
     }
+    if (args.awaitReply) {
+        throw new Error('usage: sfora chat <room> -m "text" --await-reply [--timeout <secs>] — the reply needs a message to reply to');
+    }
+    // The tail without the prompt — for logs, pipes, and agents.
+    if (args.follow)
+        return runChatFollow(args, client, room, tag, clientLabel);
     // History, oldest first — the page arrives newest-first.
     const limit = Number.isFinite(args.limit) && args.limit > 0
         ? Math.min(args.limit, 100)
@@ -854,6 +881,7 @@ async function runChat(args, client) {
     const history = await client.listRoomMessages(room._id, Math.max(limit, 20));
     const seeded = history.page.slice().reverse();
     const seen = new Set(seeded.map((m) => m._id));
+    const pendingSendBodies = new Set();
     const messages = seeded.slice(-limit);
     if (messages.length === 0) {
         console.log(`${colors.dim}(no messages yet)${colors.reset}`);
@@ -899,11 +927,27 @@ async function runChat(args, client) {
     });
     const wait = Number.isFinite(args.wait) ? args.wait : undefined;
     const tail = chatTailLoop({
-        poll: (since) => client.pollEvents({ since, wait, signal: inFlight.signal }),
+        // `includeOwn`: your own app sends ring the doorbell too, so talking in
+        // the web while sitting here shows both halves of the conversation. The
+        // seen set already keeps the CLI's own sends from printing twice.
+        poll: (since) => client.pollEvents({
+            since,
+            wait,
+            includeOwn: true,
+            signal: inFlight.signal,
+        }),
         fetchRecent: async () => (await client.listRoomMessages(room._id, 20)).page,
-        print: (msg) => printAbove(renderChatMessage(msg, Date.now())),
+        // With includeOwn on, a send's event can race its own HTTP response:
+        // the tail may refetch before `seen.add(messageId)` runs. Bodies in
+        // flight are suppressed for that window (the typed line on screen is
+        // the echo); the id joins `seen` when the send resolves.
+        print: (msg) => {
+            if (pendingSendBodies.has(msg.body))
+                return;
+            printAbove(renderChatMessage(msg, Date.now()));
+        },
         warn: (text) => printAbove(`${colors.dim}${text}${colors.reset}`),
-        sleep,
+        sleep: stoppableSleep(() => stop),
     }, {
         roomId: room._id,
         seen,
@@ -924,16 +968,20 @@ async function runChat(args, client) {
         }
         if (line === "/quit" || line === "/exit" || line === "/q")
             break;
+        pendingSendBodies.add(line);
         try {
             // The send's own echo is the typed line still on screen; recording the
             // id keeps the tail's refetch from printing it a second time.
-            const { messageId } = await client.sendRoomMessage(room._id, line);
+            const { messageId } = await client.sendRoomMessage(room._id, line, clientLabel);
             seen.add(messageId);
         }
         catch (e) {
             const msg = e instanceof Error ? e.message : String(e);
             process.stderr.write(`${colors.red}error:${colors.reset} ${msg}\n`);
         }
+        finally {
+            pendingSendBodies.delete(line);
+        }
         if (isTty)
             rl.prompt();
     }
@@ -948,6 +996,165 @@ async function runChat(args, client) {
     if (isTty)
         console.log("");
 }
+/**
+ * `sfora chat <room> --follow` — the tail without the prompt.
+ *
+ * For logs, pipes, and agents: history first (respecting `-n`), then new
+ * messages as they arrive — no prompt, no TTY needed. The poll asks for the
+ * caller's OWN messages too (`includeOwn`), so the same person talking from
+ * the app appears here; nothing prints twice, the seen set is the ledger.
+ * `--json` emits one NDJSON object per message. ^C exits cleanly.
+ */
+async function runChatFollow(args, client, room, tag, clientLabel) {
+    const emit = (msg) => console.log(args.json ? chatMessageJson(msg) : renderChatMessage(msg, Date.now()));
+    // History, oldest first — seeded wide enough that the doorbell's refetch
+    // (20) never "discovers" older history, printed only as far as -n asked.
+    const limit = Number.isFinite(args.limit) && args.limit > 0
+        ? Math.min(args.limit, 100)
+        : 30;
+    const history = await client.listRoomMessages(room._id, Math.max(limit, 20));
+    const seeded = history.page.slice().reverse();
+    const seen = new Set(seeded.map((m) => m._id));
+    for (const msg of seeded.slice(-limit))
+        emit(msg);
+    process.stderr.write(`${colors.dim}following ${tag} — ^C to stop${colors.reset}\n`);
+    // Following is being in the room: beat now, then every ~45s, same as the
+    // interactive chat. `unref` so the timer never holds the process open.
+    const beat = () => client.heartbeat({ roomId: room._id, client: clientLabel }).catch(() => { });
+    void beat();
+    const pulse = setInterval(() => void beat(), 45_000);
+    pulse.unref?.();
+    // ^C has to reach the socket — the long-poll hangs for tens of seconds.
+    // Second ^C stands down and lets the default behaviour end things.
+    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);
+    const wait = Number.isFinite(args.wait) ? args.wait : undefined;
+    try {
+        await chatTailLoop({
+            poll: (since) => client.pollEvents({
+                since,
+                wait,
+                includeOwn: true,
+                signal: inFlight.signal,
+            }),
+            fetchRecent: async () => (await client.listRoomMessages(room._id, 20)).page,
+            print: emit,
+            warn: (t) => process.stderr.write(`${colors.dim}${t}${colors.reset}\n`),
+            sleep: stoppableSleep(() => stop),
+        }, {
+            roomId: room._id,
+            seen,
+            // Cursor on SERVER time — see the interactive tail.
+            since: history.page[0]?._creationTime ?? Date.now(),
+            stopped: () => stop,
+        });
+    }
+    finally {
+        clearInterval(pulse);
+        process.off("SIGINT", onSignal);
+        process.off("SIGTERM", onSignal);
+    }
+    // A parting beat, best-effort — awaited so exit doesn't race it.
+    await beat();
+}
+/**
+ * `sfora chat <room> -m "…" --await-reply` — send, then hold the line.
+ *
+ * Blocks until the NEXT message that is not the send itself lands in the
+ * room, prints it, and exits 0 — the reply is picked by message id, not
+ * author, so the same human answering from the app counts. `--timeout <secs>`
+ * gives up with exit code 2. Everything already said before the send is
+ * seeded as seen, so an old message can never pose as the answer.
+ */
+async function runSendAwaitReply(args, client, room, tag, text, clientLabel) {
+    // Seed BEFORE the send: the history is not the reply, and the events cursor
+    // is server time, so a fast local clock opens no blind window.
+    const history = await client.listRoomMessages(room._id, 50);
+    const seen = new Set(history.page.map((m) => m._id));
+    const since = history.page[0]?._creationTime ?? Date.now();
+    // A mistyped --timeout must fail loudly, not silently wait forever — the
+    // exact opposite of what the flag asked for (reviewer catch).
+    if (args.timeout !== undefined && (!Number.isFinite(args.timeout) || args.timeout <= 0)) {
+        throw new Error("--timeout needs a positive number of seconds");
+    }
+    const { messageId } = await client.sendRoomMessage(room._id, text, clientLabel);
+    seen.add(messageId);
+    const deadlineMs = args.timeout !== undefined ? Date.now() + args.timeout * 1000 : undefined;
+    if (args.json) {
+        // NDJSON-shaped: this line says it landed; the reply is the next line.
+        console.log(JSON.stringify({ messageId, roomId: room._id }));
+    }
+    else {
+        console.log(`${colors.green}✓${colors.reset} Sent to ${tag}`);
+        process.stderr.write(`${colors.dim}waiting for a reply${deadlineMs ? ` (up to ${args.timeout}s)` : ""} — ^C to stop${colors.reset}\n`);
+    }
+    // Same signal shape as `ask --wait`: ^C reaches the socket, second ^C
+    // stands down and lets the default behaviour end things.
+    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);
+    try {
+        const result = await awaitReplyLoop({
+            // `includeOwn`: the same member answering from the app must ring the
+            // doorbell — the reply filter is by message id, not author. With a
+            // deadline, each poll's server-side budget is capped to what is left.
+            poll: (cursor) => client.pollEvents({
+                since: cursor,
+                wait: deadlineMs
+                    ? Math.max(1, Math.ceil((deadlineMs - Date.now()) / 1000))
+                    : undefined,
+                includeOwn: true,
+                signal: inFlight.signal,
+            }),
+            fetchRecent: async () => (await client.listRoomMessages(room._id, 20)).page,
+            warn: (t) => process.stderr.write(`${colors.dim}${t}${colors.reset}\n`),
+            sleep: stoppableSleep(() => stop),
+        }, { roomId: room._id, seen, since, deadlineMs, stopped: () => stop });
+        if (result.outcome === "reply") {
+            console.log(args.json
+                ? chatMessageJson(result.message)
+                : renderChatMessage(result.message, Date.now()));
+        }
+        else if (result.outcome === "timeout") {
+            process.stderr.write(`${colors.dim}no reply within ${args.timeout}s${colors.reset}\n`);
+            // 2, not 1: "nobody answered" is its own branch for a script — distinct
+            // from "the send failed", which throws and exits 1.
+            process.exitCode = 2;
+        }
+        // stopped (^C): say nothing — the message is sent and stands.
+    }
+    finally {
+        process.off("SIGINT", onSignal);
+        process.off("SIGTERM", onSignal);
+    }
+}
 /**
  * `sfora ask` — how an agent asks a human, wired to the real process.
  *
@@ -1063,7 +1270,7 @@ async function runAsk(args, client) {
                 signal: inFlight.signal,
             }),
             warn: (t) => process.stderr.write(`${colors.dim}${t}${colors.reset}\n`),
-            sleep,
+            sleep: stoppableSleep(() => stop),
         }, { askId: created.askId, since, deadlineMs, stopped: () => stop });
         if (result.outcome === "answered") {
             const answer = result.chosenOption ?? result.resolution;
@@ -1304,6 +1511,12 @@ async function main() {
     const cfg = await readConfig();
     const settings = resolveSettings({ url: args.url, apiKey: args.key, org: args.org, bot: args.bot }, cfg);
     const { url: baseUrl, apiKey } = settings;
+    // Once per invocation: what kind of client is on the line. The api client
+    // sends it on every request (`X-Sfora-Client`), so every creation door
+    // stamps its work — a post made from Claude Code says so on the feed, the
+    // same way a chat message does. Sent always, "cli" included: a plain
+    // terminal is honest attribution too.
+    const clientLabel = detectClient(process.env, args.client);
     if (args.command === "mcp-config") {
         printMcpConfig(settings);
         return;
@@ -1344,6 +1557,7 @@ async function main() {
                 apiKey: apiKey ?? "",
                 org: settings.org ?? "",
                 localRoot,
+                clientLabel,
             });
             return;
         }
@@ -1372,6 +1586,7 @@ async function main() {
             apiKey,
             org: settings.org ?? "",
             actAs: args.as,
+            clientLabel,
             presence: runPresence,
         });
         try {
@@ -1392,7 +1607,7 @@ async function main() {
     }
     // MCP mode: stdout is the protocol channel — never write logs there.
     if (args.mcp) {
-        await runMcpServer({ baseUrl, apiKey, org: settings.org ?? "" });
+        await runMcpServer({ baseUrl, apiKey, org: settings.org ?? "", clientLabel });
         return;
     }
     if (!settings.org) {
@@ -1406,6 +1621,7 @@ async function main() {
         apiKey,
         org,
         cwd: args.cwd,
+        clientLabel,
         presence: runPresence,
     });
     // Pre-flight: confirm auth + connectivity and greet with the resolved identity.

package/dist/index.d.ts

@@ -25,6 +25,12 @@ export interface CreateSforaShellOptions {
     cwd?: string;
     /** Act/post as an owned agent, using this key (sent as `X-Sfora-Act-As`). */
     actAs?: string;
+    /**
+     * What kind of client is on the line ("claude-code", "cli"). Sent as
+     * `X-Sfora-Client` on every request so writes are stamped with the terminal
+     * that made them — the CLI passes `detectClient(process.env, --client)`.
+     */
+    clientLabel?: string;
     /**
      * The run's "you are visible" latch. Pass one when something OUTSIDE this
      * shell can print the note too — the CLI does, after any line that wrote —
@@ -69,5 +75,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 { KNOWN_CLIENTS, detectClient, sanitizeClientSlug, chatMessageJson, chatTailLoop, awaitReplyLoop, type ChatTailDeps, type ChatTailOptions, type AwaitReplyDeps, type AwaitReplyOptions, type AwaitReplyResult, } 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

@@ -17,6 +17,7 @@ export function createSforaShell(options) {
         baseUrl: options.baseUrl,
         apiKey: options.apiKey,
         actAs: options.actAs,
+        clientLabel: options.clientLabel,
     });
     const presence = options.presence ?? presenceNotice();
     const fs = new SforaFs(client);
@@ -57,5 +58,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 { KNOWN_CLIENTS, detectClient, sanitizeClientSlug, chatMessageJson, chatTailLoop, awaitReplyLoop, } from "./chat.js";
 export { validateAskOptions, reshapeCandidatesError, askWaitLoop, ASK_OPTIONS_MIN, ASK_OPTIONS_MAX, ASK_OPTION_MAX_LENGTH, } from "./ask.js";

package/dist/mcp-server.d.ts

@@ -12,5 +12,7 @@ export interface RunMcpServerOptions {
     org: string;
     /** Absolute path of a local `.sfora/` workspace — serves it instead of the cloud. */
     localRoot?: string;
+    /** Terminal client slug for write attribution (`X-Sfora-Client`). */
+    clientLabel?: string;
 }
 export declare function runMcpServer(options: RunMcpServerOptions): Promise<void>;

package/dist/mcp-server.js

@@ -39,6 +39,7 @@ export async function runMcpServer(options) {
             baseUrl: options.baseUrl,
             apiKey: options.apiKey,
             org: options.org,
+            clientLabel: options.clientLabel,
         });
     // Persistent shell state across tool calls.
     let cwd = "/";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sfora-cli",
-  "version": "0.13.0",
+  "version": "0.14.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": [