@quo-systems/dock 0.1.0 → 0.2.1

package/cli/daemon.ts

@@ -102,7 +102,7 @@ export const sidePath = (dir: string) => socketPath(dir, 'side');
 // them: `local`, for a side that reached side.sock, and `web`, for a human
 // who passed the exchange pages. Both are the daemon vouching for someone it
 // saw itself; a proof of either kind arriving any other way names no nonce.
-const NONCES = new Map<string, { kind: string; user: string; client: string; wake?: boolean }>();
+const NONCES = new Map<string, { kind: string; user: string; client: string; wake?: boolean; reach?: boolean }>();
 // A nonce is minted for one kind and honoured under that kind alone: a tab's
 // nonce offered as a `local` proof names no nonce, so a proof of a kind still
 // arrives only the one way that kind is made.
@@ -138,7 +138,7 @@ async function readAll(req: AsyncIterable<Buffer>): Promise<Buffer | undefined>
 // `user` and nothing is minted, so `wake`, the human's word that this
 // device may wake her others, is read the first time only; to change it,
 // remove the occupant and allow again. The one path for every side.
-export async function admit(hosted: Hosted, identity: string, kind: 'local' | 'web', wake = false): Promise<{ avatar?: Avatar; error?: string }> {
+export async function admit(hosted: Hosted, identity: string, kind: 'local' | 'web', wake = false, reach = false): Promise<{ avatar?: Avatar; error?: string }> {
   if (!/^[\w.-]+$/.test(identity) || identity === hosted.record.user || identity === 'desk') return { error: 'an identity is a word, and not a being of the ward' };
   const key = `avatar:${identity}`;
   let avatar = hosted.being(key) as Avatar | undefined;
@@ -148,7 +148,7 @@ export async function admit(hosted: Hosted, identity: string, kind: 'local' | 'w
     avatar = hosted.being(key) as Avatar;
   }
   const nonce = randomBytes(16).toString('hex');
-  NONCES.set(nonce, wake ? { kind, user: hosted.record.user, client: identity, wake: true } : { kind, user: hosted.record.user, client: identity });
+  NONCES.set(nonce, { kind, user: hosted.record.user, client: identity, ...(wake ? { wake: true } : {}), ...(reach ? { reach: true } : {}) });
   const entered = await avatar.enter({ ward: hosted.pk }, { kind, nonce });
   NONCES.delete(nonce);
   await hosted.save(); // the knock went through the ward's own door, which the harbor never sees
@@ -196,30 +196,43 @@ export async function serve(dir: string, options: Options = {}): Promise<Serving
       mountQuo(harbor, http, server, quo);
       const routes = options.routes ?? (await readRoutes(harbor.dir));
       const password = options.password ?? (() => process.env.QUO_OWNER_PASSWORD);
-      const main = harbor.wards.get('main');
       const here = `http://${http.host}:${http.port}`;
-      // the tab page: always, on the daemon's own door when no route names a public one
-      const tab = main ? tabPages(main, { quo: routes?.quo ?? `${here}/quo`, web: routes?.web ?? `${here}/web` }, password) : null;
+      // the worlds' pages: always, on the daemon's own door when no route names a public one
+      const tab = worldPages(harbor, { quo: routes?.quo ?? `${here}/quo`, web: routes?.web ?? `${here}/web` }, password);
       if (routes) {
-        // the MCP endpoint: a bearer names an identity, the identity names her avatar, the side runs beside her
-        mcp = main ? new McpHttp((identity) => admit(main, identity, 'web'), () => main.save()) : null;
+        // the worlds a client may be allowed into: every ward with a public being, main first
+        const worlds = () =>
+          [...harbor.wards]
+            .filter(([, h]) => (h.partition as { public?: string | null }).public !== null)
+            .sort(([a], [b]) => (a === 'main' ? -1 : b === 'main' ? 1 : a.localeCompare(b)))
+            .map(([ward, h]) => ({ ward, user: h.record.user }));
+        // the MCP endpoint: a bearer names an identity in a world, the identity names her avatar there, the side runs beside her
+        mcp = new McpHttp(
+          async (identity, ward) => {
+            const hosted = harbor.wards.get(ward);
+            return hosted ? admit(hosted, identity, 'web') : { error: 'no such world' };
+          },
+          async () => {
+            for (const h of harbor.wards.values()) await h.save();
+          },
+        );
         oauth = await mountOAuth(harbor.dir, http, routes, mcp);
-        if (mcp) mcp.gone = (identity) => oauth!.revoke(identity); // removal at the ward ends the grant at the route
-        if (main) {
-          exchange = new Exchange({
-            oauth,
-            password,
-            user: main.record.user,
-            admit: async (identity, wake) => {
-              const r = await admit(main, identity, 'web', wake);
-              return r.error ? { error: r.error } : {};
-            },
-          });
-        }
+        mcp.gone = (identity, ward) => oauth!.revoke(identity, ward); // removal at the ward ends the grant at the route
+        exchange = new Exchange({
+          oauth,
+          password,
+          worlds,
+          admit: async (identity, wake, reach, ward) => {
+            const hosted = harbor.wards.get(ward);
+            if (!hosted) return { error: 'no such world' };
+            const r = await admit(hosted, identity, 'web', wake, reach);
+            return r.error ? { error: r.error } : {};
+          },
+        });
       }
       const ex = exchange;
       http.mount('/web', async (req, res, rest) => {
-        if (tab && (await tab(req, res, rest))) return;
+        if (await tab(req, res, rest)) return;
         if (ex && (await ex.handle(req, res, rest))) return;
         res.writeHead(404, { 'content-type': 'text/plain' });
         res.end('no such page');
@@ -419,15 +432,23 @@ async function readRoutes(dir: string): Promise<Routes | null> {
   return out;
 }
 
-// The tab page, `estate/human/tab.ts`, on the web route: the page, its
-// bundle built once from the source, and the one call of the exchange a tab
-// makes: the owner password for a nonce the desk honours under `tab`. The
-// avatar that knocks with it lives in the tab, not here, so nothing is
-// admitted on this side; the tab's harbor announces its ward and the user
-// being knocks back down that socket.
-function tabPages(main: Hosted, at: { quo: string; web: string }, password: () => string | undefined): (req: IncomingMessage, res: ServerResponse, rest: string) => Promise<boolean> {
-  // The tab's source sits beside this file: `.ts` in the tree, `.js` once
-  // emitted into the package's dist. The bundler takes whichever is there.
+// The worlds on the web route. A world is a ward with a public being, and
+// its address is `/web/<ward>`: the tab page, `human/tab.ts`, told which
+// ward and which pk, so that its guest is that ward's public being rendered
+// by the screen, whatever class she is. `/web/` lists the worlds. The bundle
+// is built once from the source beside this file, `.ts` in the tree, `.js`
+// once emitted into the package's dist. `/web/<ward>/login` is the one call
+// of the dock's own way in a tab makes: the owner password for a nonce the
+// desk honours under `tab`. The avatar that knocks with it lives in the tab,
+// not here, so nothing is admitted on this side.
+//
+// The page carries a content security policy: scripts from this origin
+// only and never inline, connections to this origin and the quo. route the
+// tab dials, images from data URIs and this origin, and nothing else. So
+// even a bug in a renderer cannot become a script, and no look can reach a
+// server. The config crosses in a JSON script, which the policy allows.
+const RESERVED_PATHS = new Set(['login', 'allow', 'tab.js']);
+function worldPages(harbor: DiskHarbor, at: { quo: string; web: string }, password: () => string | undefined): (req: IncomingMessage, res: ServerResponse, rest: string) => Promise<boolean> {
   const tabEntry = () => {
     const js = fileURLToPath(new URL('../human/tab.js', import.meta.url));
     return existsSync(js) ? js : fileURLToPath(new URL('../human/tab.ts', import.meta.url));
@@ -435,21 +456,49 @@ function tabPages(main: Hosted, at: { quo: string; web: string }, password: () =
   let bundle: Promise<string> | undefined;
   const built = () =>
     (bundle ??= build({ entryPoints: [tabEntry()], bundle: true, format: 'esm', platform: 'browser', target: 'es2023', write: false }).then((o) => o.outputFiles[0]!.text));
-  const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>quo</title>
-<style>body{font:16px/1.5 system-ui,sans-serif;max-width:40rem;margin:2rem auto;padding:0 1rem;color:#222}input,button{font:inherit;padding:.4rem;margin:.2rem}pre{background:#f4f4f4;padding:.75rem;overflow:auto}</style>
-</head><body><script type="module">import { start } from './tab.js'; start(${JSON.stringify(at)});</script></body></html>`;
+  const quoOrigin = (() => {
+    try {
+      const u = new URL(at.quo);
+      return `${u.origin} ${u.origin.replace(/^http/, 'ws')}`;
+    } catch {
+      return '';
+    }
+  })();
+  const policy = `default-src 'none'; script-src 'self'; style-src 'unsafe-inline'; img-src 'self' data:; connect-src 'self' ${quoOrigin}; form-action 'self'; base-uri 'none'; frame-ancestors 'none'`;
+  const shell = (body: string) => `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>quo</title>
+<style>${CSS}</style>
+</head><body>${body}</body></html>`;
+  const esc = (v: string) => v.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] ?? c);
+  const publicOf = (h: Hosted) => (h.partition as { public?: string | null }).public ?? null;
+  const html = (status: number, res: ServerResponse, body: string) => {
+    res.writeHead(status, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'content-security-policy': policy, 'referrer-policy': 'no-referrer' });
+    res.end(shell(body));
+    return true;
+  };
   return async (req, res, rest) => {
-    if (rest === '/tab' && req.method === 'GET') {
-      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
-      res.end(html);
-      return true;
+    const parts = rest.split('/').filter(Boolean);
+    if (req.method === 'GET' && (rest === '' || rest === '/')) {
+      const list = [...harbor.wards]
+        .filter(([, h]) => publicOf(h) !== null)
+        .map(([n, h]) => `<li><a href="${at.web}/${encodeURIComponent(n)}">${esc(n)}</a> <small>${esc(publicOf(h) ?? '')} at the door, <code>${h.pk.slice(0, 16)}…</code></small></li>`)
+        .join('');
+      return html(200, res, `<h1>worlds</h1>${list ? `<ul>${list}</ul>` : '<p>no ward here has a public being</p>'}`);
     }
     if (rest === '/tab.js' && req.method === 'GET') {
       res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' });
       res.end(await built());
       return true;
     }
-    if (rest === '/tab/login' && req.method === 'POST') {
+    const wardName = parts[0] ?? '';
+    if (!wardName || RESERVED_PATHS.has(wardName)) return false;
+    const hosted = harbor.wards.get(wardName);
+    if (!hosted) return html(404, res, `<h1>no such world</h1><p>no ward named ${esc(wardName)} on this harbor.</p>`);
+    if (parts.length === 1 && req.method === 'GET') {
+      if (publicOf(hosted) === null) return html(404, res, `<h1>not a world</h1><p>ward ${esc(wardName)} has no public being, so nobody is at its door.</p>`);
+      const cfg = { quo: at.quo, web: at.web, ward: wardName, pk: hosted.pk };
+      return html(200, res, `<script id="quo" type="application/json">${JSON.stringify(cfg).replace(/</g, '\\u003c')}</script><script type="module" src="${at.web}/tab.js"></script>`);
+    }
+    if (parts.length === 2 && parts[1] === 'login' && req.method === 'POST') {
       const raw = await readAll(req as AsyncIterable<Buffer>);
       let body: { password?: unknown; identity?: unknown } = {};
       try {
@@ -470,15 +519,20 @@ function tabPages(main: Hosted, at: { quo: string; web: string }, password: () =
         return json(401, { error: 'that is not the password' });
       }
       const identity = typeof body.identity === 'string' ? body.identity : '';
-      if (!/^[\w.-]{1,40}$/.test(identity) || identity === main.record.user || identity === 'desk') return json(400, { error: 'an identity is one word, and not the user or the desk' });
+      if (!/^[\w.-]{1,40}$/.test(identity) || identity === hosted.record.user || identity === 'desk') return json(400, { error: 'an identity is one word, and not the user or the desk' });
       const nonce = randomBytes(16).toString('hex');
-      NONCES.set(nonce, { kind: 'tab', user: main.record.user, client: identity });
-      return json(200, { nonce, ward: main.pk });
+      NONCES.set(nonce, { kind: 'tab', user: hosted.record.user, client: identity, reach: true });
+      return json(200, { nonce, ward: hosted.pk });
     }
     return false;
   };
 }
 
+// The tab's stylesheet: one, light and dark, honouring the variables a look
+// sets on a section. The page owns layout; a far being paints inside her
+// section and nowhere else.
+const CSS = ":root{color-scheme:light dark;--accent:#3b6ef5;--bg:transparent;--fg:inherit;--font:system-ui,sans-serif;--radius:6px}body{font:16px/1.5 system-ui,sans-serif;max-width:40rem;margin:2rem auto;padding:0 1rem}nav.worlds{display:flex;flex-wrap:wrap;gap:.5rem 1rem;font-size:.9rem;opacity:.8}nav.worlds a[aria-current]{font-weight:600}header,main{background:var(--bg);color:var(--fg);font-family:var(--font)}header{display:flex;flex-wrap:wrap;align-items:center;gap:.5rem 1rem}header .notice{width:100%;margin:0}input,select,textarea,button{font:inherit;padding:.4rem;margin:.2rem;border-radius:var(--radius)}button{background:var(--accent);color:#fff;border:0;padding:.4rem .9rem}fieldset{border:1px solid color-mix(in srgb,currentColor 20%,transparent);border-radius:var(--radius);margin:.5rem 0}section.standing{background:var(--bg);color:var(--fg);font-family:var(--font);border-left:4px solid var(--accent);border-radius:var(--radius);padding:.25rem 1rem;margin:1.5rem 0}section.standing h2{display:flex;align-items:center;gap:.5rem;font-size:1.1rem}img.logo{height:1.6rem}table{border-collapse:collapse}td,th{padding:.15rem .5rem;text-align:left}.answer{margin:.5rem 0 1rem;padding:.5rem;border-left:3px solid var(--accent)}.answer.error{border-color:#c33}.answer.silence,.answer.word,.answer.unreached{border-color:#c93}pre{padding:.75rem;overflow:auto}";
+
 // The quo. route. A request carries one ask to a pk; an upgrade is a held
 // socket. Bytes from here go to an own door or a held socket, never onward.
 function mountQuo(harbor: DiskHarbor, http: Http, server: HttpServer, quo: Quo): void {
@@ -571,9 +625,9 @@ async function mountOAuth(dir: string, http: Http, routes: Routes, mcp: McpHttp
   http.mount('/mcp', async (req, res, rest) => {
     if (await oauth.handle(req, res, rest)) return;
     if (rest === '/mcp') {
-      const identity = oauth.bearer(req);
-      if (identity === null || !mcp) return oauth.challenge(res);
-      return mcp.handle(req, res, identity);
+      const grant = oauth.bearer(req);
+      if (grant === null || !mcp) return oauth.challenge(res);
+      return mcp.handle(req, res, grant.identity, grant.ward);
     }
     res.writeHead(404, { 'content-type': 'application/json' });
     res.end(JSON.stringify({ error: 'no such route' }));

package/cli/estate/Caddyfile

@@ -0,0 +1,25 @@
+# Three hostnames, one daemon, one loopback port. Caddy faces the world and
+# terminates TLS; the daemon never does. Each hostname is a route, and a
+# route is a path on the daemon's HTTP door. Replace DOMAIN.
+#
+#   mcp.   the model side: streamable HTTP MCP, with the credential exchange in front
+#   web.   the bundle for plain tabs, and the exchange pages
+#   quo.   the socket door for other harbors: requests in, sockets held, the rendezvous
+#
+# There is no cli. route. The root owner is the unix socket, reached on the
+# device or over SSH, and never through here.
+
+mcp.DOMAIN {
+	reverse_proxy 127.0.0.1:8787
+	rewrite * /mcp{uri}
+}
+
+web.DOMAIN {
+	reverse_proxy 127.0.0.1:8787
+	rewrite * /web{uri}
+}
+
+quo.DOMAIN {
+	reverse_proxy 127.0.0.1:8787
+	rewrite * /quo{uri}
+}

package/cli/estate/quo.service

@@ -0,0 +1,36 @@
+# The daemon on a droplet, as one user, forever. Install with:
+#   sudo cp droplet/quo.service /etc/systemd/system/quo.service
+#   sudo systemctl enable --now quo
+# The unit runs as the `quo` user, whose home holds the estate folder and
+# the harbor folder, so the seed, the lease and the sockets are that user's
+# alone. The HTTP door is loopback only; Caddy fronts it. See Caddyfile
+# beside this file.
+[Unit]
+Description=quo: one harbor on this device
+After=network.target
+
+[Service]
+User=quo
+Group=quo
+Environment=QUO_DIR=/home/quo/.quo
+Environment=QUO_HTTP=8787
+# QUO_OWNER_PASSWORD, root-only. Without it the exchange pages are closed.
+# CLAUDE_CODE_OAUTH_TOKEN, when an agent folder runs `claude -p`: the agent
+# reads its credential from the device, never from cells.
+EnvironmentFile=-/etc/quo/env
+WorkingDirectory=/home/quo/ESTATE
+ExecStart=/usr/bin/node /home/quo/ESTATE/node_modules/@quo-systems/dock/dist/cli/quo.js serve
+Restart=always
+RestartSec=2
+KillSignal=SIGTERM
+TimeoutStopSec=10
+NoNewPrivileges=true
+ProtectSystem=strict
+# Agents run in their folders and Claude Code keeps its own state in the
+# user's home; both must be writable for a run to happen, and a harbor
+# with no agent has neither.
+ReadWritePaths=/home/quo/.quo -/home/quo/agents -/home/quo/.claude -/home/quo/.claude.json /tmp
+PrivateTmp=false
+
+[Install]
+WantedBy=multi-user.target

package/cli/estate.ts

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: Apache-2.0
+// `quo estate DIR --domain D`: an estate folder, written once, of the shape
+// every estate has. One folder per harbor, here the first, `droplet/`: the
+// quo directory that device runs minus what it mints, its routes under the
+// domain, no agents, no classes of its own, and that device's unit and
+// Caddyfile. A package file that depends on this dock and nothing else, and
+// one document to fill in. An estate needs nothing the dock does not give
+// it, and this is the dock giving it.
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// This package's own version, read beside the emitted or the source tree.
+async function version(): Promise<string> {
+  for (const rel of ['../package.json', '../../package.json']) {
+    const at = fileURLToPath(new URL(rel, import.meta.url));
+    if (!existsSync(at)) continue;
+    const pkg = JSON.parse(await readFile(at, 'utf8')) as { name?: string; version?: string };
+    if (pkg.name === '@quo-systems/dock' && pkg.version) return pkg.version;
+  }
+  return '0.1.0';
+}
+const template = (name: string) => readFile(fileURLToPath(new URL(`estate/${name}`, import.meta.url)), 'utf8');
+
+export async function estate(dir: string, domain: string): Promise<{ dir: string; name: string; files: string[] }> {
+  if (!/^[a-z0-9.-]+\.[a-z]{2,}$/i.test(domain)) throw new Error(`estate: ${domain} is not a domain`);
+  if (existsSync(join(dir, 'package.json'))) throw new Error(`estate: ${dir} already holds a package`);
+  const name = basename(dir);
+  const files: Record<string, string> = {
+    'package.json': JSON.stringify({ name, private: true, description: `The ${name} estate: one owner's harbors, built on the dock and nothing else.`, type: 'module', dependencies: { '@quo-systems/dock': `^${await version()}` } }, null, 2) + '\n',
+    [`${name}.md`]: `# ${name}\n\nAn estate: all of one owner's harbors. One folder per harbor, each the quo\ndirectory that device runs minus what it mints, plus that device's unit.\n\`droplet/\` is the first: its routes under \`${domain}\`, its agents, its\nclasses, its systemd unit and its Caddyfile. This folder depends on the\ndock and nothing else.\n\n## The droplet\n\nWhere it is, how it is reached, and what was done to stand it up: yours\nto write.\n`,
+    'droplet/routes.json': JSON.stringify({ mcp: `https://mcp.${domain}`, web: `https://web.${domain}`, quo: `https://quo.${domain}` }) + '\n',
+    'droplet/agents.json': '{}\n',
+    'droplet/classes/index.ts': '// The classes this harbor holds beside the dock\'s built-in ones, exported\n// by name.\nexport {};\n',
+    'droplet/quo.service': (await template('quo.service')).replaceAll('ESTATE', name),
+    'droplet/Caddyfile': (await template('Caddyfile')).replaceAll('DOMAIN', domain),
+  };
+  for (const [rel, text] of Object.entries(files)) {
+    await mkdir(join(dir, rel, '..'), { recursive: true });
+    await writeFile(join(dir, rel), text);
+  }
+  return { dir, name, files: Object.keys(files) };
+}

package/cli/quo.ts

@@ -11,10 +11,12 @@
 //   quo invite [--dir D] [--ward W] [--via S] <json> { being, id }
 //   quo knock  [--dir D] [--ward W] [--via S] <json> { being | { boot, key }, id, invitation, method?, args?, wanted? }
 //   quo remove [--dir D] [--ward W] [--via S] <json> { being, id }: a relation out of a being; on the ward pk, an owner
+//   quo unboot [--dir D] [--ward W] [--via S] <json> { being }: a being out of the ward, with every relation she holds
 //   quo side   [--dir D] [--ward W] --as NAME  an avatar over stdio for a local MCP client; NAME is the client identity
 //   quo run    [--dir D] [--ward W] --as NAME --url URL --model NAME [--turns N]  a human at a terminal talking to a model through an avatar: a line in, the model's final text out
 //   quo pilot  [--dir D] [--ward W] [--via S]        the owner pilot over stdio: census, boot, invite, knock, remove
 //   quo reach  [--dir D] <pk> <url>          a hint for the harbor's directory: that ward pk lives at that quo. route
+//   quo estate <dir> --domain D              an estate folder of the shape every estate has: a droplet's quo directory, unit and Caddyfile, on this dock
 //
 // D defaults to $QUO_DIR, then ~/.quo. W defaults to main. init takes
 // --user NAME for the user being, defaulting to the device's user. run
@@ -31,8 +33,9 @@ import { DiskHarbor } from '../harbor/disk.ts';
 import { serve } from './daemon.ts';
 import { ask, side, reach, type Run } from './client.ts';
 import { pilotSide } from '../mcp/pilot.ts';
+import { estate } from './estate.ts';
 
-const OWNER_ASKS = new Set(['boot', 'invite', 'knock', 'remove']);
+const OWNER_ASKS = new Set(['boot', 'public', 'invite', 'knock', 'remove', 'unboot']);
 
 function parse(argv: string[]) {
   const flags: Record<string, string> = {};
@@ -80,7 +83,7 @@ async function main(argv: string[]): Promise<number> {
   }
   if (cmd === 'pilot') {
     await ask(dir, undefined, {}, ward); // no daemon is a clear word now, not at the first tool call
-    const serving = await pilotSide(dir, ward, new StdioServerTransport(), (line) => console.error(`pilot ${line}`), via);
+    const serving = await pilotSide(dir, ward, new StdioServerTransport(), via);
     process.stdin.once('end', () => void serving.close().then(() => process.exit(0)));
     return -1;
   }
@@ -93,6 +96,14 @@ async function main(argv: string[]): Promise<number> {
     process.once('SIGTERM', stop);
     return -1; // stays up
   }
+  if (cmd === 'estate') {
+    if (!json || !flags.domain) {
+      console.error('quo estate needs <dir> --domain D');
+      return 2;
+    }
+    print(await estate(json, flags.domain));
+    return 0;
+  }
   if (cmd === 'reach') {
     if (!json || !more) {
       console.error('quo reach needs <pk> <url>');
@@ -111,7 +122,7 @@ async function main(argv: string[]): Promise<number> {
     const failed = 'error' in out || (typeof out.result === 'object' && out.result !== null && 'error' in out.result);
     return failed ? 1 : 0;
   }
-  console.error('usage: quo init|serve|census|boot|invite|knock|remove|side|run|pilot|reach [--dir D] [--ward W] [--via S] [--as NAME] [--url URL --model NAME] [--dial URL] [json]');
+  console.error('usage: quo init|serve|census|boot|public|invite|knock|remove|unboot|side|run|pilot|reach|estate [--dir D] [--ward W] [--via S] [--as NAME] [--url URL --model NAME] [--dial URL] [json]');
   return 2;
 }
 

package/dist/beings/avatar.js

@@ -47,8 +47,11 @@ export class Avatar extends Being {
             return inv ?? { error: 'no invitation' };
         return this.join(inv);
     }
-    // Knock with an invitation, hand the user being one back so she can push,
-    // and take her as `user`. The only moment a standing is born here.
+    // Knock with an invitation, hand the far being one back so she can push,
+    // and take her as `user`. The only moment a standing is born here. A being
+    // who answers the hello with an error object is a being who answered: she
+    // is taken all the same, and the way back she did not take is dropped, so
+    // any world's public being may admit a guest, hello or not.
     async join(invitation) {
         if (this.standings[USER])
             return this.tools();
@@ -60,6 +63,8 @@ export class Avatar extends Being {
             this.occupants.remove(PUSHER);
             return { error: isSilence(out) ? 'silence' : wordOf(out) };
         }
+        if (out !== null && typeof out === 'object' && !Array.isArray(out) && 'error' in out)
+            this.occupants.remove(PUSHER);
         await this.take(USER, invitation);
         return this.tools();
     }

package/dist/beings/carry.d.ts

@@ -0,0 +1,10 @@
+import { Being } from '@quo-systems/quo';
+import type { Asker, Blueprint, JsonObject, OccupantRecord, Reply } from '@quo-systems/quo';
+export declare class Carrier extends Being {
+    static carries(_occupant: OccupantRecord | undefined, _asker: Asker): boolean;
+    static hidden(id: string): boolean;
+    private get carried();
+    private get looks();
+    blueprint(asker: Asker): Promise<Blueprint>;
+    answer(asker: Asker, method?: string, args?: JsonObject): Promise<Reply>;
+}

package/dist/beings/carry.js

@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: Apache-2.0
+// A carrier: a being who shows the asks of the standings she holds as asks
+// of her own, and forwards. Whoever she carries for sees, in one describe,
+// what she can be asked and what every being she holds can be asked, each
+// under that standing's name; asking one is an ask on that standing, in her
+// name, so the far being sees her and never who is behind her. A user being
+// carries acme for the human's devices; a house being could carry its
+// rooms; nothing here knows what she is.
+//
+// A carried ask is `<id>-<name>`, and the mapping back is kept in her cells
+// and never parsed from the name, so an id with a dash in it is no trouble.
+// The notes say which asks are whose, `standings: { id: { asks, look? } }`,
+// so a screen draws one section per standing and a model side keeps the
+// flat list it needs. Her own asks come first and are never shadowed: a
+// carried name that collides with one of hers is dropped.
+//
+// She asks a standing's describe again when its digest moved, and its
+// `look` once per digest, and keeps both in her cells. So a describe of
+// hers may cost one ask per stale standing, which is the price of a page
+// that is never more than one ask behind.
+import { Being, isSilence, isWord, wordOf } from '@quo-systems/quo';
+import { sanitise } from './look.js';
+export class Carrier extends Being {
+    // Who sees what she carries. Nobody, until a subclass says who.
+    static carries(_occupant, _asker) {
+        return false;
+    }
+    // Standings she never carries: a way back to a device is one, by the
+    // dock's own convention, and a subclass may name more.
+    static hidden(id) {
+        return id.startsWith('to:');
+    }
+    get carried() {
+        return (this.cells.carried ??= {});
+    }
+    get looks() {
+        return (this.cells.looks ??= {});
+    }
+    // Her describe with her standings carried into it, for an asker who may
+    // see them. Every other asker gets her describe alone.
+    async blueprint(asker) {
+        const C = this.constructor;
+        const bp = this.describe(asker);
+        if (!C.carries(this.occupant(asker), asker))
+            return bp;
+        const own = new Set(bp.asks.map((a) => a.name));
+        const carried = {};
+        const groups = {};
+        for (const [id, rec] of Object.entries(this.cells.standings)) {
+            if (C.hidden(id))
+                continue;
+            const st = this.standings[id];
+            if (!st)
+                continue;
+            if (!rec.blueprint || rec.seen !== rec.digest)
+                await st.ask(); // her ward writes the record
+            if (!rec.blueprint)
+                continue;
+            const names = [];
+            for (const a of rec.blueprint.asks) {
+                if (a.name === 'look')
+                    continue;
+                const name = `${id}-${a.name}`;
+                if (own.has(name))
+                    continue;
+                carried[name] = { id, ask: a.name };
+                names.push(name);
+                bp.asks.push({ ...a, name });
+            }
+            const group = { asks: names };
+            if (rec.blueprint.asks.some((a) => a.name === 'look')) {
+                const kept = this.looks[id];
+                if (!kept || kept.digest !== rec.digest) {
+                    const l = await st.ask('look');
+                    this.looks[id] = { digest: rec.digest, look: isSilence(l) || isWord(l) ? {} : sanitise(l) };
+                }
+                group.look = this.looks[id].look;
+            }
+            groups[id] = group;
+        }
+        for (const id of Object.keys(this.looks))
+            if (!(id in groups))
+                delete this.looks[id];
+        this.cells.carried = carried;
+        const notes = bp.notes !== null && typeof bp.notes === 'object' && !Array.isArray(bp.notes) ? bp.notes : {};
+        return { asks: bp.asks, notes: { ...notes, standings: groups } };
+    }
+    async answer(asker, method, args = {}) {
+        if (method === undefined)
+            return this.blueprint(asker);
+        const C = this.constructor;
+        const to = Object.hasOwn(this.carried, method) ? this.carried[method] : undefined;
+        if (to && C.carries(this.occupant(asker), asker)) {
+            const st = this.standings[to.id];
+            if (!st)
+                return { error: 'unknown ask' };
+            const out = await st.ask(to.ask, args);
+            if (isSilence(out))
+                return out;
+            if (isWord(out))
+                return { error: wordOf(out) };
+            return out;
+        }
+        return super.answer(asker, method, args);
+    }
+}

package/dist/beings/desk.d.ts

@@ -8,6 +8,7 @@ export type Verified = {
     user: string;
     client: string;
     wake?: boolean;
+    reach?: boolean;
 };
 export type Verifier = (proof: Proof) => Promise<Verified | null> | Verified | null;
 export declare class Desk extends Being {

package/dist/beings/desk.js

@@ -33,7 +33,7 @@ export class Desk extends Being {
         const user = this.standings[`user:${who.user}`];
         if (!user)
             return { error: 'no such user' };
-        const inv = await user.ask('device', who.wake === true ? { client: who.client, wake: true } : { client: who.client });
+        const inv = await user.ask('device', { client: who.client, ...(who.wake === true ? { wake: true } : {}), ...(who.reach === true ? { reach: true } : {}) });
         if (isSilence(inv))
             return { error: 'silence' };
         if (isWord(inv))

package/dist/beings/index.d.ts

@@ -1,3 +1,5 @@
 export { User, DESK } from './user.ts';
 export { Desk, type Proof, type Verified, type Verifier } from './desk.ts';
 export { Avatar, USER, PUSHER } from './avatar.ts';
+export { Carrier } from './carry.ts';
+export { sanitise, hint, hintFor, groups, type Look, type Hint } from './look.ts';

package/dist/beings/index.js

@@ -3,3 +3,5 @@
 export { User, DESK } from './user.js';
 export { Desk } from './desk.js';
 export { Avatar, USER, PUSHER } from './avatar.js';
+export { Carrier } from './carry.js';
+export { sanitise, hint, hintFor, groups } from './look.js';

package/dist/beings/link.d.ts

@@ -0,0 +1,7 @@
+import type { Invitation } from '@quo-systems/quo';
+export declare const KEY = "quo";
+export declare function format(inv: Invitation): string;
+export declare function parse(hash: string): Invitation | null;
+export declare function strip(hash: string): string;
+export declare function link(page: string, inv: Invitation): string;
+export declare function isInvitation(v: unknown): v is Invitation;

package/dist/beings/link.js

@@ -0,0 +1,42 @@
+export const KEY = 'quo';
+const HEX = (n) => `[0-9a-f]{${n}}`;
+const FULL = new RegExp(`^(${HEX(128)})\\.(${HEX(64)})\\.(${HEX(64)})$`);
+const PUBLIC = new RegExp(`^${HEX(128)}$`);
+export function format(inv) {
+    return inv.heir && inv.secret ? `${inv.ward}.${inv.heir}.${inv.secret}` : inv.ward;
+}
+// The invitation in a fragment, or null. Anything else in the fragment is
+// the page's own and is left alone.
+export function parse(hash) {
+    const m = /(?:^#|&)quo=([^&]+)/.exec(hash.startsWith('#') ? hash : `#${hash}`);
+    if (!m)
+        return null;
+    const v = decodeURIComponent(m[1]);
+    const full = FULL.exec(v);
+    if (full)
+        return { ward: full[1], heir: full[2], secret: full[3] };
+    return PUBLIC.test(v) ? { ward: v } : null;
+}
+// The fragment without the invitation, so the page keeps whatever else it
+// put there and the capability is gone from the address bar.
+export function strip(hash) {
+    const rest = (hash.startsWith('#') ? hash.slice(1) : hash)
+        .split('&')
+        .filter((p) => !p.startsWith(`${KEY}=`))
+        .join('&');
+    return rest ? `#${rest}` : '';
+}
+export function link(page, inv) {
+    return `${page}#${KEY}=${format(inv)}`;
+}
+// Whether an answer is an invitation: a ward pk, and a heir with its secret
+// or neither. What a guest's form answers with to be let in.
+export function isInvitation(v) {
+    if (v === null || typeof v !== 'object' || Array.isArray(v))
+        return false;
+    const o = v;
+    if (typeof o.ward !== 'string' || !PUBLIC.test(o.ward))
+        return false;
+    const heir = typeof o.heir === 'string', secret = typeof o.secret === 'string';
+    return (heir && secret) || (!heir && !secret && !('heir' in o) && !('secret' in o));
+}