sfora-cli 0.13.1 → 0.15.0

package/dist/cli-args.js

@@ -6,13 +6,21 @@
  * 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")
             args.mcp = true;
         else if (a === "--help" || a === "-h")
             args.help = true;
+        else if (a === "--skills-target")
+            args.skillsTarget = argv[++i];
+        else if (a === "--version")
+            args.skillVersion = Number(argv[++i]);
+        else if (a === "--expected-version")
+            args.expectedVersion = Number(argv[++i]);
+        else if (a === "--expected-revision")
+            args.expectedRevision = Number(argv[++i]);
         else if (a === "--org")
             args.org = argv[++i];
         else if (a.startsWith("--org="))
@@ -89,6 +97,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

@@ -6,9 +6,11 @@
  *   SFORA_API_KEY=sk_… SFORA_URL=http://localhost:2222 sfora --org test
  *   sfora --mcp        # MCP stdio server for Claude/Cursor
  */
+import { CLI_VERSION } from "./version.js";
+import { runSkillsCommand, SKILLS_HELP } from "./skills-command.js";
 import * as readline from "node:readline";
 import { spawn } from "node:child_process";
-import { readFile as readLocalFile } from "node:fs/promises";
+import { realpath, readFile as readLocalFile } from "node:fs/promises";
 import { basename } from "node:path";
 import { taskUploadFilename } from "./format/taskUploadFilename.js";
 import { createSforaShell, createLocalShell, SforaApiError, } from "./index.js";
@@ -19,9 +21,9 @@ import { colors, ndjson, presenceRecords, renderPresence, renderWriteEffect, url
 import { parseWatchTarget, watchLoop } from "./watch.js";
 import { LocalWorkspace, initWorkspace, findWorkspace, migrateWorkspaceStages, } from "./local/workspace.js";
 import { runMcpServer } from "./mcp-server.js";
-import { readConfig, writeConfig, resolveSettings, upsertProfile, effectiveProfiles, DEFAULT_URL, } from "./config.js";
+import { readConfig, updateConfig, resolveSettings, upsertProfile, effectiveProfiles, profileKey, 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):
@@ -57,6 +59,7 @@ Browse & read:
   sfora cat <path>                    Print a file's markdown
   sfora url <path>                    Print the web URL for a path
   sfora open <path>                   Open that URL in your browser
+  sfora desktop <file.md>             Open local Markdown in Sfora for macOS
   sfora                               Open the interactive shell
 
   Add --json to any list command (projects/posts/tasks/ls/me) for
@@ -69,10 +72,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"
@@ -169,15 +180,22 @@ async function runInit(args) {
         process.exitCode = 1;
         return;
     }
-    const { cfg: next, key: profile } = upsertProfile(cfg, {
-        url,
-        org: org || cfg.org,
-        apiKey: key,
-    });
-    const path = await writeConfig(next);
+    const identity = { url, org: org || cfg.org, apiKey: key };
+    const profile = profileKey(identity.url, identity.org);
+    const path = await updateConfig(current => upsertProfile(current, identity).cfg);
     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 {
@@ -233,30 +251,14 @@ async function runLogin(args, baseUrl) {
             continue;
         }
         if (data.status === "approved" && data.apiKey) {
-            const cfg = await readConfig();
-            let next;
-            if (args.bot) {
-                // Save under the bot's slot; keep the user's personal key intact.
-                next = {
-                    ...cfg,
-                    url: base,
-                    bots: {
-                        ...cfg.bots,
-                        [args.bot]: { apiKey: data.apiKey, org: data.orgSlug ?? undefined },
-                    },
-                };
-            }
-            else {
-                // Add/update this deployment+org as its own profile instead of
-                // overwriting one shared key — so logging in here never invalidates the
-                // key you hold for another deployment.
-                next = upsertProfile(cfg, {
-                    url: base,
-                    org: data.orgSlug ?? undefined,
-                    apiKey: data.apiKey,
-                }).cfg;
-            }
-            const path = await writeConfig(next);
+            const approvedKey = data.apiKey;
+            const botName = args.bot;
+            const path = await updateConfig(current => botName ? {
+                ...current, url: base,
+                bots: { ...current.bots, [botName]: { apiKey: approvedKey, org: data.orgSlug ?? undefined } },
+            } : upsertProfile(current, {
+                url: base, org: data.orgSlug ?? undefined, apiKey: approvedKey,
+            }).cfg);
             console.log(`\n${colors.green}✓${colors.reset} Logged in as ${data.name ?? "you"}${data.orgSlug ? ` ${colors.dim}(${data.orgSlug})${colors.reset}` : ""}${args.bot ? ` ${colors.dim}[bot: ${args.bot}]${colors.reset}` : ""} — saved ${path}`);
             return;
         }
@@ -480,6 +482,7 @@ async function runVerb(args, fs, client) {
             : await readStdin();
         return writeCommandOutput(await putCommand(client, path, body, {
             blockId: args.block,
+            expectedRevision: args.expectedRevision,
             json: args.json,
             presence: runPresence,
         }));
@@ -539,7 +542,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 +770,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,13 +832,16 @@ 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();
+        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));
@@ -844,6 +850,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 +866,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 +912,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,6 +953,7 @@ 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.
@@ -934,6 +964,9 @@ async function runChat(args, client) {
             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 +981,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 +1255,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;
@@ -1285,9 +1477,26 @@ Everything is git-versioned with your repo. ${colors.dim}Connect a team later wi
 Type ${colors.cyan}exit${colors.reset} to quit.
 `;
 async function main() {
+    if (["--version", "-v"].includes(process.argv[2] ?? "")) {
+        console.log(`sfora-cli ${CLI_VERSION}`);
+        return;
+    }
     const args = parseArgs(process.argv.slice(2));
     if (args.help) {
-        process.stdout.write(HELP);
+        process.stdout.write(HELP + "\n" + SKILLS_HELP);
+        return;
+    }
+    if (args.command === "desktop") {
+        if (process.platform !== "darwin")
+            throw new Error("Desktop opening is currently supported on macOS.");
+        if (!args.rest.length)
+            throw new Error("usage: sfora desktop <file.md> [file.md ...]");
+        const paths = await Promise.all(args.rest.map(path => realpath(path)));
+        await new Promise((resolve, reject) => {
+            const child = spawn("/usr/bin/open", ["-a", "Sfora", "--", ...paths], { stdio: "inherit" });
+            child.once("error", reject);
+            child.once("exit", code => code === 0 ? resolve() : reject(new Error("Could not open Sfora. Install Sfora.app in Applications first.")));
+        });
         return;
     }
     if (args.command === "init") {
@@ -1303,7 +1512,17 @@ async function main() {
     }
     const cfg = await readConfig();
     const settings = resolveSettings({ url: args.url, apiKey: args.key, org: args.org, bot: args.bot }, cfg);
+    if (args.command === "skills") {
+        await runSkillsCommand(args, settings);
+        return;
+    }
     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 +1563,7 @@ async function main() {
                 apiKey: apiKey ?? "",
                 org: settings.org ?? "",
                 localRoot,
+                clientLabel,
             });
             return;
         }
@@ -1372,6 +1592,7 @@ async function main() {
             apiKey,
             org: settings.org ?? "",
             actAs: args.as,
+            clientLabel,
             presence: runPresence,
         });
         try {
@@ -1392,7 +1613,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 +1627,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/config.d.ts

@@ -17,6 +17,8 @@ export interface SforaConfig {
 export declare const CONFIG_PATH: string;
 export declare const DEFAULT_URL = "https://www.sfora.ai";
 export declare function readConfig(): Promise<SforaConfig>;
+export declare function updateConfig(update: (current: SforaConfig) => SforaConfig): Promise<string>;
+/** Merge profile maps under a process lock for older callers holding a snapshot. */
 export declare function writeConfig(cfg: SforaConfig): Promise<string>;
 export interface ResolvedSettings {
     url: string;

package/dist/config.js

@@ -11,7 +11,8 @@
  */
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { readFile, writeFile, mkdir, chmod } from "node:fs/promises";
+import { readFile, mkdir } from "node:fs/promises";
+import { atomicWrite, withLocalLock } from "./local-core/files.js";
 const CONFIG_DIR = join(homedir(), ".sfora");
 export const CONFIG_PATH = join(CONFIG_DIR, "config.json");
 // Production sfora. Local development of sfora itself overrides via --url or
@@ -27,12 +28,20 @@ export async function readConfig() {
         return {};
     }
 }
+export async function updateConfig(update) {
+    await mkdir(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    return withLocalLock(CONFIG_PATH, async () => {
+        const next = update(await readConfig());
+        await atomicWrite(CONFIG_PATH, `${JSON.stringify(next, null, 2)}\n`, 0o600);
+        return CONFIG_PATH;
+    });
+}
+/** Merge profile maps under a process lock for older callers holding a snapshot. */
 export async function writeConfig(cfg) {
-    await mkdir(CONFIG_DIR, { recursive: true });
-    await writeFile(CONFIG_PATH, `${JSON.stringify(cfg, null, 2)}\n`, "utf8");
-    // The file holds an API key — keep it owner-readable only.
-    await chmod(CONFIG_PATH, 0o600).catch(() => { });
-    return CONFIG_PATH;
+    return updateConfig(current => ({ ...current, ...cfg,
+        profiles: { ...current.profiles, ...cfg.profiles },
+        bots: { ...current.bots, ...cfg.bots },
+    }));
 }
 // First non-empty value (treats "" / undefined as unset).
 function pick(...vals) {

package/dist/format/cardMarkdown.d.ts

@@ -16,6 +16,7 @@ export interface MarkdownCardInput {
     resolution?: string;
     scope?: "out";
     blockedBy?: number[];
+    parentCardId?: string;
 }
 export interface MarkdownBoardRef {
     _id: string;

package/dist/format/cardMarkdown.js

@@ -63,6 +63,7 @@ export function cardToMarkdown(card, board, column, commentsCount) {
     const fm = serializeFrontmatter([
         ["id", card._id],
         ["number", String(card.number)],
+        ["parentCardId", card.parentCardId],
         ["board", board?.slug ?? board?.name ?? ""],
         ["boardId", board?._id ?? ""],
         ["column", column?.name ?? ""],

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,6 @@ 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";
+export { SkillsClient } from "./skills-client.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,6 @@ 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";
+export { SkillsClient } from "./skills-client.js";

package/dist/local/workspace.d.ts

@@ -1,19 +1,3 @@
-/**
- * LocalWorkspace — the OSS local mode. A `.sfora/` directory in your repo is
- * the workspace: tasks, posts, and docs are plain markdown files on disk, in
- * exactly the same format the cloud serves over /v1/fs (shared `../format`
- * core), so `cp` is a migration.
- *
- *   .sfora/
- *     board/01-todo/0001-fix-login.md   tasks — NNNN-<slug>.md per column dir
- *     posts/2026-07-02-standup.md       posts — YYYY-MM-DD-<slug>.md
- *     docs/architecture.md              docs  — <slug>.md
- *
- * This module owns the *semantics* (scaffolding, card numbering, canonical
- * filenames, listings). The interactive shell needs no virtualization locally —
- * just-bash's ReadWriteFs jails a real directory, and real `mv` between column
- * dirs IS a card move.
- */
 /** Directory name that marks a local sfora workspace. */
 export declare const WORKSPACE_DIR = ".sfora";
 /**