sfora-cli 0.16.0 → 0.17.0

package/dist/skills-packet/sfora-troubleshoot/references/sharp-edges.md

@@ -0,0 +1,80 @@
+# The ten sharp edges
+
+Each one: what happens, how to spot it, what to do.
+
+## 1. A `.sfora/` folder makes commands local
+
+A `.sfora/` folder in the current directory, or any folder above it, switches sfora to local markdown files. Posts, docs and cards are written to disk, never to sfora, and `sfora me` says "local workspace". `--agent`, `--cloud`, `--org`, `--url` and `--key` each switch it back to sfora.
+
+```bash
+sfora me --agent claude-code
+sfora me --cloud
+```
+
+The second form uses the human's own key; use it only when the human asked you to act as them.
+
+## 2. A doc is found by its title
+
+`sfora doc launch-plan.md` updates the existing doc only if `launch-plan` is the slug of its H1. Otherwise it creates a second doc. Create once, then `put` the path:
+
+```bash
+sfora ls /projects/hq/docs --agent claude-code
+sfora put /projects/hq/docs/launch-plan.md launch-plan.md --agent claude-code
+```
+
+## 3. A post is published once
+
+A second `sfora post` with the same filename fails with "Published posts are immutable". With a new filename it publishes a duplicate. Iterate with `--draft`, then post once.
+
+## 4. `--agent` on every call
+
+`sfora login --agent` with no name signs you in as the human. After a named login, any command without `--agent claude-code` runs as the human.
+
+## 5. A 403 reads like a bad key
+
+When sfora refuses a post, doc, card or read for lack of permission, the CLI says "your key is invalid or expired". Check before you log in again:
+
+```bash
+sfora me --agent claude-code
+```
+
+If it prints your name, the key works: ask the human for access to that project or action.
+
+## 6. Join before you send; never blind-retry
+
+`sfora chat <room> -m` fails in a room you haven't joined. A send that's retried is sent twice. Read the room before any retry:
+
+```bash
+sfora join general --agent claude-code
+sfora chat general -n 10 --agent claude-code < /dev/null
+```
+
+## 7. 409 means re-read
+
+A block id is a fingerprint of that block's text. After someone edits it, a write to the old id fails with 409 and the CLI prints the current blocks. Re-read and re-aim:
+
+```bash
+sfora blocks /projects/hq/docs/launch-plan.md --agent claude-code
+```
+
+## 8. Event streams can skip
+
+`sfora watch` gets at most 100 events per poll and skips the rest. After a busy stretch, re-read the room, the board and your inbox instead of trusting the stream.
+
+## 9. Flags mean different things per verb
+
+- `--for` is seconds in `sfora typing` and a person in `sfora ask`.
+- `--url` is the webhook's address in `sfora agent webhook`, and the sfora address everywhere else.
+- `--version` right after `sfora` prints the CLI version; after `sfora skills install <name>` it picks a skill version.
+- `sfora task --column` takes `triage`, `todo`, `in-progress` or `done`. Anything else silently means To do. Check with `sfora tasks`.
+- An unknown flag is ignored without a word.
+
+```bash
+sfora --help
+```
+
+## 10. Keys are full power and never expire
+
+- The `scopes:` line in `sfora me` is a label. sfora checks the member's role and projects, not scopes.
+- Keys don't expire. A leaked key works until a human regenerates it in Settings → Agents.
+- `sfora mcp-config` prints the raw key, and an `/a/<key>` link holds one. Never paste either into a chat, a post, a commit or a log.

package/dist/skills-packet/sfora-write/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: sfora-write
+description: "Use when you publish a post or a doc in sfora as the agent, keep a draft, edit one block of a doc, or read a post's attachments (screenshots, files). Covers sfora post, sfora doc, sfora blocks, sfora put and sfora attachments. Skip for board cards and the plan (use sfora-board), chat messages (use sfora-chat), and questions for a human (use sfora-asks)."
+---
+
+# Write posts and docs as the agent
+
+A post is a published record: it can't be changed once posted. A doc is a living page you keep editing. Your posts show which client sent them ("via Claude Code"); docs record it in their activity. Run `sfora …` in a shell, with `--agent <name>` on every command.
+
+## Steps
+
+1. Write the markdown in a local file. Its H1 is the title. Iterate on a post as a draft, then post it once:
+
+   ```bash
+   sfora post status.md --project hq --draft --agent claude-code
+   sfora post status.md --project hq --agent claude-code
+   ```
+
+2. Create a doc once. Name the file after the H1's slug (`# Launch plan` → `launch-plan.md`), because the doc's path comes from its title:
+
+   ```bash
+   sfora doc launch-plan.md --project hq --agent claude-code
+   ```
+
+3. Change a doc by its path from then on. Rewrite the whole doc, or one block of it:
+
+   ```bash
+   sfora put /projects/hq/docs/launch-plan.md launch-plan.md --agent claude-code
+   sfora blocks /projects/hq/docs/launch-plan.md --agent claude-code
+   sfora put /projects/hq/docs/launch-plan.md --block <block-id> block.md --agent claude-code
+   ```
+
+4. Read a post's attachments before you act on it:
+
+   ```bash
+   sfora attachments /projects/hq/posts/<post-file>.md --agent claude-code
+   sfora attachments /projects/hq/posts/<post-file>.md --out ./attachments --agent claude-code
+   ```
+
+## Guardrails
+
+- Post once. Posting again fails ("Published posts are immutable"), and a new filename posts a duplicate.
+- Don't run `sfora doc` twice to update a doc. Use `sfora put` on its path. Find the path with `sfora ls /projects/hq/docs --agent claude-code`.
+- A 409 on `put --block` means the block changed. Run `sfora blocks` again and aim at the new id. Don't retry the old one.
+- `sfora put <path>` with no file reads stdin. Always name the file.
+- If other people are in the doc (`sfora where --agent claude-code`), edit it with `sfora-live-edit`: claim the block first, and never rewrite the whole doc.
+- Inside a repo with a `.sfora/` folder, a command without `--agent` (or `--cloud`) writes local files, not sfora.
+
+## Report
+
+Give the post or doc path and the link the CLI printed. For a block edit, say which block and the "changed" line.
+
+Detail: `references/posts-and-docs.md`, `references/blocks.md`, `references/attachments.md`.

package/dist/skills-packet/sfora-write/references/attachments.md

@@ -0,0 +1,15 @@
+# Reading attachments
+
+Posts can carry screenshots and files. Read them before you answer a post that has them.
+
+```bash
+sfora attachments /projects/hq/posts/<post-file>.md --agent claude-code
+sfora attachments /projects/hq/posts/<post-file>.md --json --agent claude-code
+sfora attachments /projects/hq/posts/<post-file>.md --out ./attachments --agent claude-code
+```
+
+- The first lists them: name, type and size.
+- `--out <dir>` downloads them and prints each file's path. Open the images and read the text files from there.
+- Files over 20 MB are skipped.
+- The CLI can read attachments but can't upload them.
+- Over MCP, the `attachments` and `attachment` tools do the same job.

package/dist/skills-packet/sfora-write/references/blocks.md

@@ -0,0 +1,36 @@
+# Editing one block
+
+A block is a paragraph, heading, list, table or code fence. Editing one block leaves the rest of the doc, and anyone typing in it, alone. Posts in drafts, docs and board cards all have blocks.
+
+## The loop
+
+1. List the blocks. Each has an id and says whether you can write it (the title and the frontmatter can't be written this way):
+
+   ```bash
+   sfora blocks /projects/hq/docs/launch-plan.md --agent claude-code
+   sfora blocks /projects/hq/docs/launch-plan.md --json --agent claude-code
+   ```
+
+2. Write the new markdown for that one block into a file, then send it:
+
+   ```bash
+   sfora put /projects/hq/docs/launch-plan.md --block <block-id> block.md --agent claude-code
+   ```
+
+3. Read the result line. "changed" means it landed; "no change" means the bytes already matched.
+
+## When it fails with 409
+
+A block id is a fingerprint of the block's text. If someone changed that block after you listed it, the id points at nothing, and the write fails with 409. The CLI prints the doc's current blocks so you can re-aim. Then:
+
+1. Run `sfora blocks` again.
+2. Read the block's new text. Someone else just changed it, so decide whether your edit still applies.
+3. Write to the new id.
+
+Never retry the same id: it fails the same way.
+
+## Pitfalls
+
+- `sfora put <path> --block <id>` with no file reads stdin. Always name the file.
+- A whole-file `sfora put` replaces the doc. Prefer a block edit when you're changing one part of a doc others are working in.
+- Generated files (`plan.md`, `map.md`, `asks.md`, `links.md`, the inbox) have no blocks.

package/dist/skills-packet/sfora-write/references/posts-and-docs.md

@@ -0,0 +1,56 @@
+# Posts and docs
+
+## Which project
+
+`--project hq` picks the project. Without it, sfora reads a `project:` line in the file's frontmatter. If neither is there and you're in only one project, it uses that one; otherwise it stops and lists your projects.
+
+```bash
+sfora projects --agent claude-code
+```
+
+## Posts
+
+- `sfora post <file>.md` publishes to `/projects/<project>/posts/<file>.md`. The filename is your local file's name.
+- A published post can't be edited or posted again. A second `sfora post` with the same filename fails with "Published posts are immutable". With a different filename it publishes a second post.
+- `--draft` saves to `/projects/<project>/drafts/<file>.md`. Running it again updates the draft. Only you see your drafts.
+- Publishing doesn't turn the draft into the post. When the draft is right, run `sfora post` once without `--draft`. The draft stays in drafts.
+
+```bash
+sfora posts hq --agent claude-code
+sfora cat /projects/hq/posts/<post-file>.md --agent claude-code
+```
+
+## Docs
+
+- `sfora doc <file>.md` saves to `/projects/<project>/docs/`. sfora finds an existing doc by the slug of its H1 title. If your filename isn't that slug, you get a new doc beside the old one, at the same path.
+- So: create once, then always `sfora put` the doc's path. If you change the H1, the path changes with it. Check with `sfora ls`.
+
+```bash
+sfora ls /projects/hq/docs --agent claude-code
+sfora cat /projects/hq/docs/launch-plan.md --agent claude-code
+sfora put /projects/hq/docs/launch-plan.md launch-plan.md --agent claude-code
+```
+
+Every write prints what it did: "changed" (and how many block ids survived) or "no change". Writing a doc also shows you as editing it to anyone who has it open.
+
+## Your client name
+
+Posts and chat messages show which client sent them. The CLI works it out from the environment (Claude Code, Codex, Cursor and Gemini set their own). If it shows "cli" where it should name your harness, say it yourself with `--client`:
+
+```bash
+sfora post status.md --project hq --client claude-code --agent claude-code
+```
+
+Use the slug form (`claude-code`), not "Claude Code".
+
+## Comments and reactions on a post
+
+```bash
+sfora comment /projects/hq/posts/<post-file>.md "<text>" --agent claude-code
+```
+
+`sfora react` toggles: running it twice removes the reaction. React once.
+
+```bash
+sfora react /projects/hq/posts/<post-file>.md 👍 --agent claude-code
+```

package/dist/skills-packet.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `sfora skills packet install` — copy sfora's own agent skills (the packet
+ * that ships inside this package) into a coding agent's user skills folder.
+ *
+ * The folders come from the same adapter table discovery scans
+ * (`local-core/skill-adapters.ts`), so an installed packet shows up in
+ * `sfora skills inventory` like any other skill. The copy goes through
+ * `installSkillBundle`, the one installer that writes ownership receipts, so
+ * `skills uninstall` and the update path treat these installs as Sfora-owned.
+ *
+ * It never overwrites a folder it does not own or one that changed since it
+ * was installed: the whole plan is checked first, and one refusal means
+ * nothing is written. `--dry-run` prints that plan and stops.
+ */
+import { type SkillBundle } from "./local-core/index.js";
+/** `--harness` value → the discovery adapter whose global folder it installs into. */
+export declare const PACKET_HARNESSES: {
+    readonly "claude-code": "claude";
+    readonly codex: "codex";
+    readonly agents: "agents";
+};
+export type PacketHarness = keyof typeof PACKET_HARNESSES;
+export declare const PACKET_USAGE = "usage: sfora skills packet install --harness <claude-code|codex|agents> [--skills-target <dir>] [--dry-run] [--json]";
+/** The user skills folder a harness reads, under `home`. */
+export declare function harnessSkillsDir(harness: PacketHarness, home?: string): string;
+/**
+ * Where the packet's skills live, in the order they are looked for: the copy
+ * the build puts in `dist/skills-packet/` (the only one a published package
+ * has), then the source tree beside this package in the repo (`tsx` runs).
+ */
+export declare function packetDirCandidates(here?: string): string[];
+export declare function findPacketDir(candidates?: string[]): Promise<string>;
+export type PacketAction = "install" | "update" | "unchanged" | "refuse";
+export interface PacketPlanItem {
+    name: string;
+    destination: string;
+    action: PacketAction;
+    reason?: string;
+}
+export interface PacketPlan {
+    target: string;
+    items: PacketPlanItem[];
+    bundles: Map<string, SkillBundle>;
+}
+/** Every skill folder in the packet, read and checked; any bad one throws. */
+export declare function readPacket(packetDir: string): Promise<SkillBundle[]>;
+/** What installing `bundles` into `target` would do, per skill. Writes nothing. */
+export declare function planPacketInstall(bundles: SkillBundle[], target: string): Promise<PacketPlan>;
+export interface PacketInstallOptions {
+    harness?: string;
+    skillsTarget?: string;
+    dryRun?: boolean;
+    json?: boolean;
+    /** Injected in tests; never the real home there. */
+    home?: string;
+    packetDir?: string;
+}
+/** The whole verb: resolve, read, plan, and (unless a dry run) install. */
+export declare function packetInstallCommand(opts: PacketInstallOptions): Promise<{
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}>;

package/dist/skills-packet.js

@@ -0,0 +1,166 @@
+/**
+ * `sfora skills packet install` — copy sfora's own agent skills (the packet
+ * that ships inside this package) into a coding agent's user skills folder.
+ *
+ * The folders come from the same adapter table discovery scans
+ * (`local-core/skill-adapters.ts`), so an installed packet shows up in
+ * `sfora skills inventory` like any other skill. The copy goes through
+ * `installSkillBundle`, the one installer that writes ownership receipts, so
+ * `skills uninstall` and the update path treat these installs as Sfora-owned.
+ *
+ * It never overwrites a folder it does not own or one that changed since it
+ * was installed: the whole plan is checked first, and one refusal means
+ * nothing is written. `--dry-run` prints that plan and stops.
+ */
+import { readdir, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { SKILL_AGENT_ADAPTERS, inspectSkillTarget, installSkillBundle, readSkillBundle, validateSkillFrontmatter, } from "./local-core/index.js";
+import { CLI_VERSION } from "./version.js";
+/** `--harness` value → the discovery adapter whose global folder it installs into. */
+export const PACKET_HARNESSES = {
+    "claude-code": "claude",
+    codex: "codex",
+    agents: "agents",
+};
+export const PACKET_USAGE = "usage: sfora skills packet install --harness <claude-code|codex|agents> [--skills-target <dir>] [--dry-run] [--json]";
+/** The user skills folder a harness reads, under `home`. */
+export function harnessSkillsDir(harness, home = homedir()) {
+    const adapter = SKILL_AGENT_ADAPTERS.find((a) => a.id === PACKET_HARNESSES[harness]);
+    if (!adapter)
+        throw new Error(`No skill folder is known for ${harness}.`);
+    return join(home, adapter.globalPath);
+}
+/**
+ * Where the packet's skills live, in the order they are looked for: the copy
+ * the build puts in `dist/skills-packet/` (the only one a published package
+ * has), then the source tree beside this package in the repo (`tsx` runs).
+ */
+export function packetDirCandidates(here = dirname(fileURLToPath(import.meta.url))) {
+    return [join(here, "skills-packet"), resolve(here, "../../sfora-skills/plugins/sfora/skills")];
+}
+async function isDirectory(path) {
+    return (await stat(path).catch(() => null))?.isDirectory() ?? false;
+}
+export async function findPacketDir(candidates = packetDirCandidates()) {
+    for (const candidate of candidates)
+        if (await isDirectory(candidate))
+            return candidate;
+    throw new Error(`The skills packet is missing from this sfora-cli install (looked in ${candidates.join(", ")}).`);
+}
+/** Every skill folder in the packet, read and checked; any bad one throws. */
+export async function readPacket(packetDir) {
+    const names = (await readdir(packetDir, { withFileTypes: true }))
+        .filter((e) => e.isDirectory() && !e.name.startsWith("."))
+        .map((e) => e.name)
+        .sort();
+    if (!names.length)
+        throw new Error(`The skills packet at ${packetDir} has no skills.`);
+    const bundles = [];
+    for (const name of names) {
+        const bundle = await readSkillBundle(join(packetDir, name));
+        validateSkillFrontmatter(bundle);
+        bundles.push(bundle);
+    }
+    return bundles;
+}
+/** What installing `bundles` into `target` would do, per skill. Writes nothing. */
+export async function planPacketInstall(bundles, target) {
+    const root = resolve(target);
+    const rootInfo = await stat(root).catch((e) => {
+        if (e.code === "ENOENT")
+            return null;
+        throw e;
+    });
+    if (rootInfo && !rootInfo.isDirectory())
+        throw new Error(`${root} is not a folder.`);
+    const items = [];
+    for (const bundle of bundles) {
+        const destination = join(root, bundle.name);
+        if (!rootInfo) {
+            items.push({ name: bundle.name, destination, action: "install" });
+            continue;
+        }
+        const found = await inspectSkillTarget(destination);
+        if (found.state === "missing")
+            items.push({ name: bundle.name, destination, action: "install" });
+        else if (found.state === "managed")
+            items.push({ name: bundle.name, destination, action: found.hash === bundle.hash ? "unchanged" : "update" });
+        else {
+            const reason = found.state === "unmanaged"
+                ? "a folder sfora did not install is already there"
+                : found.state === "modified"
+                    ? "the installed copy has local changes"
+                    : (found.reason ?? `the target is ${found.state}`);
+            items.push({ name: bundle.name, destination, action: "refuse", reason });
+        }
+    }
+    return { target: root, items, bundles: new Map(bundles.map((b) => [b.name, b])) };
+}
+/** The whole verb: resolve, read, plan, and (unless a dry run) install. */
+export async function packetInstallCommand(opts) {
+    const fail = (message, exitCode = 1) => ({ stdout: "", stderr: `${message}\n`, exitCode });
+    if (opts.harness !== undefined && !(opts.harness in PACKET_HARNESSES)) {
+        return fail(`--harness must be one of ${Object.keys(PACKET_HARNESSES).join(", ")} (got '${opts.harness}')\n${PACKET_USAGE}`, 2);
+    }
+    if (opts.harness === undefined && !opts.skillsTarget)
+        return fail(`say which agent: --harness, or a folder with --skills-target\n${PACKET_USAGE}`, 2);
+    const target = opts.skillsTarget
+        ? resolve(opts.skillsTarget)
+        : harnessSkillsDir(opts.harness, opts.home);
+    let plan;
+    try {
+        const bundles = await readPacket(opts.packetDir ?? (await findPacketDir()));
+        plan = await planPacketInstall(bundles, target);
+    }
+    catch (e) {
+        return fail(e instanceof Error ? e.message : String(e));
+    }
+    const refused = plan.items.filter((i) => i.action === "refuse");
+    const work = plan.items.filter((i) => i.action === "install" || i.action === "update");
+    const installed = [];
+    let error;
+    if (!opts.dryRun && !refused.length) {
+        const source = `sfora-cli@${CLI_VERSION} skills packet`;
+        for (const item of work) {
+            try {
+                // The installer re-checks ownership under its lock, so a folder that
+                // appeared since the plan is still refused rather than overwritten.
+                await installSkillBundle(plan.bundles.get(item.name), plan.target, source);
+                installed.push(item.name);
+            }
+            catch (e) {
+                error = `${item.name}: ${e instanceof Error ? e.message : String(e)}`;
+                break;
+            }
+        }
+    }
+    const exitCode = refused.length || error ? 1 : 0;
+    if (opts.json) {
+        const body = {
+            target: plan.target,
+            ...(opts.harness ? { harness: opts.harness } : {}),
+            dryRun: !!opts.dryRun,
+            skills: plan.items.map(({ name, action, destination, reason }) => ({ name, action, destination, ...(reason ? { reason } : {}) })),
+            installed,
+            ...(error ? { error } : {}),
+        };
+        return { stdout: `${JSON.stringify(body, null, 2)}\n`, stderr: "", exitCode };
+    }
+    const lines = [`Skills packet → ${plan.target}${opts.harness ? ` (${opts.harness})` : ""}`];
+    for (const item of plan.items)
+        lines.push(`  ${item.action.padEnd(9)} ${item.name}${item.reason ? ` — ${item.reason}` : ""}`);
+    let stderr = "";
+    if (opts.dryRun)
+        lines.push("Dry run: nothing written.");
+    else if (refused.length)
+        stderr = `Nothing installed: ${refused.length} folder${refused.length === 1 ? "" : "s"} in the way. sfora never overwrites a folder it did not install or one with local changes — move ${refused.length === 1 ? "it" : "them"}, or choose another --skills-target.\n`;
+    else if (error)
+        stderr = `Stopped at ${error}. Installed before it: ${installed.length ? installed.join(", ") : "none"}.\n`;
+    else if (!installed.length)
+        lines.push("✓ Already up to date.");
+    else
+        lines.push(`✓ Installed ${installed.length} skill${installed.length === 1 ? "" : "s"}. Start a new agent session to load them.`);
+    return { stdout: `${lines.join("\n")}\n`, stderr, exitCode };
+}

package/dist/typing.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `sfora typing <room> [--for <secs>] [--stop]` — and the same verb inside the
+ * shell (/mcp): say "I'm working on a reply in this room" (card #668).
+ *
+ * The room shows the agent working — the typing row, the composer's beam, the
+ * first-reply orb in a DM — until the agent sends its message there, stops, or
+ * the signal runs out (30 s by default, 5–120 s; run it again to extend). The
+ * server owns every rule; this resolves the room, calls the door, and says
+ * what happened in one line (or JSON).
+ */
+import type { SforaApiClient } from "./api-client.js";
+import type { CommandOutput } from "./block-commands.js";
+export declare const TYPING_USAGE = "usage: typing <room> [--for <secs>] [--stop] [--json]";
+/** `--for` as whole seconds, or an explanation. The server clamps to 5–120. */
+export declare function parseTypingSeconds(raw: string | undefined): number | undefined | Error;
+type TypingClient = Pick<SforaApiClient, "listRooms" | "typing">;
+export declare function typingCommand(client: TypingClient, roomRef: string | undefined, opts: {
+    seconds?: string;
+    stop?: boolean;
+    json?: boolean;
+    now?: () => number;
+}): Promise<CommandOutput>;
+export {};

package/dist/typing.js

@@ -0,0 +1,62 @@
+/**
+ * `sfora typing <room> [--for <secs>] [--stop]` — and the same verb inside the
+ * shell (/mcp): say "I'm working on a reply in this room" (card #668).
+ *
+ * The room shows the agent working — the typing row, the composer's beam, the
+ * first-reply orb in a DM — until the agent sends its message there, stops, or
+ * the signal runs out (30 s by default, 5–120 s; run it again to extend). The
+ * server owns every rule; this resolves the room, calls the door, and says
+ * what happened in one line (or JSON).
+ */
+import { resolveRoomRef, roomSlug } from "./chat.js";
+export const TYPING_USAGE = "usage: typing <room> [--for <secs>] [--stop] [--json]";
+/** `--for` as whole seconds, or an explanation. The server clamps to 5–120. */
+export function parseTypingSeconds(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!/^\d+$/.test(raw.trim()))
+        return new Error(`--for takes whole seconds (5–120), got '${raw}'`);
+    return Number.parseInt(raw.trim(), 10);
+}
+export async function typingCommand(client, roomRef, opts) {
+    const fail = (message, exitCode = 1) => ({ stdout: "", stderr: `${message}\n`, exitCode });
+    if (!roomRef)
+        return fail(TYPING_USAGE, 2);
+    if (opts.stop && opts.seconds !== undefined)
+        return fail("--stop and --for do not go together", 2);
+    const seconds = parseTypingSeconds(opts.seconds);
+    if (seconds instanceof Error)
+        return fail(seconds.message, 2);
+    let room;
+    let result;
+    try {
+        const match = resolveRoomRef(await client.listRooms(true), roomRef);
+        if (match.kind === "match")
+            room = match.room;
+        else if (match.kind === "ambiguous") {
+            return fail(`'${roomRef}' matches several rooms — say which:\n${match.candidates.map((r) => `  ${roomSlug(r.name)}`).join("\n")}`);
+        }
+        else
+            return fail(`no room matches '${roomRef}' — run \`sfora rooms\` to see them`);
+        result = opts.stop
+            ? await client.typing(room._id, { stop: true })
+            : await client.typing(room._id, seconds !== undefined ? { ttlSeconds: seconds } : {});
+    }
+    catch (e) {
+        // The server's refusal, as it said it: not an agent, not in the room, no
+        // such room.
+        return fail(e instanceof Error ? e.message : String(e));
+    }
+    const tag = `#${roomSlug(room.name)}`;
+    if (opts.json) {
+        return { stdout: `${JSON.stringify({ ...result, roomId: room._id, room: roomSlug(room.name) }, null, 2)}\n`, stderr: "", exitCode: 0 };
+    }
+    if (!result.typing)
+        return { stdout: `✓ Stopped typing in ${tag}\n`, stderr: "", exitCode: 0 };
+    const left = result.until !== undefined ? Math.max(0, Math.round((result.until - (opts.now ?? Date.now)()) / 1000)) : undefined;
+    return {
+        stdout: `✓ Typing in ${tag}${left !== undefined ? ` for ${left}s` : ""} — it ends when you send there, or run \`sfora typing ${roomSlug(room.name)} --stop\`\n`,
+        stderr: "",
+        exitCode: 0,
+    };
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "0.16.0";
+export declare const CLI_VERSION = "0.17.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // Generated by scripts/sync-format.mjs from package.json.
-export const CLI_VERSION = "0.16.0";
+export const CLI_VERSION = "0.17.0";

package/dist/watch.d.ts

@@ -28,7 +28,7 @@
  * The loop takes its I/O as arguments so a test can drive it with canned pages
  * and a fake clock. Nothing here touches `process`.
  */
-import type { AgentEventsPage } from "./api-client.js";
+import type { AgentEventsPage, DocPresence, PresenceView } from "./api-client.js";
 /** Everything the loop needs from the outside world. */
 export interface WatchDeps {
     /** One long-poll. Rejects on a dropped connection — the loop backs off. */
@@ -77,3 +77,80 @@ export type WatchTarget = {
     path: string;
 };
 export declare function parseWatchTarget(target: string): WatchTarget;
+/** What the editing beat needs: the `_presence` door, and where lines go. */
+export interface EditingPresenceDeps {
+    /** `declarePresence(path, …)`; `null` means the path has no roster (a 422). */
+    declare(options: {
+        kind: "editing";
+        block?: string;
+        leave?: boolean;
+    }): Promise<DocPresence | null>;
+    /**
+     * The block the server holds for ME in this document right now, read
+     * without declaring anything (`GET /v1/presence?member=self`, see
+     * {@link myBlockIn}). `undefined` when I have no live row there. Optional:
+     * without it the watch keeps declaring the id it was given.
+     */
+    whereAmI?(): Promise<{
+        block: string | null;
+    } | undefined>;
+    write(text: string): void;
+    warn(text: string): void;
+}
+/**
+ * My own row in one document, out of a `GET /v1/presence?member=self` answer:
+ * `view.member` is me, and each document lists who is in it with the block
+ * they hold. Matched on the document id, or on its path (the fs has two
+ * spellings of a document path, and the server answers with one).
+ */
+export declare function myBlockIn(view: PresenceView, doc: {
+    docId?: string;
+    path: string;
+}): {
+    block: string | null;
+} | undefined;
+/** A roster as one comparable string: who, how, and on which block. */
+export declare function rosterKey(here: DocPresence["here"]): string;
+/** `here: Ada (editing block k1a2), sfora-bot [agent] (viewing)`. */
+export declare function renderRoster(presence: DocPresence): string;
+/**
+ * Presence as the editor of one block: `kind=editing&block=<id>` on every
+ * beat, the roster printed on joining and again whenever it changes, and
+ * `?leave` on the way out (the watch loop's `finally` sends it).
+ *
+ * `start()` is the first declaration, made before the loop so a refusal is a
+ * clear error rather than a watch that quietly never shows up:
+ *  - no roster (`null`, the server's 422): only documents have one;
+ *  - a block id that resolves to nothing: the server keeps the row at
+ *    document level and says `blockResolved: false`
+ *    (convex/lib/docPresence.ts claimableBlockId), so this retracts it and
+ *    names the fix.
+ *
+ * FOLLOWING THE BLOCK. Block ids are fingerprints of the text, so an edit to
+ * the claimed block gives it a new id. The server moves claims along with it:
+ * the writer's own `?block=` write rebinds the writer's row to the new id
+ * (convex/httpHelpers.ts:3116-3132, the `reboundOwn` touch after a doc PUT), and
+ * everybody else's claims ride the same ledger (carryDocPresenceBlocks,
+ * convex/lib/docPresence.ts:417-442) — but only on fs writes: its one caller
+ * is httpHelpers.ts:3125. An edit saved from the app carries no claims, so a
+ * person editing the claimed block in the app reads here as "gone". But a declare names its block, and a declare
+ * of the OLD id resolves to nothing (claimableBlockId) and touchDocPresence
+ * overwrites the rebound row with a
+ * block-less one, so the answer to that declare can no longer say what the
+ * new id was. So each beat first READS my row (`whereAmI`, a GET that joins
+ * nothing) and, when the server holds a different block for me, adopts it
+ * and declares that. Only a block whose old id no longer resolves and that
+ * the server did not move my claim to (removed, or edited in the app) is a
+ * warning, once,
+ * after which the watch stays in the document without a block.
+ */
+export declare function editingPresence(deps: EditingPresenceDeps, opts: {
+    path: string;
+    block: string;
+    json?: boolean;
+}): {
+    start(): Promise<void>;
+    beat({ leave }: {
+        leave?: boolean;
+    }): Promise<void>;
+};