@saadnvd1/agent-os 0.3.698 → 0.3.715

package/lib/peer/rpc-server.ts

@@ -15,7 +15,10 @@
  * Refusals before decryption are plain and fixed (`bad envelope`, `bad
  * signature`, `stale`, `replay`, `busy`). An unknown sender, a suspended one
  * and a bad signature all read `bad signature`, so a stranger can't tell
- * which machines are linked here; the audit keeps the difference. Everything
+ * which machines are linked here; the audit keeps the difference. The one
+ * exception is a machine unlinked here, proven by the key it was pinned
+ * with: it gets 403 `unknown peer`, signed (unlinked-proof.ts), so it can
+ * show that it was unlinked. Everything
  * after is inside the envelope,
  * always HTTP 200, so whoever carries the traffic never learns the route or
  * its status.
@@ -45,7 +48,14 @@ import {
   type BoxKey,
   type Identity,
 } from "./keys";
-import { hasActivePin, pinForMachine, type PeerPin } from "./links";
+import {
+  hasActivePin,
+  hasRecentUnlinked,
+  pinForMachine,
+  unlinkedMachine,
+  type PeerPin,
+} from "./links";
+import { UNLINKED_PROOF_HEADER, signUnlinked } from "./unlinked-proof";
 import { sqliteNonceStore } from "./nonce-store";
 import { createReplayGuard, type ReplayGuard } from "./replay";
 import {
@@ -75,7 +85,11 @@ export interface RpcDeps {
   identity: () => Identity | null;
   boxKey: () => BoxKey;
   pinForMachine: (machineId: string) => PeerPin | null;
-  /** False while no link is active: the route is closed to everyone. */
+  /** A machine unlinked here lately: the key it was pinned with. */
+  unlinked?: (
+    machineId: string
+  ) => { signPub: string; hostId: string | null } | null;
+  /** False while no link is active or recently unlinked: the route is closed to everyone. */
   anyActive: () => boolean;
   replay: ReplayGuard;
   dispatch: (d: Dispatch) => Promise<PeerResponse>;
@@ -125,6 +139,10 @@ export async function handlePeerRpc(
   const self = deps.identity();
   let fromMachine: string | null = null;
   let pin: PeerPin | null = null;
+  // An unlinked sender whose header its old key proved, and its nonce.
+  let unlinkedHost: string | null = null;
+  let viaUnlinked = false;
+  let provenUnlinked: string | null = null;
   const audit = (
     outcome: Outcome,
     status: number,
@@ -133,7 +151,7 @@ export async function handlePeerRpc(
     bytes = 0
   ) =>
     deps.audit({
-      hostId: pin?.hostId ?? null,
+      hostId: pin?.hostId ?? unlinkedHost,
       machineId: fromMachine,
       direction: "in",
       method,
@@ -144,6 +162,19 @@ export async function handlePeerRpc(
       outcome,
     });
   const refuse = (refusal: Refusal): null => {
+    if (refusal === "unknown_peer" && provenUnlinked && self && fromMachine) {
+      audit("unknown_peer", 403);
+      res.setHeader(
+        UNLINKED_PROOF_HEADER,
+        signUnlinked(self.signKey, {
+          from: self.machineId,
+          to: fromMachine,
+          nonce: provenUnlinked,
+        })
+      );
+      plain(res, 403, "unknown peer");
+      return null;
+    }
     const [status, text, outcome] = REFUSED[refusal];
     audit(outcome, status);
     plain(res, status, text);
@@ -161,6 +192,18 @@ export async function handlePeerRpc(
       : found.state !== "active"
         ? "suspended"
         : null;
+    if (!found) {
+      const gone = deps.unlinked?.(machineId);
+      if (gone)
+        try {
+          const key = signPublic(gone.signPub);
+          unlinkedHost = gone.hostId;
+          viaUnlinked = true;
+          return key;
+        } catch {
+          // Unreadable: a decoy, like any stranger.
+        }
+    }
     if (!found || hidden) return DECOY_KEY;
     try {
       return signPublic(found.signPub);
@@ -177,6 +220,13 @@ export async function handlePeerRpc(
     return null;
   };
 
+  // The one nonce the header claimed: the whole envelope must carry it.
+  let claimed: string | null = null;
+  const spent: ReplayGuard = {
+    check: (peer, nonce) =>
+      claimed !== null && claimed === `${peer}:${nonce}` ? "ok" : "replay",
+  };
+
   if (!deps.anyActive()) return plain(res, 404, "not found");
   const ticket = deps.budget.open(sourceOf(req));
   if (!ticket) return void refuse("busy");
@@ -193,6 +243,21 @@ export async function handlePeerRpc(
             return { refusal: "bad_sig" };
           const now = deps.now?.() ?? Date.now();
           if (Math.abs(now - header.ts) > SKEW_MS) return { refusal: "stale" };
+          // The nonce is spent the moment its header is proven, so a header
+          // seen on the wire can't be sent again with junk bodies to hold
+          // the sender's share while the first is still arriving.
+          const fresh = deps.replay.check(
+            header.from,
+            header.nonce,
+            header.ts,
+            now
+          );
+          if (fresh !== "ok") return { refusal: fresh };
+          if (viaUnlinked) {
+            provenUnlinked = header.nonce;
+            return { refusal: "unknown_peer" };
+          }
+          claimed = `${header.from}:${header.nonce}`;
           return { peer: header.from };
         },
         ticket,
@@ -209,7 +274,7 @@ export async function handlePeerRpc(
       self: self.machineId,
       boxKey: deps.boxKey().privateKey,
       signKeyFor,
-      replay: deps.replay,
+      replay: spent,
       now: deps.now?.(),
     });
   };
@@ -342,7 +407,8 @@ export function rpcDeps(port: number): RpcDeps {
     identity: () => currentIdentity(),
     boxKey: () => (box ??= loadBoxKey()),
     pinForMachine,
-    anyActive: hasActivePin,
+    unlinked: (machineId) => unlinkedMachine(machineId),
+    anyActive: () => hasActivePin() || hasRecentUnlinked(),
     replay: createReplayGuard({ store: sqliteNonceStore() }),
     dispatch: loopbackDispatch(port),
     audit: recordPeerCall,

package/lib/peer/unlink.ts

@@ -0,0 +1,62 @@
+/**
+ * Unlinking a machine linked through Connect, from either side. Here: the
+ * pin goes at once (links.ts dropPin), then the other machine is told with a
+ * signed POST /api/peer/unlink, best effort. There: the same call drops its
+ * pin and its Machines says "Unlinked by <this machine>". If that call never
+ * arrives, the other machine's next call here is answered with a signed
+ * "unknown peer" (rpc-server.ts), which does the same.
+ */
+
+import { deleteHost } from "../hosts";
+import { hostLink, type HostLink } from "../hosts/remote-api";
+import { peerCall } from "./client";
+import { dropPin, pinForHost } from "./links";
+
+export const UNLINKED_HERE = "Unlinked here";
+
+export interface UnlinkDeps {
+  tell: (link: HostLink) => Promise<unknown>;
+  remove: (hostId: string) => void;
+}
+
+const realDeps: UnlinkDeps = {
+  tell: (link) =>
+    peerCall(link, "/api/peer/unlink", { body: {}, timeout: 8_000 }),
+  remove: deleteHost,
+};
+
+export interface UnlinkResult {
+  name: string;
+  /** The other machine confirmed it dropped its side. */
+  told: boolean;
+  /** The machine left Machines here too (it held no sessions or projects). */
+  removed: boolean;
+}
+
+/** A person here unlinks it. Throws when it isn't linked through Connect. */
+export async function unlinkPeer(
+  hostId: string,
+  deps: UnlinkDeps = realDeps
+): Promise<UnlinkResult> {
+  const link = hostLink(hostId);
+  if (!link?.connect || !pinForHost(hostId))
+    throw new Error("That machine isn't linked through Connect.");
+  dropPin(hostId, { byPeer: false, reason: UNLINKED_HERE });
+  let told = false;
+  // A suspended link is refused there too; nothing would arrive.
+  if (link.connect.state === "active")
+    try {
+      await deps.tell(link);
+      told = true;
+    } catch {
+      // Best effort: its next call here is refused and says why.
+    }
+  let removed = false;
+  try {
+    deps.remove(hostId);
+    removed = true;
+  } catch {
+    // It still holds sessions or projects; it stays, unlinked.
+  }
+  return { name: link.hostName, told, removed };
+}

package/lib/peer/unlinked-proof.ts

@@ -0,0 +1,44 @@
+/**
+ * The one refusal that is signed: "unknown peer", sent to a machine that was
+ * unlinked here, bound to its own request's nonce. Only the key it had pinned
+ * for this machine verifies it, so whoever carries the traffic can't forge an
+ * unlink, and a replayed one never matches a new request.
+ */
+
+import crypto, { type KeyObject } from "crypto";
+
+export const UNLINKED_PROOF_HEADER = "x-agentos-peer-unlinked";
+const DOMAIN = "agentos-peer-unlinked-v1";
+
+interface Bound {
+  /** The machine refusing: the one that unlinked. */
+  from: string;
+  /** The caller, which it no longer knows. */
+  to: string;
+  /** The caller's request nonce, base64url. */
+  nonce: string;
+}
+
+const message = (o: Bound) =>
+  Buffer.from(`${DOMAIN}|${o.from}|${o.to}|${o.nonce}`);
+
+export const signUnlinked = (signKey: KeyObject, o: Bound): string =>
+  crypto.sign(null, message(o), signKey).toString("base64url");
+
+export function verifyUnlinked(
+  signPub: KeyObject,
+  o: Bound,
+  sig: string | null
+): boolean {
+  if (!sig || !/^[A-Za-z0-9_-]{86}$/.test(sig)) return false;
+  try {
+    return crypto.verify(
+      null,
+      message(o),
+      signPub,
+      Buffer.from(sig, "base64url")
+    );
+  } catch {
+    return false;
+  }
+}

package/lib/projects.ts

@@ -19,6 +19,7 @@ import {
   type DevServerType,
 } from "./db";
 import { resolveModelForAgent } from "./model-catalog";
+import { clearForeignGroup } from "./session-groups/assignSessions";
 import type { AgentType } from "./providers";
 
 const execAsync = promisify(exec);
@@ -312,7 +313,7 @@ export function getProjectSessions(projectId: string): Session[] {
 export function moveSessionToProject(
   sessionId: string,
   projectId: string
-): void {
+): { clearedGroup: string | null } {
   const to = getProject(projectId);
   const from = db
     .prepare(
@@ -321,7 +322,7 @@ export function moveSessionToProject(
     )
     .get(sessionId) as
     { workspace_id: string | null; own: string | null } | undefined;
-  db.transaction(() => {
+  return db.transaction(() => {
     queries.updateSessionProject(db).run(projectId, sessionId);
     // A project's session follows the project; one left in none keeps the
     // workspace it was in.
@@ -333,6 +334,8 @@ export function moveSessionToProject(
         : (from?.workspace_id ?? from?.own ?? null),
       sessionId
     );
+    // A group belongs to the workspace the session just left.
+    return { clearedGroup: clearForeignGroup(sessionId) };
   })();
 }
 

package/lib/schedules/when.ts

@@ -26,7 +26,7 @@ const UNIT_MS: Record<string, number> = {
   d: 86_400_000,
 };
 
-function duration(text: string): number | null {
+export function duration(text: string): number | null {
   let total = 0;
   const rest = text.replace(
     /(\d+(?:\.\d+)?|an?)\s*(minutes?|mins?|m|hours?|hrs?|h|days?|d)\b/g,

package/lib/security/auth.ts

@@ -18,6 +18,9 @@ export const DEVICE_COOKIE = "aos_device";
 export const DEVICE_HEADER = "x-agentos-device";
 export const TRUST_HEADER = "x-agentos-trust";
 export const REMOTE_HEADER = "x-agentos-remote";
+// Who sent it, for per-sender limits: the visitor's address on a Connect
+// request (lib/peer/rpc-intake sourceOf), an IPv6 address by its /64.
+export const SOURCE_HEADER = "x-agentos-source";
 // The rpc server's loopback hop (lib/peer/rpc-server): the per-boot secret,
 // and the linked machine it verified. Never trusted from anywhere else.
 export const PEER_INTERNAL_HEADER = "x-agentos-peer-internal";
@@ -81,12 +84,17 @@ const FORWARDING = new Set([
 const FORWARDING_PREFIXES = ["x-forwarded-", "cf-", "tailscale-"];
 
 // Reached without a token: the pairing page, what it needs to render, the
-// claim it posts, and a linked machine's rpc (its envelope is the proof). Exact paths, plus a few static asset folders whose
-// paths may only use plain characters (no traversal, no encoding).
+// claim it posts, a linked machine's rpc (its envelope is the proof) and
+// the pairing hellos (signed by a key the account lists). Exact paths, plus
+// a few static asset folders whose paths may only use plain characters (no
+// traversal, no encoding).
 const PUBLIC_EXACT = new Set([
   "/pair",
   "/api/pair/claim",
   "/api/peer/rpc",
+  "/api/peer/hello",
+  "/api/peer/hello/reveal",
+  "/api/peer/hello/status",
   "/manifest.webmanifest",
   "/manifest.json",
   "/favicon.ico",

package/lib/security/demo.ts

@@ -49,23 +49,30 @@ export function assertDemoSandbox(env: Env = process.env, home = os.homedir()) {
 // "projects/[id]"): Next serves the folder, so an id must never match them.
 // The test walks app/api and fails when one is missing here.
 export const STATIC_SIBLINGS = [
+  "account",
   "archived",
   "arrived",
   "availability",
   "browse",
+  "check",
   "clone",
   "connect",
   "detect",
   "done-idle",
   "draft",
   "ended",
+  "exchange",
   "held-replies",
   "import",
   "init",
+  "group",
   "init-script",
   "me",
   "items",
+  "link",
   "network",
+  "order",
+  "pending",
   "pdf",
   "preview",
   "queue",

package/lib/security/gate.ts

@@ -14,6 +14,7 @@ import {
   DEVICE_HEADER,
   TRUST_HEADER,
   REMOTE_HEADER,
+  SOURCE_HEADER,
   PEER_HEADER,
   PEER_INTERNAL_HEADER,
   type AuthPolicy,
@@ -25,6 +26,7 @@ import { tailscaleAddresses } from "./net";
 import { networkSetting } from "./network-settings";
 import { pairLocation } from "../session-url";
 import { peerSecret } from "../peer/internal";
+import { sourceOf } from "../peer/rpc-intake";
 
 // Interface addresses change rarely; don't re-read them on every request.
 let tailnetCache = { at: 0, ips: [] as string[] };
@@ -63,6 +65,7 @@ function decide(req: IncomingMessage, policy: AuthPolicy): AuthResult {
     delete req.headers[PEER_HEADER];
   const tunnel = isTunnelSocket(req.socket);
   req.headers[REMOTE_HEADER] = sourceLabel(req.socket.remoteAddress, tunnel);
+  req.headers[SOURCE_HEADER] = sourceOf(req);
   let result: AuthResult;
   try {
     result = authorize(

package/lib/session-groups/assignSessions.ts

@@ -0,0 +1,81 @@
+import { getDb } from "@/lib/db";
+import { liveGroup } from "./store";
+import { sessionWorkspaceId } from "./workspace";
+import { GroupError, type SessionGroup } from "./types";
+
+// The one place that checks the invariant: a session joins only a group of
+// its own workspace. Membership is a view choice, so it leaves updated_at
+// alone, like pinning.
+export function checkMember(sessionId: string, group: SessionGroup): void {
+  const workspaceId = sessionWorkspaceId(sessionId);
+  if (workspaceId === undefined)
+    throw new GroupError("not-found", "Session not found");
+  if ((workspaceId ?? null) !== (group.workspace_id ?? null))
+    throw new GroupError(
+      "workspace",
+      `"${group.name}" is a group of another workspace`
+    );
+}
+
+// Files sessions into a group, or out of any (groupId null). All or none.
+export function assignSessions(
+  sessionIds: readonly string[],
+  groupId: string | null
+): { moved: number } {
+  const ids = [...new Set(sessionIds)];
+  const group = groupId === null ? null : liveGroup(groupId);
+  const db = getDb();
+  return db.transaction(() => {
+    let moved = 0;
+    for (const id of ids) {
+      if (group) checkMember(id, group);
+      else if (sessionWorkspaceId(id) === undefined)
+        throw new GroupError("not-found", "Session not found");
+      moved += db
+        .prepare(
+          `UPDATE sessions SET session_group_id = ?
+           WHERE id = ? AND session_group_id IS NOT ?`
+        )
+        .run(group?.id ?? null, id, group?.id ?? null).changes;
+    }
+    return { moved };
+  })();
+}
+
+// For a session that is starting: its group may have been deleted, or its
+// workspace changed, since it was asked for. Starting must not fail over a
+// view choice, so it just starts ungrouped.
+export function fileInGroup(sessionId: string, groupId: string): void {
+  try {
+    assignSessions([sessionId], groupId);
+  } catch (err) {
+    if (!(err instanceof GroupError)) throw err;
+  }
+}
+
+// A new session starts in the group of the one it came from (a worker from its
+// conductor, a fork or a fresh start from its source), when that group is
+// still live and in the new session's workspace.
+export function inheritGroup(fromSessionId: string, toSessionId: string): void {
+  const row = getDb()
+    .prepare(`SELECT session_group_id AS id FROM sessions WHERE id = ?`)
+    .get(fromSessionId) as { id: string | null } | undefined;
+  if (row?.id) fileInGroup(toSessionId, row.id);
+}
+
+// Leaving a workspace leaves its groups (a project move into another one).
+export function clearForeignGroup(sessionId: string): string | null {
+  const row = getDb()
+    .prepare(
+      `SELECT g.id AS id, g.name AS name, g.workspace_id AS ws
+       FROM sessions s JOIN session_groups g ON g.id = s.session_group_id
+       WHERE s.id = ?`
+    )
+    .get(sessionId) as
+    { id: string; name: string; ws: string | null } | undefined;
+  if (!row || (sessionWorkspaceId(sessionId) ?? null) === row.ws) return null;
+  getDb()
+    .prepare(`UPDATE sessions SET session_group_id = NULL WHERE id = ?`)
+    .run(sessionId);
+  return row.name;
+}

package/lib/session-groups/cli.ts

@@ -0,0 +1,61 @@
+import { getDb } from "@/lib/db";
+import { resolveReadable, readerScope } from "@/lib/bus/read-scope";
+import { assignSessions } from "./assignSessions";
+import { createGroup } from "./createGroup";
+import { listGroups } from "./store";
+import { updateGroup } from "./updateGroup";
+import { resolveGroup } from "./resolveGroup";
+import { GroupError } from "./types";
+
+export type GroupCommand =
+  | { action: "list" }
+  | { action: "new"; name: string }
+  | { action: "rename"; group: string; name: string }
+  | { action: "add"; group: string; sessions: string[] }
+  | { action: "rm"; sessions: string[] };
+
+// `aos group ...`: the caller's own workspace's groups, resolved the way
+// `aos read` resolves sessions, so it reaches nothing outside that scope.
+export function groupCommand(callerId: string, cmd: GroupCommand): string {
+  const scope = readerScope(callerId);
+  const ws = scope.workspaceId;
+  if (cmd.action === "list") return describe(ws, scope.label);
+  if (cmd.action === "new") {
+    const g = createGroup(ws, cmd.name);
+    return `created group "${g.name}" in your ${scope.label}`;
+  }
+  if (cmd.action === "rename") {
+    const from = resolveGroup(ws, cmd.group);
+    return `renamed "${from.name}" to "${updateGroup(from.id, { name: cmd.name }).name}"`;
+  }
+  if (!cmd.sessions.length)
+    throw new GroupError("invalid", "Name at least one session");
+  const target = cmd.action === "add" ? resolveGroup(ws, cmd.group) : null;
+  const ids = cmd.sessions.map((ref) => {
+    if (ref === "me") return callerId;
+    const found = resolveReadable(callerId, ref);
+    if (!found.ok) throw new GroupError("not-found", found.error);
+    return found.session.id;
+  });
+  assignSessions(ids, target?.id ?? null);
+  return target
+    ? `put ${ids.length} session${ids.length === 1 ? "" : "s"} in "${target.name}"`
+    : `took ${ids.length} session${ids.length === 1 ? "" : "s"} out of their group`;
+}
+
+function describe(workspaceId: string | null, label: string): string {
+  const groups = listGroups(workspaceId);
+  if (!groups.length) return `no groups in your ${label}`;
+  const counts = new Map(
+    (
+      getDb()
+        .prepare(
+          `SELECT session_group_id AS id, COUNT(*) AS n FROM sessions
+           WHERE session_group_id IS NOT NULL AND archived_at IS NULL
+           GROUP BY session_group_id`
+        )
+        .all() as { id: string; n: number }[]
+    ).map((r) => [r.id, r.n])
+  );
+  return groups.map((g) => `${g.name}  ·  ${counts.get(g.id) ?? 0}`).join("\n");
+}

package/lib/session-groups/createGroup.ts

@@ -0,0 +1,28 @@
+import { randomUUID } from "crypto";
+import { getDb } from "@/lib/db";
+import { cleanName, findGroup, groupByName } from "./store";
+import { GroupError, type SessionGroup } from "./types";
+
+// A new group goes to the bottom of its workspace's order. The name is
+// unique within the workspace, ignoring case.
+export function createGroup(
+  workspaceId: string | null,
+  name: unknown
+): SessionGroup {
+  const clean = cleanName(name);
+  const db = getDb();
+  if (
+    workspaceId &&
+    !db.prepare(`SELECT 1 FROM workspaces WHERE id = ?`).get(workspaceId)
+  )
+    throw new GroupError("not-found", "Workspace not found");
+  if (groupByName(workspaceId, clean))
+    throw new GroupError("duplicate", `There is already a group "${clean}"`);
+  const id = randomUUID();
+  db.prepare(
+    `INSERT INTO session_groups (id, workspace_id, name, sort_order)
+     VALUES (?, ?, ?, (SELECT COALESCE(MAX(sort_order) + 1, 0)
+       FROM session_groups WHERE COALESCE(workspace_id, '') = COALESCE(?, '')))`
+  ).run(id, workspaceId, clean, workspaceId);
+  return findGroup(id)!;
+}

package/lib/session-groups/index.ts

@@ -0,0 +1,21 @@
+export * from "./types";
+export {
+  groupNames,
+  listGroups,
+  findGroup,
+  groupByName,
+  liveGroup,
+} from "./store";
+export { createGroup } from "./createGroup";
+export { updateGroup } from "./updateGroup";
+export { reorderGroups } from "./reorderGroups";
+export { deleteGroup, restoreGroup } from "./removeGroup";
+export {
+  assignSessions,
+  checkMember,
+  clearForeignGroup,
+  fileInGroup,
+  inheritGroup,
+} from "./assignSessions";
+export { resolveGroup } from "./resolveGroup";
+export { sessionWorkspaceId } from "./workspace";

package/lib/session-groups/removeGroup.ts

@@ -0,0 +1,36 @@
+import { getDb } from "@/lib/db";
+import { findGroup, groupByName, liveGroup } from "./store";
+import { GroupError, type SessionGroup } from "./types";
+
+// Soft delete: members keep their session_group_id and the sidebar ignores a
+// deleted group, so they fall back to the status shelves and Undo (restore)
+// puts them back. Nothing is hard-deleted.
+export function deleteGroup(id: string): SessionGroup {
+  const group = liveGroup(id);
+  getDb()
+    .prepare(
+      `UPDATE session_groups SET deleted_at = datetime('now'),
+         updated_at = datetime('now') WHERE id = ?`
+    )
+    .run(id);
+  return group;
+}
+
+export function restoreGroup(id: string): SessionGroup {
+  const group = findGroup(id);
+  if (!group) throw new GroupError("not-found", "Group not found");
+  if (!group.deleted) return group;
+  // A new group took the name meanwhile.
+  if (groupByName(group.workspace_id, group.name))
+    throw new GroupError(
+      "duplicate",
+      `There is already a group "${group.name}"`
+    );
+  getDb()
+    .prepare(
+      `UPDATE session_groups SET deleted_at = NULL,
+         updated_at = datetime('now') WHERE id = ?`
+    )
+    .run(id);
+  return liveGroup(id);
+}

package/lib/session-groups/reorderGroups.ts

@@ -0,0 +1,31 @@
+import { getDb } from "@/lib/db";
+import { listGroups } from "./store";
+import { GroupError, type SessionGroup } from "./types";
+
+// Sets a workspace's group order. `ids` may name only some of them (a move
+// up or down sends the whole list; a stale list from another device leaves
+// newer groups at the end), but never one from another workspace.
+export function reorderGroups(
+  workspaceId: string | null,
+  ids: unknown
+): SessionGroup[] {
+  if (!Array.isArray(ids) || ids.some((i) => typeof i !== "string"))
+    throw new GroupError("invalid", "ids is a list of group ids");
+  const current = listGroups(workspaceId);
+  const known = new Set(current.map((g) => g.id));
+  const wanted = [...new Set(ids as string[])];
+  const stranger = wanted.find((i) => !known.has(i));
+  if (stranger)
+    throw new GroupError("workspace", "A group is not in this workspace");
+  const order = [
+    ...wanted,
+    ...current.map((g) => g.id).filter((i) => !wanted.includes(i)),
+  ];
+  const db = getDb();
+  const set = db.prepare(
+    `UPDATE session_groups SET sort_order = ?, updated_at = datetime('now')
+     WHERE id = ? AND sort_order != ?`
+  );
+  db.transaction(() => order.forEach((id, i) => set.run(i, id, i)))();
+  return listGroups(workspaceId);
+}

package/lib/session-groups/resolveGroup.ts

@@ -0,0 +1,19 @@
+import { groupByName, listGroups } from "./store";
+import { GroupError, type SessionGroup } from "./types";
+
+// A group named by a caller (`aos --group`, an orchestrator tool): it must
+// exist in that workspace, and the error lists the ones that do.
+export function resolveGroup(
+  workspaceId: string | null,
+  name: string
+): SessionGroup {
+  const found = groupByName(workspaceId, name);
+  if (found) return found;
+  const names = listGroups(workspaceId).map((g) => `"${g.name}"`);
+  throw new GroupError(
+    "not-found",
+    names.length
+      ? `No group "${name.trim()}" in this workspace. Groups: ${names.join(", ")}`
+      : `No group "${name.trim()}": this workspace has no groups`
+  );
+}