shadok-ai 0.17.0 → 0.17.2

package/README.md

@@ -434,6 +434,62 @@ supplies the reaper. And either way it is decided when the container is
 **created**: `docker restart` empties the table — pid 1 restarts, the kernel
 drops the lot — but the leak starts over, so a recreate is what makes it stop.
 
+### Groups and deployment modes
+
+An agent lives in a **group**, and a group is both what is isolated and who can
+see it:
+
+- **Private** — only you. One per person, sealed, invisible even to an admin.
+- **Restricted** — your team: a member list, any member can invite.
+- **Public** — everyone. `Main` is the default public group.
+
+You see and drive only your own groups plus the public ones; that covers the
+agent list, secrets, the shared ledger and messaging between agents. Private and
+restricted groups are real walls: each agent runs as its **own OS user** with its
+own home and secrets, never as root. Crossing a wall is always a deliberate act:
+drop a file in the shared `~/shared/` folder, record a ledger line with
+`--public`, push a branch, or message an agent (public groups freely, restricted
+ones only with a handle they gave you; private groups cannot be messaged).
+
+Real isolation needs two things, checked once at boot:
+
+1. the server can create OS users (it runs as root or has passwordless `sudo` —
+   the official Docker image or a VPS deploy), **and**
+2. a GUI password is set (`SHADOK_GUI_PASSWORD`), because accounts are who the
+   walls protect.
+
+Both → **multi-tenant**. Anything else — `npx shadok-ai` on your machine, Docker
+without the password — stays **single-tenant**, exactly as before: it says so and
+refuses to create a private or restricted group rather than drawing one that
+protects nothing. You don't configure this; it follows from how you run it. The
+boot log prints `deployment mode: …`.
+
+An existing single-tenant instance that comes up capable is migrated
+automatically: what you have becomes the public `Main` group, each account gets
+a private group, and agents restart one at a time. A banner shows progress. Once
+migration completes, private and restricted agents run as their own non-root
+user, and `Main` agents run as a shared non-root `main` user. Until migration
+completes (or if it fails), agents keep running as before, so the non-root
+guarantee does not yet hold for them. On a **brand-new** instance one migration
+step — seeding the shared Claude credential — can only run once you have signed
+in to Claude, which happens after boot; the banner stays up until then and the
+migration **finishes on its own the moment you sign in** (no restart needed).
+**One-time provisioning:** isolated-group agents authenticate with a
+subscription token injected into their environment, not a shared credential
+file. Until it is set, group spawns are refused with a message naming this step,
+and the cockpit shows a red "no subscription token" banner. Provide it from the
+cockpit itself — **no shell needed**: as an admin, click **Provide token** on
+that banner (or **Replace subscription token…** in the version menu to rotate
+it), authorise on your Claude subscription in the browser, and paste the code
+back; the server mints and stores it. From Telegram, `/mttoken` then
+`/mtcode <code>` do the same. The token is captured and vaulted server-side and
+is never shown. It is valid for about a year; re-run the card (or `/mttoken`)
+before it expires. The shell path still works as a fallback: `claude setup-token`
+and store the result as the vault secret `MT_CLAUDE_OAUTH_TOKEN`.
+
+Telegram stays single-owner, and there are no
+disk quotas yet. Design: `docs/superpowers/specs/2026-10-29-multi-tenant-scoped-isolation-design.md`.
+
 ### Exposing it beyond this machine
 
 The cockpit runs arbitrary commands on the host by design, so it binds

package/context/agents-skill/SKILL.md

@@ -31,6 +31,8 @@ and automatically starts the shadok-ai server when it is not running (port
 | `stop <id>` | ends the session (for ALL its clients) |
 | `screen <id>` | raw TUI screen (debug) |
 | `profile-prompt "<text>" [--name NAME] [--readonly]` | rewrites a profile's **system prompt**: your own by default; any of them (and creation with `--name`) under the lead profile |
+| `talk-handle` | prints **your own** handle — the "here is a handle to me" you share so another agent can send you a letter → `{handle}` |
+| `talk <handle> "message"` | sends a one-way **letter** to the agent that handle points to → `{ok, delivered}`. A letter, NOT a drive: it is read in the recipient's own context and you get no transcript back (see below) |
 
 ## Choosing a profile (`--profile`)
 
@@ -113,6 +115,36 @@ time, and the information comes to you.
 `--parent none` spawns an agent deliberately unattached; `--parent <id>`
 attaches it elsewhere.
 
+## Talking across groups: a letter, not a remote control (`talk`)
+
+When agents belong to different **groups** (teams sharing one cockpit), you
+cannot `prompt`/`drive` another group's agent — see/drive stay to your own group
+and to public ones. `talk` is the one narrow, consensual exception: you send a
+one-way **letter** the recipient handles in ITS OWN context, under its own
+guardrails. You never receive its transcript, stream or files back — `talk`
+returns only that the letter was accepted and delivered.
+
+The ACL, enforced server-side:
+
+- an agent in a **public** group — messageable freely, no handle needed;
+- an agent in another **restricted** group — ONLY if you hold its **handle** (an
+  opaque token it shared with you). There is no roster to browse: you can only
+  write to an agent whose handle reached you out of band;
+- an agent in a **private** group — **sealed inbound**: no letter gets in, even
+  with a handle. (But a private-group agent may still send OUTWARD.)
+
+To let someone write to you, give them your handle:
+
+```bash
+node ~/.claude/skills/shadok-ai-agents/pilotctl.mjs talk-handle      # → {"handle":"…"}
+# share that string (a human or a prompt relays it), then they run:
+node ~/.claude/skills/shadok-ai-agents/pilotctl.mjs talk <handle> "please review PR 42"
+```
+
+There is no automatic reply channel — if you want an answer, include YOUR handle
+inside the message. (In mono-tenant / single-team cockpits everything is one
+public commons, so `talk` is simply unrestricted.)
+
 ## Being prompted BY another agent
 
 The other direction: a prompt from an agent arrives under a context header

package/context/agents-skill/pilotctl.mjs

@@ -567,6 +567,50 @@ async function cmdProfilePrompt(text, flags) {
   return out;
 }
 
+// Cross-group TALK: send another agent a one-way LETTER, the sanctioned
+// server-mediated channel (there is no native SendMessage). This is NOT a drive:
+// the recipient reads the message in its OWN context under its own guardrails,
+// and you never receive its transcript/stream back — the call returns only that
+// the letter was accepted and dispatched.
+//
+// ACL (enforced server-side): a PUBLIC-group agent is messageable freely; an
+// agent in another RESTRICTED group only if you hold its HANDLE (an opaque token
+// it shared — there is no roster to browse); a PRIVATE group is SEALED inbound.
+// A private-group agent may still send OUTWARD.
+//
+// `handle` identifies the recipient. Get your OWN handle to share with
+// `pilotctl talk-handle`; obtaining someone else's is out of band (a human or a
+// prompt relays it) — pilotctl deliberately offers no way to enumerate handles.
+async function cmdTalk(handle, message) {
+  const key = process.env.SHADOK_SESSION_KEY;
+  if (!key) throw new Error("no SHADOK_SESSION_KEY in env — not running as a piloted agent");
+  if (!handle) throw new Error("usage: pilotctl talk <handle> <message>");
+  if (!message || !message.trim()) throw new Error("a message is required");
+  const r = await fetch(`${httpBase()}/talk`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...authHeaders() },
+    body: JSON.stringify({ key, handle, message }),
+  });
+  const out = await r.json();
+  if (!r.ok) throw new Error(out.error ?? `HTTP ${r.status}`);
+  return out;
+}
+
+// Your OWN talk handle — the "here is a handle to me" an agent shares so another
+// agent can send it a letter. Scoped to yourself by the session key: there is no
+// way to mint or look up someone else's.
+async function cmdTalkHandle() {
+  const key = process.env.SHADOK_SESSION_KEY;
+  if (!key) throw new Error("no SHADOK_SESSION_KEY in env — not running as a piloted agent");
+  const r = await fetch(`${httpBase()}/talk/handle`, {
+    method: "GET",
+    headers: { ...authHeaders() },
+  });
+  const out = await r.json();
+  if (!r.ok) throw new Error(out.error ?? `HTTP ${r.status}`);
+  return out;
+}
+
 async function cmdScreen(id, flags) {
   await ensureServer();
   const st = readState(id);
@@ -579,7 +623,7 @@ async function cmdScreen(id, flags) {
 }
 
 const HELP =
-  "usage: pilotctl <spawn|prompt|dialog|choose|toggle|confirm|freetext|list|diff|stop|screen|profile-prompt|peer> …\n" +
+  "usage: pilotctl <spawn|prompt|dialog|choose|toggle|confirm|freetext|list|diff|stop|screen|profile-prompt|talk|talk-handle|peer> …\n" +
   "       add --peer <alias> to any command to run it against another instance's agents\n" +
   "       pilotctl peer <add <alias> <url> <ticket> [--token]|list|rm <alias>>";
 
@@ -685,6 +729,10 @@ export async function run(argv) {
       return cmdScreen(pos[0], flags);
     case "profile-prompt":
       return cmdProfilePrompt(pos[0], flags);
+    case "talk":
+      return cmdTalk(pos[0], pos[1]);
+    case "talk-handle":
+      return cmdTalkHandle();
     default:
       throw new Error(HELP);
   }

package/context/agents-skill/test/mock-server.mjs

@@ -8,15 +8,28 @@ export function startMockServer(script = {}) {
   // Cookie headers seen on HTTP requests and on the WS upgrade — lets a test
   // assert pilotctl presents the SHADOK_AUTH cookie when a password is set.
   const cookies = { http: [], ws: [] };
+  // Per-route HTTP requests seen, with their parsed JSON body and the session-key
+  // header — lets a test assert what pilotctl actually sent (e.g. `talk`).
+  const http_ = [];
   const app = http.createServer((req, res) => {
     if (req.headers.cookie) cookies.http.push(req.headers.cookie);
-    res.setHeader("content-type", "application/json");
-    if (req.url.startsWith("/sessions")) return res.end(JSON.stringify(script.sessions ?? []));
-    if (req.url.startsWith("/diff"))
-      return res.end(
-        JSON.stringify(script.diff ?? { status: "", diff: "", branch: null, error: "no such session" }),
-      );
-    res.end("{}");
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => {
+      const raw = Buffer.concat(chunks).toString("utf8");
+      let body;
+      try { body = raw ? JSON.parse(raw) : undefined; } catch { body = raw; }
+      http_.push({ method: req.method, url: req.url, body, sessionKey: req.headers["x-shadok-session-key"] });
+      res.setHeader("content-type", "application/json");
+      if (req.url.startsWith("/sessions")) return res.end(JSON.stringify(script.sessions ?? []));
+      if (req.url.startsWith("/diff"))
+        return res.end(
+          JSON.stringify(script.diff ?? { status: "", diff: "", branch: null, error: "no such session" }),
+        );
+      if (req.url.startsWith("/talk/handle")) return res.end(JSON.stringify(script.talkHandle ?? { handle: "H" }));
+      if (req.url.startsWith("/talk")) return res.end(JSON.stringify(script.talk ?? { ok: true, delivered: "abcd" }));
+      res.end("{}");
+    });
   });
   const wss = new WebSocketServer({ server: app, path: "/ws" });
   const received = [];
@@ -33,6 +46,7 @@ export function startMockServer(script = {}) {
       resolve({
         port: app.address().port,
         received,
+        http: http_,
         cookies,
         close: () => new Promise((r) => { wss.close(); app.close(r); }),
       }),

package/context/agents-skill/test/talk.test.mjs

@@ -0,0 +1,48 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { startMockServer } from "./mock-server.mjs";
+
+process.env.SHADOK_STATE_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "pilotctl-talk-"));
+process.env.SHADOK_NO_HOLDER = "1";
+process.env.SHADOK_NO_AUTOSTART = "1";
+const { run } = await import("../pilotctl.mjs");
+
+test("talk without a session key is refused (not running as a piloted agent)", async () => {
+  delete process.env.SHADOK_SESSION_KEY;
+  await assert.rejects(() => run(["talk", "H", "hi"]), /SHADOK_SESSION_KEY/);
+});
+
+test("talk POSTs the session key, handle and message, and returns the server's reply", async () => {
+  const mock = await startMockServer({ talk: { ok: true, delivered: "ef01" } });
+  process.env.SHADOK_PORT = String(mock.port);
+  process.env.SHADOK_SESSION_KEY = "sk-key-123";
+  try {
+    const r = await run(["talk", "handle-xyz", "please review PR 42"]);
+    assert.deepEqual(r, { ok: true, delivered: "ef01" });
+    const call = mock.http.find((h) => h.url === "/talk" && h.method === "POST");
+    assert.ok(call, "pilotctl did not POST /talk");
+    assert.equal(call.sessionKey, "sk-key-123", "the session key header must be sent");
+    assert.equal(call.body.handle, "handle-xyz");
+    assert.equal(call.body.message, "please review PR 42");
+  } finally {
+    await mock.close();
+  }
+});
+
+test("talk-handle returns the caller's own handle", async () => {
+  const mock = await startMockServer({ talkHandle: { handle: "my-handle" } });
+  process.env.SHADOK_PORT = String(mock.port);
+  process.env.SHADOK_SESSION_KEY = "sk-key-123";
+  try {
+    const r = await run(["talk-handle"]);
+    assert.deepEqual(r, { handle: "my-handle" });
+    const call = mock.http.find((h) => h.url.startsWith("/talk/handle"));
+    assert.ok(call, "pilotctl did not GET /talk/handle");
+    assert.equal(call.sessionKey, "sk-key-123");
+  } finally {
+    await mock.close();
+  }
+});

package/context/ledger-skill/SKILL.md

@@ -115,6 +115,21 @@ node ~/.claude/skills/shadok-ledger/ledger.mjs record \
   --id <id> --status resolved --note "<one line>"
 ```
 
+## Who sees a row: your group by default, everyone with `--public`
+
+On an instance with several groups, a row you record is **private to your
+group**: only agents of your group see it in `check`, `list` and the pushed
+block. That is the safe default — forgetting a flag can never leak anything. To
+share a resolution with every group, say so on purpose:
+
+```
+… record --entity "<name>" --status resolved --public
+```
+
+It is the twin of dropping a file into `~/shared/` to make it public. Publish
+only what is meant for the other groups. `--id <id> --public` publishes an
+existing row. (On a single-group instance nothing changes.)
+
 ## To consult the whole table
 
 ```

package/context/ledger-skill/ledger-core.d.mts

@@ -12,12 +12,14 @@ export interface LedgerCoreRow {
   source?: string;
   updatedAt?: number;
   verifiedAt?: number;
+  scope?: "group" | "public";
 }
 export type LedgerKind = "task" | "fact" | "decision";
 export const KINDS: LedgerKind[];
 export const LABEL_MAX: number;
 export function normEntity(s: unknown): string;
 export function normKind(k: unknown): LedgerKind | null;
+export function normScope(sc: unknown): "group" | "public" | null;
 export function rowKind(entry: unknown): LedgerKind;
 export function resolveId<T extends LedgerCoreRow>(entries: T[], idOrPrefix: unknown): T | null;
 export function upsertEntry<T extends LedgerCoreRow>(

package/context/ledger-skill/ledger-core.mjs

@@ -86,6 +86,21 @@ export function rowKind(entry) {
   return normEntity(entry?.status) === "decided" ? "decision" : "task";
 }
 
+/**
+ * A row's SCOPE: `group` (visible to the writer's own group only) or `public`
+ * (the commons, every group). The DIRECTION OF THE DEFAULT is the invariant:
+ * absent means `group`, so forgetting a flag can only ever keep something
+ * private. Public-by-default would reopen the cross-group leak on the first
+ * oversight — publishing is a deliberate act (`--public`), the twin of dropping
+ * a file into `~/shared/`.
+ */
+export function normScope(sc) {
+  const s = String(sc ?? "").trim().toLowerCase();
+  if (!s) return null;
+  if (s !== "group" && s !== "public") throw new Error(`unknown scope "${sc}" — use group or public`);
+  return s;
+}
+
 /**
  * Upsert a row, two ways:
  *  - `patch.id` present → UPDATE that exact row in place (resolved via resolveId),
@@ -114,6 +129,7 @@ export function rowKind(entry) {
  * was last observed, which is the truth and makes the migration lazy, per row.
  */
 export function upsertEntry(entries, patch, now, newId) {
+  const scope = normScope(patch.scope);
   const kind = normKind(patch.kind); // refuses an unknown kind before anything is written
   const statusGiven = patch.status != null && String(patch.status).trim() !== "";
 
@@ -131,7 +147,7 @@ export function upsertEntry(entries, patch, now, newId) {
         ? KIND_STATUS[kind]
         : cur.status;
     const edited =
-      statusGiven || kind != null || patch.note != null || patch.source != null || patch.entity != null;
+      statusGiven || kind != null || patch.note != null || patch.source != null || patch.entity != null || scope != null;
     const observed = statusGiven || patch.verified === true || status !== cur.status;
     const row = {
       id: cur.id,
@@ -139,6 +155,7 @@ export function upsertEntry(entries, patch, now, newId) {
         patch.entity != null && String(patch.entity).trim() ? String(patch.entity).trim() : cur.entity,
       status,
       ...(effKind ? { kind: effKind } : {}),
+      scope: scope ?? normScope(cur.scope) ?? "group",
       ...((patch.note ?? cur.note) ? { note: String(patch.note ?? cur.note).trim() } : {}),
       ...((patch.source ?? cur.source) ? { source: String(patch.source ?? cur.source).trim() } : {}),
       updatedAt: edited ? now : (cur.updatedAt ?? now),
@@ -160,6 +177,7 @@ export function upsertEntry(entries, patch, now, newId) {
     entity: String(patch.entity).trim(),
     status,
     ...(effKind ? { kind: effKind } : {}),
+    scope: scope ?? normScope(existing?.scope) ?? "group",
     ...(patch.note ? { note: String(patch.note).trim() } : {}),
     ...(patch.source ? { source: String(patch.source).trim() } : {}),
     updatedAt: now,

package/context/ledger-skill/ledger.mjs

@@ -2,34 +2,52 @@
 // shadok-ledger CLI — a tiny state table so agents verify a status before they
 // assert or act on it, and record what they resolve/decide.
 //
-// Store: the PER-INSTANCE ledger. The server hands each agent the exact path in
-// SHADOK_LEDGER_FILE at spawn (an agent's own cwd is a worktree, not the launch
-// dir, so it cannot derive it); a hand-run CLI with no env falls back to the
-// legacy global file. See SKILL.md and the design spec. No server involved.
+// Store: ONE ledger table per instance, owned by the server. On an instance,
+// `record`/`check`/`list` go THROUGH the server (POST /ledger/record, GET
+// /ledger), authenticated with the per-session key — exactly like the
+// `shadok-secrets` skill reaches the vault. The server stamps the row's
+// AUTHORING GROUP from the session (never from here) and filters reads to that
+// group ∪ public, so a group's private rows never leak and no write crosses the
+// OS-user wall (the file lives 0600 in the server HOME).
+//
+// FALLBACK: with no server reachable (a hand-run CLI, or a mono-tenant instance
+// with no port/key), it reads and writes the local file directly —
+// SHADOK_LEDGER_FILE if the server handed one, else the legacy global file.
+// Nothing about the single-group / off-server case changes.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import crypto from "node:crypto";
 import { upsertEntry, searchEntries, ageDays, resolveId, normEntity, rowKind, KINDS, LABEL_MAX } from "./ledger-core.mjs";
 
+const PORT = (process.env.SHADOK_PORT || "").trim();
+const KEY = (process.env.SHADOK_SESSION_KEY || "").trim();
+const AUTH = (process.env.SHADOK_AUTH || "").trim();
+// On-server: a port AND a session key. The key is what proves WHICH agent calls,
+// and it is what the server scopes the authoring group by — without it there is
+// no identity, so we fall back to the local file.
+const useServer = !!PORT && !!KEY;
+const BASE = `http://127.0.0.1:${PORT}`;
+const TIMEOUT_MS = 15_000;
+
 const FILE =
   (process.env.SHADOK_LEDGER_FILE || "").trim() ||
   path.join(os.homedir(), ".shadok-ai", "ledger.json");
 
-function load() {
+function loadFile(file) {
   try {
-    const j = JSON.parse(fs.readFileSync(FILE, "utf8"));
+    const j = JSON.parse(fs.readFileSync(file, "utf8"));
     return Array.isArray(j) ? j : [];
   } catch {
     return []; // absent or unreadable → empty table, never a crash
   }
 }
 
-function save(rows) {
-  fs.mkdirSync(path.dirname(FILE), { recursive: true });
-  const tmp = FILE + ".tmp";
+function saveFile(file, rows) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = file + ".tmp";
   fs.writeFileSync(tmp, JSON.stringify(rows, null, 2), { mode: 0o600 });
-  fs.renameSync(tmp, FILE); // atomic: a concurrent reader never sees half a file
+  fs.renameSync(tmp, file); // atomic: a concurrent reader never sees half a file
 }
 
 /** A short, unique handle (4 hex): quotable from the pushed ledger block. */
@@ -42,9 +60,44 @@ function mintId(rows) {
   return crypto.randomBytes(4).toString("hex");
 }
 
+/** Call the server. Exits with a clear message on a transport/HTTP failure —
+ *  the same shape as the secrets skill. */
+async function api(method, p, body) {
+  let res;
+  try {
+    res = await fetch(BASE + p, {
+      method,
+      headers: {
+        "content-type": "application/json",
+        ...(AUTH ? { Cookie: AUTH } : {}),
+        // The durable credential: the cookie in the env expires after a week,
+        // the session key does not (invariant 33).
+        ...(KEY ? { "x-shadok-session-key": KEY } : {}),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch (e) {
+    console.error(`cannot reach the cockpit on ${BASE}: ${e.message}`);
+    process.exit(1);
+  }
+  const raw = await res.text();
+  if (!res.ok) {
+    let msg = raw.slice(0, 300);
+    try {
+      msg = JSON.parse(raw).error ?? msg;
+    } catch {
+      /* non-JSON body — keep the raw slice */
+    }
+    console.error(`ledger API error ${res.status}: ${msg}`);
+    process.exit(1);
+  }
+  return raw ? JSON.parse(raw) : {};
+}
+
 /** Flags that take NO value, listed rather than guessed: inferring "the next arg
  *  starts with -- so this one is a boolean" would misread `--note "--foo"`. */
-const BOOL_FLAGS = new Set(["verified"]);
+const BOOL_FLAGS = new Set(["verified", "public"]);
 
 /** `--key value` pairs → object. Values may be quoted by the shell already. */
 function parseFlags(args) {
@@ -70,23 +123,29 @@ function fmt(e, now) {
   // noise on every line. The two that change how a status must be READ are named.
   const tag = kind === "task" ? "" : ` · ${kind}`;
   const handle = e.id ? `[${e.id}] ` : "";
-  const head = `• ${handle}${e.entity} — ${e.status}${tag} (${stamp}${e.source ? ` · ${e.source}` : ""})`;
+  const pub = e.scope === "public" ? " · public" : "";
+  const head = `• ${handle}${e.entity} — ${e.status}${tag}${pub} (${stamp}${e.source ? ` · ${e.source}` : ""})`;
   return e.note ? `${head}\n    ${e.note}` : head;
 }
 
-const [cmd, ...rest] = process.argv.slice(2);
-const now = Date.now();
+/** The rows a read works over: on-server, the server-scoped table (own group ∪
+ *  public); off-server, the local file. */
+async function visibleRows() {
+  if (useServer) return (await api("GET", "/ledger")).entries ?? [];
+  return loadFile(FILE);
+}
 
-if (cmd === "check") {
+async function doCheck(rest) {
   const q = rest.join(" ").trim();
   if (!q) {
     console.error('usage: ledger check "<topic or entity>"');
     process.exit(2);
   }
+  const now = Date.now();
   // Two tiers, and the difference is the whole point: `strong` answers the
   // question, `weak` merely shares words with it. Collapsing them would make a
   // loosely-related row read as a status — the opposite of what this gates.
-  const { strong, weak } = searchEntries(load(), q);
+  const { strong, weak } = searchEntries(await visibleRows(), q);
   if (strong.length) {
     console.log(strong.map((e) => fmt(e, now)).join("\n"));
   } else {
@@ -99,51 +158,75 @@ if (cmd === "check") {
       console.log(weak.map((e) => fmt(e, now)).join("\n"));
     }
   }
-} else if (cmd === "record") {
+}
+
+async function doList() {
+  const now = Date.now();
+  const rows = searchEntries(await visibleRows(), "").strong;
+  console.log(rows.length ? rows.map((e) => fmt(e, now)).join("\n") : "(ledger empty)");
+}
+
+async function doRecord(rest) {
   const f = parseFlags(rest);
   // Two shapes: create/supersede by --entity (+ --status), or update an existing
   // row by its --id handle (change any of status/note/source; entity optional).
   const byId = f.id != null && String(f.id).trim();
   const idHasNoFields =
     f.status == null && f.note == null && f.source == null && f.entity == null &&
-    f.kind == null && f.verified == null;
+    f.kind == null && f.verified == null && f.public == null;
   // A fact or a decision has no lifecycle, so `--kind` stands in for `--status`:
   // requiring one would only invite an invented word.
   const hasStatus = !!f.status || !!f.kind;
   if (byId ? idHasNoFields : !f.entity || !hasStatus) {
     console.error(
-      'usage: ledger record --entity "<name>" --status <resolved|open|in-progress|decided> [--note "<line>"] [--source "<ref>"]\n' +
+      'usage: ledger record --entity "<name>" --status <resolved|open|in-progress|decided> [--note "<line>"] [--source "<ref>"] [--public]\n' +
         `   or: ledger record --entity "<name>" --kind <${KINDS.join("|")}> [--note "<line>"] [--source "<ref>"]\n` +
-        '   or: ledger record --id <handle> [--status <…>] [--kind <…>] [--note "<line>"] [--source "<ref>"]\n' +
+        '   or: ledger record --id <handle> [--status <…>] [--kind <…>] [--note "<line>"] [--source "<ref>"] [--public]\n' +
         '   or: ledger record --id <handle> --verified     (still true/current — nothing else changed)',
     );
     process.exit(2);
   }
-  const rows0 = load();
-  let rows;
-  try {
-    rows = upsertEntry(
-      rows0,
-      {
-        id: f.id,
-        entity: f.entity,
-        status: f.status,
-        kind: f.kind,
-        verified: f.verified === true,
-        note: f.note,
-        source: f.source,
-      },
-      now,
-      mintId(rows0),
-    );
-  } catch (e) {
-    console.error(String(e?.message ?? e));
-    process.exit(2);
+
+  const patch = {
+    id: f.id,
+    entity: f.entity,
+    status: f.status,
+    kind: f.kind,
+    verified: f.verified === true,
+    note: f.note,
+    source: f.source,
+    // Group-private unless asked: `--public` is the only way out.
+    public: f.public === true ? true : undefined,
+  };
+
+  let row;
+  if (useServer) {
+    // The server stamps the authoring group (from the session) and scopes the
+    // upsert to it, so a cross-group clobber is impossible by construction.
+    row = (await api("POST", "/ledger/record", patch)).row;
+  } else {
+    // Off-server fallback: write the local file directly (mono-tenant / hand-run).
+    const rows0 = loadFile(FILE);
+    let next;
+    try {
+      next = upsertEntry(
+        rows0,
+        { ...patch, scope: patch.public === true ? "public" : undefined },
+        Date.now(),
+        mintId(rows0),
+      );
+    } catch (e) {
+      console.error(String(e?.message ?? e));
+      process.exit(2);
+    }
+    saveFile(FILE, next);
+    row = byId ? resolveId(next, f.id) : next.find((r) => normEntity(r.entity) === normEntity(f.entity));
   }
-  save(rows);
-  const row = byId ? resolveId(rows, f.id) : rows.find((r) => normEntity(r.entity) === normEntity(f.entity));
+
   const k = rowKind(row);
-  console.log(`recorded: ${row.entity} — ${row.status}${k === "task" ? "" : ` · ${k}`} [${row.id}]`);
+  console.log(
+    `recorded: ${row.entity} — ${row.status}${k === "task" ? "" : ` · ${k}`}${row.scope === "public" ? " · public" : ""} [${row.id}]`,
+  );
   // Say it, don't enforce it: the row is already saved (a refused write is a
   // lost fact) and the full label stays in the table. But the delta pushed to
   // siblings only carries the first LABEL_MAX characters of it, and a label
@@ -154,9 +237,16 @@ if (cmd === "check") {
         `Only the first ${LABEL_MAX} reach the ⟦ledger⟧ block your siblings are pushed.`,
     );
   }
+}
+
+const [cmd, ...rest] = process.argv.slice(2);
+
+if (cmd === "check") {
+  await doCheck(rest);
+} else if (cmd === "record") {
+  await doRecord(rest);
 } else if (cmd === "list") {
-  const rows = searchEntries(load(), "").strong;
-  console.log(rows.length ? rows.map((e) => fmt(e, now)).join("\n") : "(ledger empty)");
+  await doList();
 } else {
   console.error("usage: ledger <check|record|list> …");
   process.exit(2);

package/dist/accounts.d.ts

@@ -155,3 +155,19 @@ export declare function promptAuthor(origin: string | undefined, sessionName: st
 export declare function signSessionKey(sessionId: string, secret: Buffer): string;
 /** Pure: the session id a key attests to, or null if it does not verify. */
 export declare function readSessionKey(key: string, secret: Buffer): string | null;
+/**
+ * A shareable TALK HANDLE for a session — an opaque token that lets ANOTHER
+ * agent address a one-way LETTER to this one (cross-group talk, `src/talk.ts`),
+ * and nothing more.
+ *
+ * It is DELIBERATELY NOT a session key. `signSessionKey` authenticates AS the
+ * agent and can DRIVE it; a handle must only ever resolve to "who to deliver a
+ * letter to", leaving the talk ACL to decide if the letter may pass. They share
+ * the id-inside-the-token shape but are DOMAIN-SEPARATED (`talk:` vs `session:`
+ * in the HMAC input), so a handle can never be replayed as a session key and a
+ * leaked session key is not a valid handle — a handle shared freely grants no
+ * drive capability.
+ */
+export declare function signTalkHandle(sessionId: string, secret: Buffer): string;
+/** Pure: the session id a talk handle points to, or null if it does not verify. */
+export declare function readTalkHandle(handle: string, secret: Buffer): string | null;