@augmentd-labs/canvas-edge 0.0.0-stage → 0.4.0

package/src/EdgeClient.js

@@ -0,0 +1,129 @@
+'use strict';
+
+import { io } from 'socket.io-client';
+
+const CHUNK_SIZE = 256 * 1024;
+
+/**
+ * canvas-edge tunnel client.
+ *
+ * Dials out to a canvas-server instance, announces what this runtime hosts,
+ * and replays proxied requests into the local fastify app (`app.inject()`),
+ * so the tunnel and localhost serve identical APIs by construction.
+ * Reconnection/backoff and heartbeat come from socket.io.
+ *
+ * See docs/canvas-edge-protocol.md for the frame protocol.
+ */
+export default class EdgeClient {
+    #serverUrl;
+    #token;
+    #localApp;
+    #announce;
+    #socket = null;
+    #announced = false;
+    #forwarded = [];
+
+    constructor({ serverUrl, token, localApp, announce }) {
+        if (!serverUrl || !token || !localApp?.inject || !announce?.instanceId) {
+            throw new Error('EdgeClient requires serverUrl, token, localApp (fastify) and announce.instanceId');
+        }
+        this.#serverUrl = serverUrl.replace(/\/+$/, '');
+        this.#token = token;
+        this.#localApp = localApp;
+        this.#announce = announce;
+    }
+
+    /**
+   * One-time pairing: exchange a user API token for a device token via the
+   * existing device registration endpoint. Persist the result locally and
+   * never touch the user token again.
+   */
+    static async pair({ serverUrl, userToken, name, type = 'edge', ...deviceInfo }) {
+        const res = await fetch(`${serverUrl.replace(/\/+$/, '')}/rest/v2/auth/devices/register`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${userToken}` },
+            body: JSON.stringify({ name, type, ...deviceInfo }),
+        });
+        const json = await res.json().catch(() => null);
+        if (!res.ok || !json?.payload?.token) {
+            throw new Error(`Edge pairing failed: ${json?.message || res.statusText}`);
+        }
+        return { token: json.payload.token, deviceId: json.payload.deviceId || json.payload.id };
+    }
+
+    get connected() {
+        return this.#socket?.connected === true;
+    }
+
+    connect() {
+        if (this.#socket) return this;
+        this.#socket = io(this.#serverUrl, {
+            auth: { token: this.#token },
+            transports: ['websocket'],
+        });
+        // Announce on every (re)connect — announce is idempotent full state.
+        this.#socket.on('connect', () => this.#socket.emit('edge:announce', this.#announce));
+        this.#socket.on('edge:announced', () => { this.#announced = true; });
+        this.#socket.on('disconnect', () => { this.#announced = false; });
+        this.#socket.on('edge:req', (frame) => this.handleRequest(frame));
+        return this;
+    }
+
+    /** Resolves once the server has acked the announce; rejects on timeout. */
+    waitForAnnounce(timeoutMs = 10_000) {
+        if (this.#announced) return Promise.resolve();
+        if (!this.#socket) return Promise.reject(new Error('not connected — call connect() first'));
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#socket?.off('edge:announced', onAck);
+                reject(new Error(`edge announce not acked within ${timeoutMs}ms`));
+            }, timeoutMs);
+            const onAck = () => { clearTimeout(timer); resolve(); };
+            this.#socket.once('edge:announced', onAck);
+        });
+    }
+
+    /**
+   * Dispatch a proxied request into the local app and stream the answer back.
+   * `socket` is injectable for tests.
+   */
+    async handleRequest(frame = {}, socket = this.#socket) {
+        const { id, method, path, headers = {}, body, bodyEncoding } = frame;
+        if (!id || !method || !path) return;
+        try {
+            const payload = body == null
+                ? undefined
+                : (bodyEncoding === 'base64' ? Buffer.from(body, 'base64') : body);
+            const res = await this.#localApp.inject({ method, url: path, headers, payload });
+            socket.emit('edge:res', { id, status: res.statusCode, headers: res.headers });
+            const buf = res.rawPayload;
+            for (let offset = 0, seq = 0; offset < buf.length; offset += CHUNK_SIZE, seq++) {
+                socket.emit('edge:chunk', { id, seq, data: buf.subarray(offset, offset + CHUNK_SIZE).toString('base64') });
+            }
+            socket.emit('edge:end', { id });
+        } catch (err) {
+            socket.emit('edge:err', { id, code: 'EDGE_DISPATCH_FAILED', message: err.message });
+        }
+    }
+
+    /**
+   * Relay all events from a local wildcard emitter (EventEmitter2) up the
+   * tunnel; the server re-emits them through its WorkspaceManager.
+   */
+    forwardEvents(emitter) {
+        const socket = () => this.#socket;
+        const listener = function (payload) {
+            socket()?.emit('edge:event', { name: this.event, payload });
+        };
+        emitter.on('**', listener);
+        this.#forwarded.push([emitter, listener]);
+        return this;
+    }
+
+    close() {
+        for (const [emitter, listener] of this.#forwarded) emitter.off('**', listener);
+        this.#forwarded = [];
+        this.#socket?.disconnect();
+        this.#socket = null;
+    }
+}

package/src/control.js

@@ -0,0 +1,48 @@
+'use strict';
+
+import fs from 'fs';
+import Fastify from 'fastify';
+import { EDGE_PATHS } from './env.js';
+
+/**
+ * Local control API for the CLI (unix socket, 0600; a localhost port on
+ * Windows). Nothing here is reachable from the network.
+ */
+export async function startControl({ runtimes, reload, shutdown, logger }) {
+    const app = Fastify({ logger: false });
+    const byId = (id) => runtimes.get(id) || [...runtimes.values()].find((r) => r.status().workspace === id) || null;
+
+    // fuse units read `canvas-fuse status --json` (a process); refresh them before answering.
+    const snapshot = async () => {
+        for (const r of runtimes.values()) if (typeof r.refresh === 'function') await r.refresh().catch(() => null);
+        return [...runtimes.values()].map((r) => r.status());
+    };
+    app.get('/status', async () => ({ pid: process.pid, mirrors: await snapshot() }));
+    app.get('/mirrors', async () => snapshot());
+    app.post('/mirrors/:id/resync', async (req, reply) => {
+        const r = byId(req.params.id);
+        if (!r) return reply.code(404).send({ error: 'no such mirror' });
+        await r.resync();
+        return r.status();
+    });
+    app.post('/mirrors/:id/nudge', async (req, reply) => {
+        const r = byId(req.params.id);
+        if (!r) return reply.code(404).send({ error: 'no such mirror' });
+        r.nudge();
+        return { ok: true };
+    });
+    app.post('/reload', async () => { await reload(); return { ok: true, mirrors: runtimes.size }; });
+    app.post('/shutdown', async () => { setTimeout(() => shutdown(), 50); return { ok: true }; });
+
+    if (EDGE_PATHS.socket) {
+        fs.mkdirSync(EDGE_PATHS.run, { recursive: true });
+        try { fs.unlinkSync(EDGE_PATHS.socket); } catch { /* absent */ }
+        await app.listen({ path: EDGE_PATHS.socket });
+        fs.chmodSync(EDGE_PATHS.socket, 0o600);
+        logger.info({ socket: EDGE_PATHS.socket }, 'control socket ready');
+    } else {
+        await app.listen({ host: '127.0.0.1', port: EDGE_PATHS.port });
+        logger.info({ port: EDGE_PATHS.port }, 'control port ready');
+    }
+    return app;
+}

package/src/daemon.js

@@ -0,0 +1,88 @@
+'use strict';
+
+import fs from 'fs';
+import path from 'path';
+import pino from 'pino';
+import { EDGE_PATHS, STATE_ROOT, daemonMirrors, deviceIdentity, ensureDeviceToken, ensureEnvConfig, fuseMirrors, hubFor } from './env.js';
+import { MirrorRuntime } from './mirror-runtime.js';
+import { FuseRuntime } from './fuse-runtime.js';
+import { startControl } from './control.js';
+
+/*
+ * canvas-edge: the device-side daemon for real-folder mirrors (the non-FUSE
+ * client of the sync protocol, for macOS/Windows and anyone who wants a plain
+ * folder). One process per device runs every `client: 'daemon'` mirror from
+ * ~/.canvas/config/mirrors.json; the CLI (`canvas mirror`) writes that file and
+ * talks to this process over the control socket.
+ */
+export async function main(argv = process.argv.slice(2)) {
+    const foreground = argv.includes('--foreground') || argv.includes('-f');
+    fs.mkdirSync(path.dirname(EDGE_PATHS.log), { recursive: true });
+    const logger = foreground
+        ? pino({ level: process.env.LOG_LEVEL || 'info' })
+        : pino({ level: process.env.LOG_LEVEL || 'info' }, pino.destination({ dest: EDGE_PATHS.log, sync: false }));
+
+    const runtimes = new Map();
+
+    // Container / env-driven setup: one remote + one mirror from the environment.
+    try {
+        const seeded = ensureEnvConfig();
+        if (seeded) logger.info({ mirror: seeded.id, folder: seeded.mountpoint, direction: seeded.direction, stateRoot: STATE_ROOT }, 'mirror configured from environment');
+    } catch (err) {
+        logger.error({ err: err?.message }, 'env-driven mirror config failed');
+    }
+
+    const load = async () => {
+        const wanted = daemonMirrors();
+        const fuse = fuseMirrors();
+        const wantedIds = new Set([...wanted, ...fuse].map((m) => m.id));
+        for (const [id, rt] of runtimes) {
+            if (!wantedIds.has(id)) { await rt.stop().catch(() => {}); runtimes.delete(id); logger.info({ mirror: id }, 'mirror stopped (removed from config)'); }
+        }
+        for (const mirror of wanted) {
+            if (runtimes.has(mirror.id)) continue;
+            let hub = hubFor(mirror.remote);
+            if (!hub?.token) { logger.warn({ mirror: mirror.id, remote: mirror.remote }, 'no credentials for hub — skipped'); continue; }
+            if (!hub.deviceId) {
+                try { hub = await ensureDeviceToken(mirror.remote, { logger }); }
+                catch (err) { logger.warn({ mirror: mirror.id, remote: mirror.remote, err: err?.message }, 'device registration failed — reporting under the user token'); }
+            }
+            const identity = deviceIdentity(hub);
+            const rt = new MirrorRuntime({ mirror, hub, identity, logger });
+            try {
+                await rt.start();
+                runtimes.set(mirror.id, rt);
+            } catch (err) {
+                logger.error({ mirror: mirror.id, err: err?.message }, 'mirror failed to start');
+            }
+        }
+        // fuse units: canvas-fuse mounts this daemon supervises (one process per workspace).
+        for (const mirror of fuse) {
+            if (runtimes.has(mirror.id)) continue;
+            const rt = new FuseRuntime({ mirror, logger });
+            try {
+                await rt.start();
+                runtimes.set(mirror.id, rt);
+            } catch (err) {
+                logger.error({ unit: mirror.id, err: err?.message }, 'fuse unit failed to start');
+            }
+        }
+    };
+
+    let stopping = false;
+    const shutdown = async () => {
+        if (stopping) return;
+        stopping = true;
+        logger.info('shutting down');
+        for (const rt of runtimes.values()) await rt.stop().catch(() => {});
+        await control?.close().catch(() => {});
+        process.exit(0);
+    };
+    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', shutdown);
+    process.on('SIGHUP', () => load().catch((err) => logger.error({ err: err?.message }, 'reload failed')));
+
+    const control = await startControl({ runtimes, reload: load, shutdown, logger });
+    await load();
+    logger.info({ device: deviceIdentity().deviceId, mirrors: runtimes.size, fuse: [...runtimes.values()].filter((r) => r.unit === 'fuse').length }, 'canvas-edge running');
+}

package/src/env.js

@@ -0,0 +1,182 @@
+'use strict';
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import EdgeClient from './EdgeClient.js';
+
+/*
+ * The daemon's own home. Deliberately NOT src/env.js: there CANVAS_USER_HOME
+ * means the server's users root, while for every client (cli, canvas-fuse,
+ * desktop) it is the per-user config home (~/.canvas). The daemon is a client.
+ */
+export const EDGE_HOME = process.env.CANVAS_EDGE_HOME
+    || process.env.CANVAS_USER_HOME
+    || (process.platform === 'win32' ? path.join(os.homedir(), 'Canvas') : path.join(os.homedir(), '.canvas'));
+
+export const EDGE_PATHS = Object.freeze({
+    home: EDGE_HOME,
+    mirrors: path.join(EDGE_HOME, 'config', 'mirrors.json'),
+    remotes: path.join(EDGE_HOME, 'config', 'remotes.json'),
+    device: process.env.CANVAS_DEVICE_FILE || (process.platform === 'win32'
+        ? path.join(os.homedir(), 'Canvas', 'device.json')
+        : path.join(os.homedir(), '.canvas', 'device.json')),
+    run: path.join(EDGE_HOME, 'run'),
+    socket: process.platform === 'win32' ? null : path.join(EDGE_HOME, 'run', 'edge.sock'),
+    port: Number(process.env.CANVAS_EDGE_PORT) || 8802,
+    log: path.join(EDGE_HOME, 'var', 'log', 'canvas-edge.log'),
+});
+
+export function readJson(file, fallback = null) {
+    try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return fallback; }
+}
+
+function writeJson(file, value) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n');
+}
+
+/*
+ * External state (docs/durable-workspaces.md, step 4). A mirror keeps its
+ * ledger, queue, cache, trash and conflicts under `<folder>/.workspace/` by
+ * default. A backup target (a NAS share) should hold user files only, so a
+ * mirror may name a `stateDir`, or the daemon may be given a root under
+ * which every mirror gets `<root>/<mirror id>` (the container sets
+ * CANVAS_EDGE_STATE_ROOT=/state).
+ */
+export const STATE_ROOT = process.env.CANVAS_EDGE_STATE_ROOT ? path.resolve(process.env.CANVAS_EDGE_STATE_ROOT) : null;
+
+export function resolveStateDir(mirror, stateRoot = STATE_ROOT) {
+    if (mirror?.stateDir) return path.resolve(String(mirror.stateDir));
+    if (stateRoot && mirror?.id) return path.join(stateRoot, String(mirror.id).replace(/[^a-zA-Z0-9._@-]+/g, '_'));
+    return null;   // null = inside the folder (`<folder>/.workspace`)
+}
+
+/*
+ * Env-driven single-mirror setup (the container's way in): with
+ * CANVAS_HUB_URL + CANVAS_HUB_TOKEN + CANVAS_WORKSPACE set, the daemon writes
+ * (or refreshes) one remote and one daemon mirror in its own config files
+ * before loading them. Idempotent: matched by id, only env-driven fields are
+ * overwritten, everything else the files carry is kept.
+ *
+ *   CANVAS_HUB_URL         https://canvas.example.org
+ *   CANVAS_HUB_TOKEN       user/API, device or workspace token
+ *   CANVAS_HUB_ID          remote id (default "hub")
+ *   CANVAS_WORKSPACE       workspace name (as in the hub URL)
+ *   CANVAS_MIRROR_PATH     folder to mirror (default /data)
+ *   CANVAS_DIRECTION       bi | pull | push (default bi)
+ *   CANVAS_CONFLICTS       prompt | rename        CANVAS_DELETES  propagate | keep
+ *   CANVAS_PINS / CANVAS_IGNORE   comma-separated globs
+ */
+export function ensureEnvConfig(env = process.env) {
+    const url = env.CANVAS_HUB_URL && String(env.CANVAS_HUB_URL).trim().replace(/\/+$/, '');
+    const token = env.CANVAS_HUB_TOKEN && String(env.CANVAS_HUB_TOKEN).trim();
+    const workspace = env.CANVAS_WORKSPACE && String(env.CANVAS_WORKSPACE).trim();
+    if (!url || !token || !workspace) return null;
+    const hubId = (env.CANVAS_HUB_ID && String(env.CANVAS_HUB_ID).trim()) || 'hub';
+    const list = (v) => String(v ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+    const oneOf = (v, allowed, fallback) => (allowed.includes(String(v ?? '').trim()) ? String(v).trim() : fallback);
+
+    const remotes = readJson(EDGE_PATHS.remotes, {}) || {};
+    const prior = remotes[hubId] || {};
+    // A device token minted for this remote stays authoritative; env only
+    // seeds the user/API token it started from.
+    remotes[hubId] = { ...prior, url, apiBase: prior.apiBase || '/rest/v2', auth: { ...(prior.auth || {}), token }, source: 'env' };
+    writeJson(EDGE_PATHS.remotes, remotes);
+
+    const cfg = readJson(EDGE_PATHS.mirrors, { version: 1, mirrors: [] }) || { version: 1, mirrors: [] };
+    const mirrors = Array.isArray(cfg.mirrors) ? cfg.mirrors : [];
+    const id = `${hubId}/${workspace.toLowerCase()}`;
+    const existing = mirrors.find((m) => m?.id === id) || {};
+    const mirror = {
+        ...existing,
+        id,
+        remote: hubId,
+        workspaceId: existing.workspaceId || null,
+        workspaceName: workspace.toLowerCase(),
+        folderName: existing.folderName || workspace,
+        mountpoint: path.resolve(env.CANVAS_MIRROR_PATH ? String(env.CANVAS_MIRROR_PATH) : (existing.mountpoint || '/data')),
+        pins: env.CANVAS_PINS != null ? list(env.CANVAS_PINS) : (existing.pins || []),
+        ignore: env.CANVAS_IGNORE != null ? list(env.CANVAS_IGNORE) : (existing.ignore || []),
+        conflicts: oneOf(env.CANVAS_CONFLICTS, ['prompt', 'rename'], existing.conflicts || 'prompt'),
+        deletes: oneOf(env.CANVAS_DELETES, ['propagate', 'keep'], existing.deletes || 'propagate'),
+        direction: oneOf(env.CANVAS_DIRECTION, ['bi', 'pull', 'push'], existing.direction || 'bi'),
+        client: 'daemon',
+        managed: existing.managed || 'container',
+        paused: false,
+        createdAt: existing.createdAt || new Date().toISOString(),
+        source: 'env',
+    };
+    cfg.mirrors = [...mirrors.filter((m) => m?.id !== id), mirror];
+    writeJson(EDGE_PATHS.mirrors, { version: cfg.version || 1, ...cfg, mirrors: cfg.mirrors });
+    return mirror;
+}
+
+/**
+ * Who this daemon is towards a hub. A device token is minted for one device
+ * id, so when remotes.json holds one, THAT id is the identity (the hub rejects
+ * status reports under any other); device.json is the fallback for
+ * user/API tokens, then a stable host-derived id.
+ */
+export function deviceIdentity(hub = null) {
+    const rec = readJson(EDGE_PATHS.device, null);
+    const name = process.env.CANVAS_DEVICE_NAME || rec?.hostname || os.hostname();
+    if (hub?.deviceId) return { deviceId: String(hub.deviceId), deviceName: name };
+    // A container's hostname is random per run: pin the identity explicitly.
+    if (process.env.CANVAS_DEVICE_ID) return { deviceId: String(process.env.CANVAS_DEVICE_ID).replace(/[^a-zA-Z0-9._-]+/g, '-'), deviceName: name };
+    if (rec?.deviceId) return { deviceId: String(rec.deviceId), deviceName: name };
+    return { deviceId: `host-${os.hostname()}-${os.userInfo().username}`.replace(/[^a-zA-Z0-9._-]+/g, '-'), deviceName: name };
+}
+
+/*
+ * An env-seeded remote starts with a user/API token. The hub keys mirror
+ * status (and replica protection) by DEVICE, so on first contact the daemon
+ * registers itself (`POST /auth/devices/register`) under its CANVAS_DEVICE_ID
+ * and keeps the device token in remotes.json; from then on hubFor() presents
+ * that token and the hub sees one stable device. CLI-managed remotes already
+ * carry a device token and are left alone.
+ */
+export async function ensureDeviceToken(remoteId, { logger = null } = {}) {
+    const remotes = readJson(EDGE_PATHS.remotes, {}) || {};
+    const r = remotes[remoteId];
+    if (!r?.url || r.source !== 'env' || r.device?.token || !r.auth?.token) return hubFor(remoteId);
+    const identity = deviceIdentity(null);
+    const paired = await EdgeClient.pair({
+        serverUrl: r.url, userToken: r.auth.token, name: identity.deviceName, type: 'edge',
+        deviceId: identity.deviceId, hostname: os.hostname(), platform: process.platform, arch: process.arch,
+    });
+    remotes[remoteId] = { ...r, device: { deviceId: paired.deviceId || identity.deviceId, token: paired.token, registeredAt: new Date().toISOString() } };
+    writeJson(EDGE_PATHS.remotes, remotes);
+    logger?.info?.({ remote: remoteId, deviceId: remotes[remoteId].device.deviceId }, 'registered as a device on the hub');
+    return hubFor(remoteId);
+}
+
+/** Hub url + token (+ the device id the token belongs to) for a remote id. */
+export function hubFor(remoteId) {
+    const remotes = readJson(EDGE_PATHS.remotes, {}) || {};
+    const r = remotes[remoteId];
+    if (!r?.url) return null;
+    const deviceToken = r.device?.token || null;
+    const token = deviceToken || r.auth?.token || null;
+    return {
+        id: remoteId,
+        url: String(r.url).replace(/\/+$/, ''),
+        apiBase: r.apiBase || '/rest/v2',
+        token,
+        deviceId: deviceToken && r.device?.deviceId ? String(r.device.deviceId) : null,
+    };
+}
+
+/** FUSE mounts this daemon supervises: `client: 'fuse', managed: 'edge'` entries (docs/durable-workspaces.md step 5). */
+export function fuseMirrors() {
+    const cfg = readJson(EDGE_PATHS.mirrors, { mirrors: [] }) || {};
+    return (Array.isArray(cfg.mirrors) ? cfg.mirrors : []).filter((m) => m && m.client === 'fuse' && m.managed === 'edge' && !m.paused);
+}
+
+/** Mirrors this daemon owns: `client: 'daemon'` entries of the CLI's mirrors.json. */
+export function daemonMirrors() {
+    const cfg = readJson(EDGE_PATHS.mirrors, { mirrors: [] }) || {};
+    return (Array.isArray(cfg.mirrors) ? cfg.mirrors : [])
+        .filter((m) => m && m.client === 'daemon' && !m.paused)
+        .map((m) => ({ ...m, stateDir: resolveStateDir(m) }));
+}

package/src/fuse-runtime.js

@@ -0,0 +1,173 @@
+'use strict';
+
+import { execFile, spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * A `fuse` unit: one canvas-fuse mirror mount supervised by this daemon
+ * (docs/durable-workspaces.md, step 5). canvas-fuse stays a plain executable —
+ * the on-demand namespace, content cache, pins and LRU are its own; this class
+ * only spawns `canvas-fuse mount … --mirror` attached, restarts it with backoff
+ * when it dies, reads `canvas-fuse status --json` for its state and unmounts
+ * on stop. One process per workspace under a common root (`<root>/<folder>`),
+ * several workspaces = several units in mirrors.json (`client: 'fuse',
+ * managed: 'edge'`). Credentials never touch the command line: the mount
+ * resolves `--remote <id>` from ~/.canvas/config/remotes.json, like the CLI.
+ */
+
+const DEFAULT_RESTART_DELAYS_MS = [5_000, 10_000, 20_000, 40_000, 60_000];
+const STATUS_TTL_MS = 5_000;
+
+export function fuseBinary(env = process.env) {
+    const candidates = [env.CANVAS_FUSE_BIN, path.join(os.homedir(), '.cargo', 'bin', 'canvas-fuse')].filter(Boolean);
+    for (const c of candidates) if (existsSync(c)) return c;
+    return 'canvas-fuse';   // PATH lookup at spawn time
+}
+
+/** Command line for one mirror entry (attached: no `-d`, the daemon owns the lifecycle). */
+export function fuseMountArgs(mirror) {
+    if (!mirror?.root) throw new Error(`fuse unit ${mirror?.id || '?'}: mirror.root is required`);
+    if (!mirror?.remote) throw new Error(`fuse unit ${mirror?.id || '?'}: mirror.remote is required`);
+    const args = ['mount', '-w', mirror.folderName || mirror.workspaceName, mirror.root, '--remote', mirror.remote, '--mirror'];
+    for (const pin of mirror.pins || []) args.push('--pin', pin);
+    for (const glob of mirror.ignore || []) args.push('--ignore', glob);
+    if (mirror.conflicts) args.push('--conflicts', mirror.conflicts);
+    if (mirror.deletes) args.push('--deletes', mirror.deletes);
+    if (mirror.cacheBudgetMb) args.push('--cache-budget-mb', String(mirror.cacheBudgetMb));
+    return args;
+}
+
+export class FuseRuntime {
+    #mirror;
+    #logger;
+    #bin;
+    #child = null;
+    #stopping = false;
+    #restartTimer = null;
+    #restarts = 0;
+    #attempt = 0;
+    #startedAt = null;
+    #lastExit = null;
+    #restartDelays;
+    #statusCache = null;
+
+    constructor({ mirror, logger, binary = null, restartDelaysMs = DEFAULT_RESTART_DELAYS_MS }) {
+        this.#mirror = mirror;
+        this.#logger = logger;
+        this.#bin = binary || fuseBinary();
+        this.#restartDelays = restartDelaysMs;
+    }
+
+    get id() { return this.#mirror.id; }
+    get unit() { return 'fuse'; }
+    get folder() { return this.#mirror.mountpoint || path.join(this.#mirror.root, this.#mirror.folderName || this.#mirror.workspaceName); }
+    get running() { return !!this.#child && this.#child.exitCode == null && !this.#child.killed; }
+    get pid() { return this.running ? this.#child.pid : null; }
+
+    async start() {
+        this.#stopping = false;
+        await this.#spawn();
+        this.#logger.info({ unit: this.id, mountpoint: this.folder, bin: this.#bin }, 'fuse unit started');
+    }
+
+    async #spawn() {
+        const args = fuseMountArgs(this.#mirror);
+        const child = spawn(this.#bin, args, { stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env } });
+        this.#child = child;
+        this.#startedAt = Date.now();
+        const log = (level) => (chunk) => { for (const line of String(chunk).split('\n')) if (line.trim()) this.#logger[level]?.({ unit: this.id }, line.trim()); };
+        child.stdout?.on('data', log('debug'));
+        child.stderr?.on('data', log('debug'));
+        await new Promise((resolve, reject) => {
+            child.once('spawn', resolve);
+            child.once('error', (err) => reject(Object.assign(new Error(err.code === 'ENOENT' ? `canvas-fuse binary not found (${this.#bin}); install it or set CANVAS_FUSE_BIN` : err.message), { code: err.code })));
+        });
+        child.on('exit', (code, signal) => {
+            if (this.#child !== child) return;
+            this.#child = null;
+            this.#lastExit = { code, signal, at: Date.now() };
+            this.#statusCache = null;
+            if (this.#stopping) return;
+            // A mount that stayed up a while starts the backoff over.
+            if (Date.now() - this.#startedAt > 60_000) this.#attempt = 0;
+            const delay = this.#restartDelays[Math.min(this.#attempt, this.#restartDelays.length - 1)];
+            this.#attempt += 1;
+            this.#restarts += 1;
+            this.#logger.warn({ unit: this.id, code, signal, restartInMs: delay }, 'fuse mount exited — restarting');
+            this.#restartTimer = setTimeout(() => {
+                this.#restartTimer = null;
+                this.#spawn().catch((err) => this.#logger.error({ unit: this.id, err: err?.message }, 'fuse restart failed'));
+            }, delay);
+            this.#restartTimer.unref?.();
+        });
+    }
+
+    /** Graceful: SIGINT (canvas-fuse unmounts on it), then SIGTERM, then a best-effort `unmount`. */
+    async stop({ timeoutMs = 10_000 } = {}) {
+        this.#stopping = true;
+        if (this.#restartTimer) { clearTimeout(this.#restartTimer); this.#restartTimer = null; }
+        const child = this.#child;
+        if (child && child.exitCode == null) {
+            const exited = new Promise((resolve) => child.once('exit', resolve));
+            child.kill('SIGINT');
+            const timer = new Promise((resolve) => setTimeout(resolve, timeoutMs));
+            if (await Promise.race([exited.then(() => true), timer.then(() => false)]) === false) {
+                child.kill('SIGTERM');
+                await Promise.race([exited, new Promise((resolve) => setTimeout(resolve, 3_000))]);
+            }
+        }
+        this.#child = null;
+        await this.#run(['unmount', this.folder], { timeout: 15_000 }).catch(() => null);
+        this.#logger.info({ unit: this.id, mountpoint: this.folder }, 'fuse unit stopped');
+    }
+
+    async #run(args, { timeout = 30_000 } = {}) {
+        const { stdout } = await execFileAsync(this.#bin, args, { timeout, maxBuffer: 4 * 1024 * 1024 });
+        return String(stdout || '');
+    }
+
+    /** The mount's own account (`canvas-fuse status --json` row for this mountpoint), cached briefly. */
+    async mountStatus() {
+        if (this.#statusCache && Date.now() - this.#statusCache.at < STATUS_TTL_MS) return this.#statusCache.row;
+        let row = null;
+        try {
+            const parsed = JSON.parse(await this.#run(['status', '--json'], { timeout: 15_000 }) || '[]');
+            const rows = Array.isArray(parsed) ? parsed : (Array.isArray(parsed?.mounts) ? parsed.mounts : []);
+            const target = path.resolve(this.folder);
+            row = rows.find((r) => path.resolve(r?.mountpoint || '') === target) || null;
+        } catch { row = null; }
+        this.#statusCache = { at: Date.now(), row };
+        return row;
+    }
+
+    /** Sync snapshot; `status()` is what the control API and the CLI show. */
+    status() {
+        const row = this.#statusCache?.row || null;
+        return {
+            id: this.id,
+            unit: 'fuse',
+            workspace: this.#mirror.workspaceName,
+            hub: this.#mirror.remote,
+            folder: this.folder,
+            pins: this.#mirror.pins || [],
+            conflictsMode: this.#mirror.conflicts,
+            direction: 'bi',
+            pid: this.pid,
+            running: this.running,
+            restarts: this.#restarts,
+            startedAt: this.#startedAt,
+            lastExit: this.#lastExit,
+            mount: row ? (row.status || (row.mounted ? 'ok' : 'down')) : (this.running ? 'starting' : 'down'),
+            ...(row?.mirror && typeof row.mirror === 'object' ? row.mirror : {}),
+        };
+    }
+
+    async refresh() { await this.mountStatus(); return this.status(); }
+    nudge() { this.#run(['sync', 'now', this.folder]).catch(() => null); }
+    async resync() { await this.#run(['sync', 'now', this.folder]).catch(() => null); return this.status(); }
+}

package/src/index.js

@@ -0,0 +1,26 @@
+'use strict';
+
+/**
+ * @augmentd-labs/canvas-edge — the device-side Canvas runtime.
+ *
+ * Two jobs today, one process (`bin/canvas-edge`):
+ *   mirror  — keep real folders in sync with hub workspaces (canvas-stored's
+ *             Mirror engine; state under <folder>/.workspace/)
+ *   tunnel  — EdgeClient dials out to a canvas-server, announces what this
+ *             runtime hosts and replays proxied requests into a local fastify
+ *             app, so a remote workspace/agent behaves as if server-local
+ *
+ * Zero canvas-server imports on purpose: the same package backs `ws`,
+ * canvas-agentd and the desktop sidecar. The hub side of the tunnel
+ * (EdgeRegistry) lives in canvas-server. Protocol: canvas-server
+ * docs/canvas-edge-protocol.md; sync wire contract: docs/sync-protocol.md.
+ */
+
+export { default as EdgeClient } from './EdgeClient.js';
+export { connectRemotes, buildAnnounce } from './runtime.js';
+export { readWorkspaceConfig, listRemotes, saveRemote, removeRemote } from './remote-config.js';
+export { EDGE_HOME, EDGE_PATHS, deviceIdentity, hubFor, daemonMirrors, fuseMirrors } from './env.js';
+export { MirrorRuntime } from './mirror-runtime.js';
+export { FuseRuntime, fuseMountArgs, fuseBinary } from './fuse-runtime.js';
+export { startControl } from './control.js';
+export { main } from './daemon.js';