@quo-systems/dock 0.1.0

package/dist/mcp/pilot.js

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: Apache-2.0
+// The owner pilot: `quo pilot`. An MCP server over stdio that reaches a
+// ward's owner asks through the daemon's root socket, and exposes four tools
+// and no more, plus the one read. Whoever runs this process is the owner, by
+// the device's own rules: the root of the ward here, or, with `via`, an
+// owner at another ward's door, on a standing the user being here holds
+// there. Every call is logged with what it made. The owner creates and
+// places; the work goes through `quo side`, under a gate.
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { ask } from '../cli/client.js';
+export const PILOT_TOOLS = [
+    {
+        name: 'census',
+        description: 'the empty ask: the ward pk and every being, with class, public and digest',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'boot',
+        description: 'boot a being by class name under a key; public marks the one public being',
+        inputSchema: { type: 'object', properties: { key: { type: 'string' }, class: { type: 'string' }, public: { type: 'boolean' } }, required: ['key', 'class'] },
+    },
+    {
+        name: 'invite',
+        description: 'mint an invitation on a being of the ward, under an id she will know the occupant by',
+        inputSchema: { type: 'object', properties: { being: { type: 'string' }, id: { type: 'string' } }, required: ['being', 'id'] },
+    },
+    {
+        name: 'knock',
+        description: 'knock for a being of the ward with an invitation, and take the standing under id if answered',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                being: { description: 'a key already booted, or { boot: class, key } to boot her first' },
+                id: { type: 'string' },
+                invitation: { type: 'object' },
+                method: { type: 'string' },
+                args: { type: 'object' },
+                wanted: { type: 'object', properties: { time: { type: 'number' } } },
+            },
+            required: ['being', 'id', 'invitation'],
+        },
+    },
+    {
+        name: 'remove',
+        description: 'take a relation out of a being of the ward by id, occupant or standing; on the ward pk, an owner, by the root alone',
+        inputSchema: { type: 'object', properties: { being: { type: 'string' }, id: { type: 'string' } }, required: ['being', 'id'] },
+    },
+];
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+export async function pilotSide(dir, ward, transport, log = () => { }, via) {
+    const server = new Server({ name: 'quo-pilot', version: '0.0.0' }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: PILOT_TOOLS }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const name = req.params.name;
+        const args = req.params.arguments ?? {};
+        if (!PILOT_TOOLS.some((t) => t.name === name))
+            return { content: [{ type: 'text', text: JSON.stringify({ error: 'unknown ask' }) }], structuredContent: { error: 'unknown ask' }, isError: true };
+        const out = await ask(dir, name === 'census' ? undefined : name, args, ward, via);
+        const value = 'error' in out ? { error: out.error } : out.result;
+        const failed = 'error' in out || (typeof value === 'object' && value !== null && 'error' in value);
+        log(`${via === undefined ? ward : `${ward} via ${via}`} ${name} ${JSON.stringify(args)} -> ${JSON.stringify(value)}`);
+        const structured = isRecord(value) ? { structuredContent: value } : {};
+        return { content: [{ type: 'text', text: JSON.stringify(value) }], ...structured, ...(failed ? { isError: true } : {}) };
+    });
+    await server.connect(transport);
+    return { close: () => server.close() };
+}

package/dist/mcp/runner.d.ts

@@ -0,0 +1,45 @@
+import type { Blueprint, JsonObject } from '@quo-systems/quo';
+import type { Avatar } from '../beings/avatar.ts';
+import { type Serving } from '../beings/side.ts';
+export type Model = {
+    url: string;
+    model: string;
+    key?: string;
+    turns?: number;
+};
+export declare const TURNS = 10;
+export type Tool = {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters: JsonObject;
+    };
+};
+export type ToolCall = {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+};
+export type Message = {
+    role: 'system' | 'user';
+    content: string;
+} | {
+    role: 'assistant';
+    content: string | null;
+    tool_calls?: ToolCall[];
+} | {
+    role: 'tool';
+    tool_call_id: string;
+    content: string;
+};
+export declare function tools(bp: Blueprint): Tool[];
+export declare function result(avatar: Avatar, call: ToolCall): Promise<string>;
+export type Runner = Serving & {
+    say(text: string): Promise<string | null>;
+    readonly messages: readonly Message[];
+};
+export declare function runnerSide(avatar: Avatar, model: Model, hear?: (text: string) => void, after?: () => Promise<void>): Runner;

package/dist/mcp/runner.js

@@ -0,0 +1,94 @@
+import { word, wordText, SILENCE_TEXT, UNREACHED_TEXT } from '../beings/side.js';
+export const TURNS = 10;
+// Her describe, spoken as a tools array. Name, description and input are
+// verbatim, with the one narrowing an endpoint has asked for: an ask that
+// declares no properties is sent with an empty `properties`, because
+// LM Studio refuses a parameters schema without one.
+export function tools(bp) {
+    return bp.asks.map((a) => {
+        const t = { type: 'function', function: { name: a.name, parameters: { properties: {}, ...a.input, type: 'object' } } };
+        if (a.description !== undefined)
+            t.function.description = a.description;
+        return t;
+    });
+}
+// One tool call, one ask, one tool message: the three words cross as the
+// table in quo-mcp.md says, and a tool message is text, so the two words
+// that carry nothing cross as the text the trunk gives them.
+export async function result(avatar, call) {
+    let args = {};
+    try {
+        const parsed = call.function.arguments ? JSON.parse(call.function.arguments) : {};
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed))
+            args = parsed;
+    }
+    catch {
+        return JSON.stringify({ error: 'arguments are not JSON' });
+    }
+    const w = word(await avatar.call(call.function.name, args));
+    if (w.word === 'object' || w.word === 'error')
+        return JSON.stringify(w.value);
+    return w.word === 'silence' ? SILENCE_TEXT : w.word === 'quo' ? wordText(w.name) : UNREACHED_TEXT;
+}
+// `hear` gets every final text the model says, whoever started the turn.
+// `after` runs when an ask is done, as in the MCP server: a harbor that must
+// write what the ward changed hooks it.
+export function runnerSide(avatar, model, hear = () => { }, after = async () => { }) {
+    const messages = [];
+    const ceiling = model.turns ?? TURNS;
+    let busy = Promise.resolve();
+    async function complete(t) {
+        const headers = { 'content-type': 'application/json' };
+        if (model.key !== undefined)
+            headers.authorization = `Bearer ${model.key}`;
+        const res = await fetch(`${model.url.replace(/\/$/, '')}/chat/completions`, { method: 'POST', headers, body: JSON.stringify({ model: model.model, messages, tools: t }) });
+        const body = (await res.json());
+        const m = body.choices?.[0]?.message;
+        if (!res.ok || !m)
+            throw new Error(`model: ${res.status} ${JSON.stringify(body.error ?? body)}`);
+        return m;
+    }
+    // One turn: from the last appended message to the model's final text.
+    async function turn() {
+        const bp = await avatar.tools();
+        const t = 'asks' in bp ? tools(bp) : [];
+        for (let i = 0; i < ceiling; i++) {
+            const m = await complete(t);
+            const reply = { role: 'assistant', content: m.content };
+            if (m.tool_calls?.length)
+                reply.tool_calls = m.tool_calls;
+            messages.push(reply);
+            if (!m.tool_calls?.length) {
+                const text = m.content ?? '';
+                hear(text);
+                return text;
+            }
+            for (const call of m.tool_calls) {
+                messages.push({ role: 'tool', tool_call_id: call.id, content: await result(avatar, call) });
+                await after();
+            }
+        }
+        return null;
+    }
+    // Turns never overlap: one conversation, one train of thought.
+    function start(message) {
+        const next = busy.then(async () => {
+            messages.push(message);
+            return turn();
+        });
+        busy = next.catch(() => { });
+        return next;
+    }
+    const ear = (object) => {
+        void start({ role: 'user', content: JSON.stringify(object) }).catch(() => { });
+    };
+    avatar.ears.add(ear);
+    return {
+        messages,
+        say: (text) => start({ role: 'user', content: text }),
+        close: async () => {
+            avatar.ears.delete(ear);
+            await busy;
+        },
+    };
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,9 @@
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { type Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { Blueprint } from '@quo-systems/quo';
+import type { Avatar } from '../beings/avatar.ts';
+import { type Serving } from '../beings/side.ts';
+export declare const NAME = "quo";
+export declare const VERSION = "0.0.0";
+export declare function tools(bp: Blueprint): Tool[];
+export declare function mcpSide(avatar: Avatar, transport: Transport, after?: () => Promise<void>): Promise<Serving>;

package/dist/mcp/server.js

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: Apache-2.0
+// The model side as an MCP server: one avatar, one transport. The mapping is
+// total and needs nothing beyond this envelope. tools/list is her describe,
+// tools/call is a named ask on her one standing, a push is a logging
+// notification, and the three words for "no object" each cross as the table
+// in quo-mcp.md says. The transport is whatever the caller connected: the
+// SDK's in-memory pair in a test, stdio for a local client, HTTP on a route.
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { word, wordText, SILENCE_TEXT, UNREACHED_TEXT } from '../beings/side.js';
+export const NAME = 'quo';
+export const VERSION = '0.0.0';
+// Her describe, spoken as tools. Name, description and input are verbatim;
+// an output schema crosses when she declared one.
+export function tools(bp) {
+    return bp.asks.map((a) => {
+        const t = { name: a.name, inputSchema: { ...a.input, type: 'object' } };
+        if (a.description !== undefined)
+            t.description = a.description;
+        if (a.output !== undefined)
+            t.outputSchema = { ...a.output, type: 'object' };
+        return t;
+    });
+}
+// `after` runs when a call is done: a harbor that must write what the ward
+// changed hooks it, since a same-ward ask never crosses the harbor.
+export async function mcpSide(avatar, transport, after = async () => { }) {
+    const server = new Server({ name: NAME, version: VERSION }, { capabilities: { tools: { listChanged: true }, logging: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const bp = await avatar.tools();
+        if ('error' in bp && !('asks' in bp))
+            return { tools: [] }; // not joined: nothing to show, and nothing to call
+        return { tools: tools(bp) };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const w = word(await avatar.call(req.params.name, (req.params.arguments ?? {})));
+        await after();
+        if (w.word === 'object') {
+            const structured = w.value !== null && typeof w.value === 'object' && !Array.isArray(w.value) ? { structuredContent: w.value } : {};
+            return { content: [{ type: 'text', text: JSON.stringify(w.value) }], ...structured };
+        }
+        if (w.word === 'error')
+            return { content: [{ type: 'text', text: JSON.stringify(w.value) }], structuredContent: w.value, isError: true };
+        if (w.word === 'silence')
+            return { content: [{ type: 'text', text: SILENCE_TEXT }], structuredContent: { error: 'silence' }, isError: true };
+        if (w.word === 'quo')
+            return { content: [{ type: 'text', text: wordText(w.name) }], structuredContent: { error: w.name }, isError: true };
+        return { content: [{ type: 'text', text: UNREACHED_TEXT }], structuredContent: { error: 'unreached' }, isError: true };
+    });
+    // A push from the user being is a notification to the client. If the
+    // transport is gone, the push is dropped, as the side says it is.
+    const ear = (object) => {
+        void server.sendLoggingMessage({ level: 'info', logger: NAME, data: object }).catch(() => { });
+    };
+    avatar.ears.add(ear);
+    await server.connect(transport);
+    return {
+        close: async () => {
+            avatar.ears.delete(ear);
+            await server.close();
+        },
+    };
+}

package/dist/mcp/web/exchange.d.ts

@@ -0,0 +1,23 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { OAuth } from '../oauth.ts';
+export declare const SESSION_TTL: number;
+export type Admit = (identity: string, wake: boolean) => Promise<{
+    error?: string;
+}>;
+export type Options = {
+    oauth: OAuth;
+    password: () => string | undefined;
+    admit: Admit;
+    user: string;
+    now?: () => number;
+};
+export declare const suggest: (name: string) => string;
+export declare class Exchange {
+    readonly o: Options;
+    readonly secret: NonSharedBuffer;
+    constructor(o: Options);
+    now(): number;
+    mint(): string;
+    valid(req: IncomingMessage): boolean;
+    handle(req: IncomingMessage, res: ServerResponse, rest: string): Promise<boolean>;
+}

package/dist/mcp/web/exchange.js

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: Apache-2.0
+// The exchange pages on the web route. Two static pages, hand-written, and
+// explicitly not the human side: they render no blueprint. They end the
+// credential exchange the way the trunk says every route does: a proof is
+// made, the front desk trades it for an invitation, the avatar knocks, and
+// the OAuth request completes with the client identity the human chose.
+//
+//   GET  /login?request=ID     the owner password, from QUO_OWNER_PASSWORD
+//   POST /login                sets a short session cookie, goes to /allow
+//   GET  /allow?request=ID     who is asking, and the identity they will be
+//   POST /allow                allow as that identity, or deny
+//
+// The password is the device's, read from the environment the way an envoy
+// reads a secret, never through cells. With none set, the exchange is closed.
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { readForm } from '../oauth.js';
+export const SESSION_TTL = 10 * 60 * 1000; // a login lives as long as a request: ten minutes
+const COOKIE = 'quo_exchange';
+const esc = (s) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] ?? c);
+const word = (s) => (typeof s === 'string' && /^[\w.-]{1,40}$/.test(s) ? s : null);
+// A client's name as an identity: lowercase words joined by dashes.
+export const suggest = (name) => name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 40) || 'client';
+export class Exchange {
+    o;
+    secret = randomBytes(32); // sessions die with the daemon, and that is fine: they live ten minutes
+    constructor(o) {
+        this.o = o;
+    }
+    now() {
+        return this.o.now?.() ?? Date.now();
+    }
+    // ---- the session cookie: an expiry, signed
+    mint() {
+        const exp = String(this.now() + SESSION_TTL);
+        return `${exp}.${createHmac('sha256', this.secret).update(exp).digest('base64url')}`;
+    }
+    valid(req) {
+        const m = /(?:^|;\s*)quo_exchange=([^;]+)/.exec(req.headers.cookie ?? '');
+        const [exp, sig] = (m?.[1] ?? '').split('.');
+        if (!exp || !sig)
+            return false;
+        const want = createHmac('sha256', this.secret).update(exp).digest('base64url');
+        return sig.length === want.length && timingSafeEqual(Buffer.from(sig), Buffer.from(want)) && Number(exp) > this.now();
+    }
+    async handle(req, res, rest) {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        const page = (status, body, headers = {}) => {
+            res.writeHead(status, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', ...headers });
+            res.end(shell(body));
+        };
+        const go = (to, headers = {}) => {
+            res.writeHead(302, { location: to, 'cache-control': 'no-store', ...headers });
+            res.end();
+        };
+        if (rest === '/login' && req.method === 'GET') {
+            const request = url.searchParams.get('request') ?? '';
+            const p = this.o.oauth.pending(request);
+            if (!p)
+                return page(400, `<h1>Nothing to allow</h1><p>This request is gone. Start again from the app that sent you here.</p>`), true;
+            if (this.o.password() === undefined)
+                return page(503, `<h1>Closed</h1><p>This world takes no logins: no owner password is set.</p>`), true;
+            if (this.valid(req))
+                return go(`/allow?request=${encodeURIComponent(request)}`), true;
+            return page(200, loginForm(request, p.client.client_name)), true;
+        }
+        if (rest === '/login' && req.method === 'POST') {
+            const f = await readForm(req);
+            const request = f.get('request') ?? '';
+            const p = this.o.oauth.pending(request);
+            if (!p)
+                return page(400, `<h1>Nothing to allow</h1><p>This request is gone.</p>`), true;
+            const want = this.o.password();
+            const got = f.get('password') ?? '';
+            if (want === undefined)
+                return page(503, `<h1>Closed</h1>`), true;
+            if (got.length !== want.length || !timingSafeEqual(Buffer.from(got), Buffer.from(want))) {
+                await new Promise((ok) => setTimeout(ok, 300));
+                return page(401, loginForm(request, p.client.client_name, 'That is not the password.')), true;
+            }
+            return go(`/allow?request=${encodeURIComponent(request)}`, { 'set-cookie': `${COOKIE}=${this.mint()}; Path=/; HttpOnly; Secure; SameSite=Strict; Max-Age=${SESSION_TTL / 1000}` }), true;
+        }
+        if (rest === '/allow' && req.method === 'GET') {
+            const request = url.searchParams.get('request') ?? '';
+            const p = this.o.oauth.pending(request);
+            if (!p)
+                return page(400, `<h1>Nothing to allow</h1><p>This request is gone.</p>`), true;
+            if (!this.valid(req))
+                return go(`/login?request=${encodeURIComponent(request)}`), true;
+            return page(200, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), this.o.user)), true;
+        }
+        if (rest === '/allow' && req.method === 'POST') {
+            const f = await readForm(req);
+            const request = f.get('request') ?? '';
+            const p = this.o.oauth.pending(request);
+            if (!p)
+                return page(400, `<h1>Nothing to allow</h1><p>This request is gone.</p>`), true;
+            if (!this.valid(req))
+                return go(`/login?request=${encodeURIComponent(request)}`), true;
+            if (f.get('decision') !== 'allow') {
+                const out = await this.o.oauth.deny(request);
+                return 'redirect' in out ? go(out.redirect) : page(400, `<h1>Gone</h1>`), true;
+            }
+            const identity = word(f.get('identity'));
+            if (identity === null || identity === this.o.user || identity === 'desk')
+                return page(400, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), this.o.user, 'An identity is one word, and not the user or the desk.')), true;
+            const admitted = await this.o.admit(identity, f.get('wake') === 'on');
+            if (admitted.error)
+                return page(500, `<h1>Not admitted</h1><p>${esc(admitted.error)}</p>`), true;
+            const out = await this.o.oauth.complete(request, identity);
+            return 'redirect' in out ? go(out.redirect, { 'set-cookie': `${COOKIE}=; Path=/; Max-Age=0` }) : page(400, `<h1>Gone</h1>`), true;
+        }
+        return false;
+    }
+}
+const shell = (body) => `<!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:32rem;margin:4rem auto;padding:0 1rem;color:#222}h1{font-size:1.4rem}label{display:block;margin:1rem 0 .25rem}input{font:inherit;padding:.5rem;width:100%;box-sizing:border-box}button{font:inherit;padding:.5rem 1rem;margin:1rem .5rem 0 0}.err{color:#b00}.who{background:#f4f4f4;padding:.75rem 1rem;border-radius:.5rem}code{word-break:break-all}</style>
+</head><body>${body}</body></html>`;
+const loginForm = (request, client, err = '') => `<h1>${esc(client)} wants in</h1>
+<p>Log in as the owner of this world to decide.</p>
+${err ? `<p class="err">${esc(err)}</p>` : ''}
+<form method="post" action="/login"><input type="hidden" name="request" value="${esc(request)}">
+<label for="p">Owner password</label><input id="p" name="password" type="password" autocomplete="current-password" autofocus required>
+<button type="submit">Log in</button></form>`;
+const allowForm = (request, client, redirect, identity, user, err = '') => `<h1>Allow ${esc(client)}?</h1>
+<div class="who"><p><strong>${esc(client)}</strong> asks to be an occupant of <strong>${esc(user)}</strong>.</p>
+<p>It will see exactly what ${esc(user)} shows the identity below, and nothing else. You can remove it any time.</p>
+<p>It returns to <code>${esc(redirect)}</code>.</p></div>
+${err ? `<p class="err">${esc(err)}</p>` : ''}
+<form method="post" action="/allow"><input type="hidden" name="request" value="${esc(request)}">
+<label for="i">Identity</label><input id="i" name="identity" value="${esc(identity)}" pattern="[\\w.-]{1,40}" required>
+<label for="w"><input id="w" name="wake" type="checkbox" style="width:auto"> May wake your other devices: hand an agent an event through ${esc(user)}</label>
+<button type="submit" name="decision" value="allow">Allow</button><button type="submit" name="decision" value="deny">Deny</button></form>`;

package/harbor/browser.ts

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: Apache-2.0
+// The browser harbor: the core over IndexedDB, in a tab. A dialer and never
+// a listener: it holds one socket per world it is connected to, and every
+// ask to a pk it does not hold goes down a socket to the listener, which is
+// the rendezvous. The lease is a web lock on the database name, held for
+// the life of the tab: a second tab on one origin meets the lock and is a
+// screen, not a harbor. The classes are the estate's beings, handed in
+// with the bundle, plus whatever a page hands in beside them.
+import type { BeingClass } from '@quo-systems/quo';
+import { User, Desk, Avatar } from '../beings/index.ts';
+import { Harbor, dial, type Dialer } from '@quo-systems/quo/harbor';
+import { Idb } from './idb.ts';
+
+export const BUILT_IN: Record<string, BeingClass> = { User, Desk, Avatar };
+
+export class BrowserHarbor extends Harbor {
+  readonly db: Idb;
+  readonly dialers: Dialer[] = [];
+  #release: (() => void) | undefined;
+
+  constructor(name = 'quo', classes: Record<string, BeingClass> = {}) {
+    const db = new Idb(name);
+    super(db, async () => ({ ...BUILT_IN, ...classes }));
+    this.db = db;
+  }
+
+  // Take the lock and boot every ward kept here. A lock already held is
+  // another tab's harbor over this seed, and this one refuses to boot.
+  override async boot(): Promise<void> {
+    await this.#lease();
+    await super.boot();
+  }
+
+  // Hold one socket to a world's quo. route.
+  dial(url: string): Dialer {
+    const d = dial(this, url);
+    this.dialers.push(d);
+    return d;
+  }
+
+  async close(): Promise<void> {
+    for (const d of this.dialers.splice(0)) d.close();
+    this.db.close();
+    this.#release?.();
+    this.#release = undefined;
+  }
+
+  async #lease(): Promise<void> {
+    const locks = (globalThis.navigator as Navigator | undefined)?.locks;
+    if (!locks) return; // no web locks on this terrain: nothing vouches, as in the memory harbor
+    const granted = await new Promise<boolean>((ok) => {
+      void locks.request(`quo:${this.db.name}`, { ifAvailable: true }, (lock) => {
+        if (!lock) {
+          ok(false);
+          return;
+        }
+        ok(true);
+        return new Promise<void>((release) => (this.#release = release)); // held until close
+      });
+    });
+    if (!granted) throw new Error(`harbor ${this.db.name} is held by another tab`);
+  }
+}

package/harbor/disk.ts

@@ -0,0 +1,120 @@
+// SPDX-License-Identifier: Apache-2.0
+// The node daemon's harbor: the core over a folder on disk. The store is
+// `files.ts`, one folder per ward; the class bodies come from a module the
+// ward record names, loaded from the folder; the lease is a pid file. The
+// estate's own beings, the user being, the front desk and the avatar, are
+// held by every harbor here: they are what every side needs, and a folder's
+// class source adds to them.
+//
+//   <dir>/
+//     lease                 pid of the one process that holds this harbor
+//     classes/index.ts      the default class source, a module exporting classes
+//     wards/<name>/         seed, partition.json, ward.json: see files.ts
+//     reach.json            the directory's hints
+import { mkdir, readFile, writeFile, unlink, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve, isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import process from 'node:process';
+import type { BeingClass } from '@quo-systems/quo';
+import { User, Desk, Avatar } from '../beings/index.ts';
+import { setup } from '../beings/setup.ts';
+import { Harbor, DEFAULT_CODE, type Hosted } from '@quo-systems/quo/harbor';
+import { Files } from './files.ts';
+
+export type { Hosted, Bound } from '@quo-systems/quo/harbor';
+export type { WardRecord } from '@quo-systems/quo/harbor';
+export const BUILT_IN: Record<string, BeingClass> = { User, Desk, Avatar };
+
+// Folders held by a harbor in this process. The lease file names a pid, and
+// a second harbor in the same pid would pass that check while still being a
+// second ward with one pk.
+const HELD = new Set<string>();
+
+// The class source is a module. Every export that is a class is a class the
+// harbor holds, under its export name. The harbor never sees a body: it
+// constructs when a ward names a class, and never chooses one.
+async function loadClasses(path: string): Promise<Record<string, BeingClass>> {
+  if (!existsSync(path)) return {};
+  // Keyed by the file's own time, so a source that changed on disk is read
+  // again and a harbor boots on what it pins, not on what it once loaded.
+  const { mtimeMs } = await stat(path);
+  const mod = (await import(`${pathToFileURL(path).href}?v=${mtimeMs}`)) as Record<string, unknown>;
+  const out: Record<string, BeingClass> = {};
+  for (const [name, v] of Object.entries(mod)) if (typeof v === 'function' && 'prototype' in v) out[name] = v as BeingClass;
+  return out;
+}
+
+export class DiskHarbor extends Harbor {
+  readonly dir: string;
+  #held = false;
+
+  constructor(dir: string) {
+    const abs = resolve(dir);
+    super(new Files(abs), async (rec) => ({ ...BUILT_IN, ...(await loadClasses(isAbsolute(rec.code) ? rec.code : join(abs, rec.code))) }));
+    this.dir = abs;
+  }
+
+  // Create a harbor folder with one ward, and the root's setup in it: the
+  // front desk, public, and one user being, with the desk holding a standing
+  // to her placed by the root's knock. Boots the ward once, with no lease, to
+  // do that and to learn its pk, and writes the record. Refuses a folder that
+  // has one.
+  static async init(dir: string, name = 'main', user = 'me'): Promise<{ dir: string; name: string; pk: string; user: string }> {
+    const h = new DiskHarbor(dir);
+    if (existsSync(join(h.dir, 'wards', name, 'seed'))) throw new Error(`ward ${name} already exists in ${h.dir}`);
+    await mkdir(join(h.dir, 'classes'), { recursive: true });
+    const classes = join(h.dir, DEFAULT_CODE);
+    if (!existsSync(classes)) await writeFile(classes, '// The classes this harbor holds beside the built-in ones. Export each one by name.\nexport {};\n');
+    const hosted = await h.create(name, user);
+    await setup(hosted, user);
+    return { dir: h.dir, name, pk: hosted.pk, user };
+  }
+
+  // Take the lease and boot every ward in the folder. The lease is the
+  // harbor's vouch made a store property: two processes over one seed are two
+  // wards with one pk, so a held lease refuses the boot.
+  override async boot(): Promise<void> {
+    await this.#lease();
+    await super.boot();
+  }
+
+  async close(): Promise<void> {
+    if (!this.#held) return;
+    await unlink(join(this.dir, 'lease')).catch(() => {});
+    HELD.delete(this.dir);
+    this.#held = false;
+  }
+
+  // Boot a ward whose folder was placed here by hand.
+  async adoptFolder(name: string): Promise<Hosted> {
+    const kept = await this.store.load(name);
+    if (!kept) throw new Error(`no ward ${name} in ${this.dir}`);
+    return this.host(name, kept);
+  }
+
+  async #lease(): Promise<void> {
+    if (HELD.has(this.dir)) throw new Error(`harbor ${this.dir} is held by pid ${process.pid}`);
+    const path = join(this.dir, 'lease');
+    if (existsSync(path)) {
+      const pid = Number(await readFile(path, 'utf8'));
+      let alive = pid !== process.pid; // our own pid with no entry in HELD is a lease we left behind
+      if (alive) {
+        try {
+          process.kill(pid, 0);
+        } catch (e) {
+          alive = (e as { code?: string }).code === 'EPERM'; // EPERM: somebody is home, and not us. anything else: a corpse
+        }
+      }
+      if (alive) throw new Error(`harbor ${this.dir} is held by pid ${pid}`);
+      await unlink(path).catch(() => {}); // the corpse, so the write below can be exclusive
+    }
+    try {
+      await writeFile(path, String(process.pid), { flag: 'wx', mode: 0o600 });
+    } catch {
+      throw new Error(`harbor ${this.dir} is held: another daemon took the lease first`);
+    }
+    HELD.add(this.dir);
+    this.#held = true;
+  }
+}