sfora-cli 0.13.1 → 0.15.0

package/README.md

@@ -399,3 +399,70 @@ print nothing, and `sfora url` on one says so.
 Reads outside `projects/<slug>/(posts|drafts)`, `inbox/mentions.md`, and
 `me/api-key` return `ENOENT`; writes outside the post/draft dirs return `EACCES`.
 ```
+
+## macOS and shared local operations
+
+The desktop app and npm CLI use the same Node-only `sfora-cli/local-core`
+operations. `sfora desktop path/to/file.md` opens a local file in the installed
+Sfora macOS app. `sfora open` continues to open Sfora web URLs. npm installation
+still requires Node 20+; the desktop distribution bundles its own CLI runtime.
+Both read the existing `~/.sfora/config.json` profiles. Config writes are atomic
+and process-locked; no account is required for local files or local skill scans.
+
+Local Markdown snapshots contain the canonical `path`, unmodified UTF-8
+`content`, and SHA-256 `revision`. Saving requires the loaded revision; Save As
+refuses existing destinations. BOM and line endings are preserved. A stale
+revision reports a conflict instead of overwriting an external edit. Locks
+coordinate Sfora processes; other editors do not participate in those locks.
+A crashed process may leave a `.sfora-lock` directory: the error identifies it
+for removal after confirming no process is using it.
+
+## Project skills
+
+Skills are complete recursive bundles: `SKILL.md`, scripts, references, and
+binary assets retain exact bytes and executable flags. Import/install never
+executes skill scripts. Symbolic links, traversal, duplicate case-insensitive
+paths, invalid hashes and oversized bundles are rejected (1,000 files,
+5 MiB/file, 20 MiB total).
+
+```sh
+sfora skills scan ~/.agents/skills ~/.codex/skills --json
+sfora skills list --project my-project
+sfora skills push ./my-skill --project my-project --expected-version 0
+sfora skills pull my-skill ./my-skill.bundle.json --project my-project
+sfora skills install my-skill --project my-project --skills-target ~/.agents/skills
+sfora skills diff ~/.agents/skills/my-skill my-skill --project my-project
+sfora skills uninstall ~/.agents/skills/my-skill
+```
+
+Push uses an explicit base version (`0` creates a skill); updating an existing
+skill also requires its `--expected-revision` draft token from `skills list`.
+Saving the draft and publishing are separately checked operations, so a
+concurrent change cannot silently publish somebody else's draft. Use
+`--version N` to pull/install a particular immutable release. Offline bundle
+installation is `skills install-file bundle.json --skills-target <directory>`.
+
+Install targets are explicit. A sibling `.name.sfora-install.json` records
+ownership and last installed hash. Existing unowned folders are never replaced;
+updates and uninstalls refuse locally modified installations. Save or push
+those modifications before retrying. `skills pull` writes a new bundle JSON
+file and refuses to overwrite an existing file.
+
+Cloud document callers can use `SforaApiClient.readPathSnapshot()` and pass its
+revision to `writePath(..., { expectedRevision })`. CLI writes accept
+`put <path> <file.md> --expected-revision N`. A null read revision means the
+server did not advertise concurrency support; clients must not infer a token.
+
+Published Skills are also mounted read-only in the ordinary filesystem view:
+
+```sh
+sfora ls /projects/my-project/skills
+sfora ls /projects/my-project/skills/my-skill/scripts
+sfora cat /projects/my-project/skills/my-skill/SKILL.md
+```
+
+Nested directories, binary reads and executable metadata are preserved. Draft
+changes appear here only after publication; use `skills push` or the project
+workbench to change a bundle. Cloud installations record both the immutable
+bundle hash and numeric `sourceVersion`; resolving “latest” pins that version
+before downloading so concurrent publications cannot mix provenance and bytes.

package/dist/SforaFs.js

@@ -76,6 +76,8 @@ function classify(path) {
         if (seg.length === 2)
             return { kind: "projectDir", slug };
         const dir = seg[2];
+        if (dir === "skills")
+            return { kind: "skillPath", slug, name: seg[3], path: seg.slice(4).join("/") };
         if (dir === "links.md" && seg.length === 3) {
             return { kind: "linksFile", slug };
         }
@@ -560,7 +562,20 @@ export class SforaFs {
                 throw enoent("open", normalize(path));
         }
     }
+    async #skillManifest(slug, name) {
+        const manifest = await this.#client.readSkillManifest(slug, name);
+        const paths = new Set();
+        for (const file of manifest.files) {
+            const parts = file.path.split("/");
+            for (let count = 1; count <= parts.length; count++)
+                paths.add(parts.slice(0, count).join("/"));
+        }
+        this.#entrySnapshots.set(`/projects/${slug}/skills/${name}`, [...paths]);
+        return manifest;
+    }
     async readFile(path, options) {
+        if (classify(path).kind === "skillPath")
+            return Buffer.from(await this.readFileBuffer(path)).toString(toNodeEncoding(readEncoding(options)));
         const text = await this.#readText(path);
         const enc = readEncoding(options);
         if (enc === "utf8" || enc === "utf-8")
@@ -568,12 +583,25 @@ export class SforaFs {
         return Buffer.from(text, "utf8").toString(toNodeEncoding(enc));
     }
     async readFileBuffer(path) {
+        const loc = classify(path);
+        if (loc.kind === "skillPath") {
+            if ((await this.stat(path)).isDirectory)
+                throw eisdir("read", normalize(path));
+            try {
+                return await this.#client.readSkillFile(loc.slug, loc.name, loc.path);
+            }
+            catch (error) {
+                throw fromApi(error, "open", normalize(path));
+            }
+        }
         const text = await this.#readText(path);
         return new TextEncoder().encode(text);
     }
     async writeFile(path, content, _options) {
         const loc = classify(path);
         const norm = normalize(path);
+        if (loc.kind === "skillPath")
+            throw eacces("open", norm);
         if (loc.kind === "inboxFile" || loc.kind === "meFile") {
             throw eacces("open", norm);
         }
@@ -746,6 +774,21 @@ export class SforaFs {
         const norm = normalize(path);
         try {
             switch (loc.kind) {
+                case "skillPath": {
+                    if (!loc.name) {
+                        await this.#client.listSkillDirectories(loc.slug);
+                        return this.#dirStat();
+                    }
+                    const manifest = await this.#skillManifest(loc.slug, loc.name);
+                    if (!loc.path)
+                        return this.#dirStat();
+                    const file = manifest.files.find(file => file.path === loc.path);
+                    if (file)
+                        return { ...this.#fileStat(new Date(0), file.size), mode: file.executable ? 0o755 : FILE_MODE };
+                    if (manifest.files.some(file => file.path.startsWith(`${loc.path}/`)))
+                        return this.#dirStat();
+                    throw enoent("stat", norm);
+                }
                 case "root":
                 case "projectsDir":
                 case "inboxDir":
@@ -853,6 +896,27 @@ export class SforaFs {
         });
         try {
             switch (loc.kind) {
+                case "skillPath": {
+                    if (!loc.name) {
+                        const directories = (await this.#client.listSkillDirectories(loc.slug)).directories;
+                        this.#entrySnapshots.set(`/projects/${loc.slug}/skills`, directories.map(skill => skill.name));
+                        return directories.map(skill => dirent(skill.name, true));
+                    }
+                    const manifest = await this.#skillManifest(loc.slug, loc.name);
+                    if (manifest.files.some(file => file.path === loc.path))
+                        throw enotdir("scandir", norm);
+                    const prefix = loc.path ? `${loc.path}/` : "";
+                    const children = new Map();
+                    for (const file of manifest.files) {
+                        if (!file.path.startsWith(prefix))
+                            continue;
+                        const parts = file.path.slice(prefix.length).split("/");
+                        children.set(parts[0], parts.length > 1);
+                    }
+                    if (loc.path && !children.size)
+                        throw enoent("scandir", norm);
+                    return [...children].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([name, directory]) => dirent(name, directory));
+                }
                 case "root":
                     return [
                         dirent("inbox", true),
@@ -884,6 +948,7 @@ export class SforaFs {
                         dirent("map.md", false),
                         dirent("posts", true),
                         dirent("pulls", true),
+                        dirent("skills", true),
                     ];
                     // `public/` only appears once the board is shared publicly.
                     if ((await this.#publicSlug(loc.slug)) != null) {
@@ -998,6 +1063,7 @@ export class SforaFs {
         const loc = classify(path);
         const norm = normalize(path);
         switch (loc.kind) {
+            case "skillPath": throw eacces("mkdir", norm);
             // Known structural directories already exist — mkdir is a no-op.
             case "root":
             case "projectsDir":
@@ -1044,6 +1110,7 @@ export class SforaFs {
         const loc = classify(path);
         const norm = normalize(path);
         switch (loc.kind) {
+            case "skillPath": throw eacces("unlink", norm);
             case "postFile": {
                 const exists = (await this.#matchEntry(loc.slug, loc.dir, loc.filename)) !==
                     undefined;
@@ -1249,6 +1316,7 @@ export class SforaFs {
             paths.add(`/projects/${slug}/drafts`);
             paths.add(`/projects/${slug}/docs`);
             paths.add(`/projects/${slug}/artifacts`);
+            paths.add(`/projects/${slug}/skills`);
             paths.add(`/projects/${slug}/library`);
             paths.add(`/projects/${slug}/library/documents`);
             paths.add(`/projects/${slug}/library/files`);

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 {
@@ -375,6 +389,8 @@ export interface BlockConflict {
 export declare function blockConflictFrom(error: unknown): BlockConflict | null;
 /** Options every markdown write door takes. */
 export interface WriteOptions {
+    /** Whole-document revision from readPathSnapshot; rejects concurrent changes. */
+    expectedRevision?: number;
     /**
      * Write ONE block instead of the whole file — the id from `?view=blocks`.
      *
@@ -442,6 +458,27 @@ export declare class SforaApiClient {
      * A 409 from a `?block=` write throws a {@link SforaApiError} carrying the
      * server's recovery payload; read it with {@link blockConflictFrom}.
      */
+    listSkillDirectories(project: string): Promise<{
+        directories: Array<{
+            name: string;
+            version: number;
+        }>;
+    }>;
+    readSkillManifest(project: string, name: string): Promise<{
+        files: Array<{
+            path: string;
+            sha256: string;
+            size: number;
+            executable: boolean;
+        }>;
+        version: number;
+        hash: string;
+    }>;
+    readSkillFile(project: string, name: string, path: string): Promise<Uint8Array>;
+    readPathSnapshot(fsPath: string): Promise<{
+        content: string;
+        revision: number | null;
+    }>;
     writePath(fsPath: string, markdown: string, options?: WriteOptions): Promise<WriteResult & Partial<CardWriteResult>>;
     /** `DELETE …/(posts|drafts)/:filename.md` — soft-deletes the matched post. */
     deletePost(projectSlug: string, kind: PostKind, filename: string): Promise<void>;
@@ -550,6 +587,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>;
     /**

package/dist/api-client.js

@@ -81,14 +81,21 @@ function routeBase(kind) {
 }
 /** `?block=<id>` when one was asked for, and nothing at all when it wasn't. */
 function blockQuery(options) {
-    return options?.blockId
-        ? `?block=${encodeURIComponent(options.blockId)}`
-        : "";
+    const query = new URLSearchParams();
+    if (options?.blockId)
+        query.set("block", options.blockId);
+    if (options?.expectedRevision !== undefined) {
+        if (!Number.isSafeInteger(options.expectedRevision) || options.expectedRevision < 0)
+            throw new Error("Expected revision must be a non-negative integer.");
+        query.set("expectedRevision", String(options.expectedRevision));
+    }
+    return query.size ? `?${query}` : "";
 }
 export class SforaApiClient {
     #baseUrl;
     #apiKey;
     #actAs;
+    #clientLabel;
     /**
      * What the LAST response said about itself, beyond the data it carried.
      *
@@ -108,6 +115,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 +156,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;
@@ -307,6 +317,26 @@ export class SforaApiClient {
      * A 409 from a `?block=` write throws a {@link SforaApiError} carrying the
      * server's recovery payload; read it with {@link blockConflictFrom}.
      */
+    async listSkillDirectories(project) {
+        return this.#json(`/v1/fs/projects/${encodeURIComponent(project)}/skills`);
+    }
+    async readSkillManifest(project, name) {
+        return this.#json(`/v1/fs/projects/${encodeURIComponent(project)}/skills/${encodeURIComponent(name)}`);
+    }
+    async readSkillFile(project, name, path) {
+        const response = await this.#request("GET", `/v1/fs/projects/${encodeURIComponent(project)}/skills/${encodeURIComponent(name)}/${path.split("/").map(encodeURIComponent).join("/")}`);
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    async readPathSnapshot(fsPath) {
+        const response = await this.#request("GET", fsRequestPath(fsPath));
+        const advertised = response.headers.get("x-sfora-revision");
+        const etag = response.headers.get("etag")?.replace(/^W\//, "").replaceAll('"', "");
+        const raw = advertised !== null && /^\d+$/.test(advertised)
+            ? advertised : etag?.match(/^(\d+)(?:-(?:gzip|br))?$/)?.[1];
+        const numeric = raw === undefined ? NaN : Number(raw);
+        const revision = Number.isSafeInteger(numeric) && numeric >= 0 ? numeric : null;
+        return { content: await response.text(), revision };
+    }
     async writePath(fsPath, markdown, options) {
         const res = await this.#request("PUT", `${fsRequestPath(fsPath)}${blockQuery(options)}`, markdown);
         return this.#jsonFrom(res);
@@ -445,16 +475,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 +485,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 +502,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 +517,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 +585,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);
     }
     /**

package/dist/block-commands.d.ts

@@ -71,6 +71,7 @@ export declare function blocksCommand(client: SforaApiClient, fsPath: string, op
  */
 export declare function putCommand(client: SforaApiClient, fsPath: string, body: string, options?: {
     blockId?: string;
+    expectedRevision?: number;
     json?: boolean;
     /**
      * The run's presence latch. Omitted means "this call is the run" — a

package/dist/block-commands.js

@@ -106,6 +106,7 @@ export async function putCommand(client, fsPath, body, options = {}) {
     try {
         const result = await client.writePath(fsPath, body, {
             blockId: options.blockId,
+            ...(options.expectedRevision !== undefined ? { expectedRevision: options.expectedRevision } : {}),
         });
         const info = client.takeResponseInfo();
         if (options.json)

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

@@ -6,6 +6,10 @@
  * process — argv in, a parsed shape out.
  */
 export interface CliArgs {
+    skillsTarget?: string;
+    skillVersion?: number;
+    expectedVersion?: number;
+    expectedRevision?: number;
     command?: string;
     rest: string[];
     org?: string;
@@ -29,6 +33,9 @@ export interface CliArgs {
     waitFlag: boolean;
     message?: string;
     limit?: number;
+    follow: boolean;
+    awaitReply: boolean;
+    timeout?: number;
     client?: string;
     option: string[];
     target?: string;