@rse/ase 2.0.2 → 2.0.4

package/dst/ase-man.js

@@ -5,13 +5,14 @@
 */
 import path from "node:path";
 import fs from "node:fs";
-import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { writeStdout } from "./ase-lib-stdio.js";
+/*  the width of the manual pages printed as plain text  */
+const WIDTH = 80;
 /*  reusable functionality: resolve the internally shipped manual pages  */
 export class Man {
     /*  determine the directory of the manual pages; the build process
-        renders "man/*.md" into "dst/man/*.1" (see the "build-man" build
+        copies "man/*.md" into "dst/man/*.md" (see the "build-man" build
         step), right next to the compiled tool  */
     static dir() {
         return path.join(path.dirname(fileURLToPath(import.meta.url)), "man");
@@ -26,15 +27,15 @@ export class Man {
             throw new Error(`man: no manual pages found in "${Man.dir()}" (tool not completely built?)`, { cause: err });
         }
         return files
-            .filter((file) => /^ase(?:-[a-z0-9-]+)?\.\d$/.test(file))
-            .map((file) => file.replace(/\.\d$/, ""))
+            .filter((file) => /^ase(?:-[a-z0-9-]+)?\.md$/.test(file))
+            .map((file) => file.replace(/\.md$/, ""))
             .sort((a, b) => a.localeCompare(b, "en", { numeric: true }));
     }
-    /*  resolve the words of a requested manual page to the absolute path of
-        its file: the words are joined with dashes, the "ase" prefix is optional,
-        and a command path deeper than the shipped pages (e.g. "ase task store
-        start") falls back to the page of its nearest parent (e.g. "ase-task-store"),
-        as the pages of a group with third-level commands cover them  */
+    /*  resolve the words of a requested manual page to its name: the words
+        are joined with dashes, the "ase" prefix is optional, and a command path
+        deeper than the shipped pages (e.g. "ase task store start") falls back to
+        the page of its nearest parent (e.g. "ase-task-store"), as the pages of a
+        group with third-level commands cover them  */
     static resolve(words) {
         const name = words.join("-").toLowerCase();
         if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name))
@@ -46,7 +47,7 @@ export class Man {
         while (parts.length > 0) {
             const page = parts.join("-");
             if (pages.has(page))
-                return path.join(Man.dir(), `${page}.1`);
+                return page;
             parts.pop();
             if (parts.length === 1)
                 break;
@@ -64,33 +65,38 @@ export default class ManCommand {
     register(program) {
         program
             .command("man")
-            .description("Show an internally shipped manual page with man(1)")
+            .description("Browse all manual pages interactively, or print a manual page as plain text")
             .argument("[page...]", "manual page name, either as \"ase-<command>[-<sub-command>]\" " +
-            "or as the words of the command path (\"ase\" prefix optional, default: \"ase\")")
+            "or as the words of the command path (\"ase\" prefix optional), selected in the " +
+            "interactive browser on a terminal (or searched for, if no manual page fits exactly), " +
+            "else printed as plain text (default: \"ase\")")
             .option("-l, --list", "list the names of all shipped manual pages instead", false)
-            .option("-p, --path", "print the path of the manual page file instead", false)
             .action(async (words, opts) => {
             /*  list all manual pages  */
             if (opts.list) {
                 await writeStdout(Man.list().map((page) => `${page}\n`).join(""));
                 return;
             }
-            /*  resolve manual page  */
-            const file = Man.resolve(words.length > 0 ? words : ["ase"]);
-            if (opts.path) {
-                await writeStdout(`${file}\n`);
+            /*  browse all manual pages interactively (only on a terminal), with
+                the given manual page selected resp. searched for (if any)  */
+            if (process.stdin.isTTY && process.stdout.isTTY) {
+                const { runManTUI } = await import("./ase-man-tui.js");
+                await runManTUI(this.log, words);
                 return;
             }
-            /*  show manual page with man(1), passing the file by its path,
-                which all common man(1) implementations support  */
-            this.log.write("debug", `man: showing manual page "${file}"`);
-            const result = spawnSync("man", [file], { stdio: "inherit" });
-            if (result.error !== undefined) {
-                const message = result.error.message;
-                throw new Error(`man: failed to run man(1): ${message} ` +
-                    `(the manual page file is "${file}")`, { cause: result.error });
-            }
-            process.exitCode = result.status ?? 1;
+            /*  resolve manual page, where a skill or command fitting exactly
+                is preferred over the fallback onto the nearest parent command  */
+            const { loadCatalog, findPage } = await import("./ase-man-catalog.js");
+            const { renderPage } = await import("./ase-man-render.js");
+            const catalog = loadCatalog();
+            const request = words.length > 0 ? words : ["ase"];
+            const page = findPage(catalog, request) ?? catalog.pages.get(`${Man.resolve(request)}.1`);
+            if (page === undefined)
+                throw new Error(`man: no manual page found for "${request.join(" ")}" (see "ase man --list")`);
+            /*  print manual page as plain text  */
+            this.log.write("debug", `man: printing manual page "${page.id}"`);
+            const { lines } = renderPage(page.md, WIDTH, page.id, (id) => catalog.pages.has(id));
+            await writeStdout(lines.map((line) => line.map((span) => span.text).join("").trimEnd() + "\n").join(""));
         });
     }
 }

package/dst/ase-mcp.js

@@ -72,7 +72,7 @@ export default class MCPCommand {
             const value = state.getExplicit("basedir");
             return typeof value === "string" && value !== "" ? value : null;
         }
-        catch (_e) {
+        catch {
             /*  best-effort: an unreadable session config just defers the lookup  */
             return null;
         }
@@ -139,7 +139,7 @@ export default class MCPCommand {
             next.onerror = (err) => {
                 this.log.write("error", `mcp: http: ${err.message}`);
             };
-            /*  service closed the connection — try to recover  */
+            /*  service closed the connection -- try to recover  */
             next.onclose = () => {
                 if (client !== next || closedByUs.has(next) || bridgeDone || reconnecting)
                     return;
@@ -183,7 +183,7 @@ export default class MCPCommand {
             if (reconnecting)
                 return;
             reconnecting = true;
-            this.log.write("warning", `mcp: ${reason} — reconnecting`);
+            this.log.write("warning", `mcp: ${reason} -- reconnecting`);
             reconnect(0).catch(() => { });
         };
         /*  bounded buffer for messages arriving while no HTTP client is connected  */
@@ -315,7 +315,7 @@ export default class MCPCommand {
                 await connectClient();
             }
             catch (err) {
-                /*  service vanished between probe and connect — recover instead of crashing  */
+                /*  service vanished between probe and connect -- recover instead of crashing  */
                 triggerReconnect(`initial connect failed: ${this.asError(err).message}`);
             }
         }

package/dst/ase-service-getopt.js

@@ -23,7 +23,7 @@ const tokenizeRanges = (input) => {
                 const quote = ch;
                 i++;
                 while (i < input.length && input[i] !== quote) {
-                    if (input[i] === "\\" && i + 1 < input.length)
+                    if (quote === "\"" && input[i] === "\\" && i + 1 < input.length)
                         i++;
                     i++;
                 }
@@ -50,7 +50,7 @@ const unquote = (s) => {
             const quote = ch;
             j++;
             while (j < s.length && s[j] !== quote) {
-                if (s[j] === "\\" && j + 1 < s.length) {
+                if (quote === "\"" && s[j] === "\\" && j + 1 < s.length) {
                     out += s[j + 1];
                     j += 2;
                 }

package/dst/ase-service-otel.js

@@ -580,7 +580,7 @@ export class UsageTracker {
         const self = userId();
         if (assignee.trim() === "")
             throw new Error("usage: empty assignee (use \"none\" to unassign)");
-        const to = assignee === "me" ? self : assignee.trim();
+        const to = assignee.trim() === "me" ? self : assignee.trim();
         /*  (keep the session out of the adoptions meanwhile, and let an assignment to oneself
             settle the adoption of its active task, as the explicit assignment takes precedence)  */
         this.explicit.add(session);
@@ -591,6 +591,7 @@ export class UsageTracker {
             this.explicit.delete(session);
         }
     }
+    /*  perform the assignment of "assign" (with the session kept out of the adoptions)  */
     async assignSession(id, to, self, session) {
         const warning = await Task.checkAssignee(this.log, to);
         const from = await Task.assign(this.log, id, to === "none" ? null : to);
@@ -952,6 +953,7 @@ export class UsageTracker {
             this.unwatch = null;
         }
     }
+    /*  close resp. implicitly account the open windows of the watched tasks whose assignee changed elsewhere  */
     async check() {
         for (const task of Array.from(this.watched)) {
             const w = this.openWindow(task);
@@ -1212,9 +1214,7 @@ export class UsageTracker {
         (dropping the records of unregistered sessions), with the session registry
         re-read from the telemetry state file only once the file changed  */
     route(records) {
-        const bySession = new Map();
-        for (const r of records)
-            bySession.set(r.session, [...(bySession.get(r.session) ?? []), r]);
+        const bySession = Map.groupBy(records, (r) => r.session);
         let registry;
         try {
             const file = UsageTracker.stateFile();

package/dst/ase-service-skills.js

@@ -187,7 +187,8 @@ export class Skills {
             if (m === null)
                 return "N.A.";
             const base = parseFloat(m[1].replace(/,/g, ""));
-            const mult = m[2] === "K" ? 1_000 : m[2] === "M" ? 1_000_000 : m[2] === "B" ? 1_000_000_000 : 1;
+            const unit = m[2].toUpperCase();
+            const mult = unit === "K" ? 1_000 : unit === "M" ? 1_000_000 : unit === "B" ? 1_000_000_000 : 1;
             const n = Math.round(base * mult);
             return Number.isFinite(n) ? n : "N.A.";
         }
@@ -246,20 +247,9 @@ export class Skills {
         const now = Date.now();
         const msPerDay = 1000 * 60 * 60 * 24;
         const halfLife = 365 / 2;
-        /*  lifespan requires both timestamps; recentness requires the
-            updated timestamp -- any unavailable date-derived factor is
-            given a neutral default so the entry can still be ranked by the
-            remaining metrics, instead of collapsing the product to zero.
-            For `lifespan` (an unbounded duration) the multiplicative-neutral
-            `1` is also the low floor, so a missing value cannot unfairly
-            inflate the rank. For `recentness`, however, the value is an
-            exp-decay factor bounded in `(0,1]` where `1` is the *ceiling*
-            (a just-now update), not a floor -- defaulting a missing update
-            date to `1` would hand packages with absent metadata the highest
-            possible recentness and let them outrank genuinely fresh ones.
-            We therefore default a missing `recentness` to the decay value at
-            one half-life (`0.5`), a conservative midpoint that keeps the
-            entry rankable without rewarding the missing date.  */
+        /*  an unavailable date-derived factor gets a neutral default: a missing lifespan
+            its floor "1", a missing recentness (whose ceiling is "1") the decay value at
+            one half-life ("0.5"), so a missing date is never rewarded  */
         const lifespan = (!Number.isNaN(cMs) && !Number.isNaN(uMs)) ? Math.max(1, uMs - cMs) : 1;
         const recentness = !Number.isNaN(uMs) ? 0.5 ** (Math.max(0, (now - uMs) / msPerDay) / halfLife) : 0.5;
         let rank = d * s * lifespan * recentness;

package/dst/ase-service.js

@@ -5,7 +5,6 @@
 */
 import path from "node:path";
 import fs from "node:fs";
-import net from "node:net";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 import Hapi from "@hapi/hapi";
@@ -13,7 +12,6 @@ import { ofetch } from "ofetch";
 import { isMap } from "yaml";
 import prettyMs from "pretty-ms";
 import * as v from "valibot";
-import { Tail } from "tail";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { ConfigMCP } from "./ase-config.js";
@@ -21,6 +19,7 @@ import { Config } from "./ase-config-core.js";
 import { configSchema } from "./ase-config-schema.js";
 import { ensureAseGitignore } from "./ase-config-scope.js";
 import { isLogLevel } from "./ase-lib-log.js";
+import { Daemon } from "./ase-lib-daemon-cli.js";
 import { CompatMCP } from "./ase-util-compat.js";
 import { DiagramMCP } from "./ase-util-diagram.js";
 import { Task, TaskMCP } from "./ase-task.js";
@@ -76,14 +75,7 @@ const PORT_ENV = "ASE_SERVICE_PORT";
 const LEVEL_ENV = "ASE_SERVICE_LOG_LEVEL";
 const IDLE_MS = 30 * 60 * 1000;
 const TICK_MS = 60 * 1000;
-const PORT_MIN = 42000;
-const PORT_MAX = 44000;
-const PORT_TRIES = 20;
-/*  bounds for the append-only ".ase/service.log" file:
-    maximum tolerated size, number of tail lines surviving a trim,
-    and maximum length of the MCP tool call arguments logged per request  */
-const LOG_MAX_SIZE = 1024 * 1024;
-const LOG_KEEP_LINES = 2000;
+/*  maximum length of the MCP tool call arguments logged per request  */
 const LOG_ARGS_MAX = 200;
 /*  load the optional "config.yaml" and "service.yaml" files and derive
     the service identity context (project id, port, preferred port, service config)  */
@@ -105,33 +97,8 @@ export const loadServiceContext = (log) => {
     /*  return context information  */
     return { projectId, port, portPref, svc, aseDir };
 };
-/*  reusable functionality: port allocation, persistence, and process spawning  */
+/*  reusable functionality: port persistence and process spawning  */
 export class Service {
-    /*  try binding a single candidate port to verify availability  */
-    static tryBind(port) {
-        return new Promise((resolve) => {
-            const s = net.createServer();
-            s.once("error", () => {
-                resolve(false);
-            });
-            s.once("listening", () => {
-                s.close(() => resolve(true));
-            });
-            s.listen(port, HOST);
-        });
-    }
-    /*  allocate the preferred port, if given and available,
-        else a fresh random port in PORT_MIN..PORT_MAX  */
-    static async allocatePort(pref = null) {
-        if (pref !== null && await Service.tryBind(pref))
-            return pref;
-        for (let i = 0; i < PORT_TRIES; i++) {
-            const p = PORT_MIN + Math.floor(Math.random() * (PORT_MAX - PORT_MIN + 1));
-            if (await Service.tryBind(p))
-                return p;
-        }
-        throw new Error(`failed to allocate a port in ${PORT_MIN}..${PORT_MAX} after ${PORT_TRIES} attempts`);
-    }
     /*  persist an allocated port into ".ase/service.yaml"  */
     static persistPort(svc, port) {
         ensureAseGitignore(path.dirname(svc.filename));
@@ -156,19 +123,6 @@ export class Service {
                 svc.write();
         });
     }
-    /*  trim the log file down to its tail if it grew beyond the size limit  */
-    static trimLog(logFile) {
-        try {
-            if (!fs.existsSync(logFile) || fs.statSync(logFile).size <= LOG_MAX_SIZE)
-                return;
-            const tail = Service.readLogTail(logFile, LOG_KEEP_LINES);
-            fs.writeFileSync(logFile, tail.length > 0 ? `${tail}\n` : "");
-        }
-        catch {
-            /*  intentionally ignore all trimming errors, as a
-                non-trimmable log file must never block the service  */
-        }
-    }
     /*  spawn the current executable detached as a background service  */
     static spawnDetached(aseDir, port, logLevel) {
         fs.mkdirSync(aseDir, { recursive: true });
@@ -177,7 +131,7 @@ export class Service {
         /*  trim the log before handing it to the service, as the detached
             service inherits the file descriptor for its entire lifetime and
             hence cannot rotate the file itself while it is running  */
-        Service.trimLog(logFile);
+        Daemon.trimLog(logFile);
         const fd = fs.openSync(logFile, "a");
         const entry = fileURLToPath(new URL("./ase.js", import.meta.url));
         const child = spawn(process.execPath, [entry, "service", "start"], {
@@ -188,68 +142,6 @@ export class Service {
         fs.closeSync(fd);
         return { child, logFile };
     }
-    /*  read the last N non-empty lines of a log file for diagnostics  */
-    static readLogTail(logFile, lines) {
-        let fd = null;
-        try {
-            fd = fs.openSync(logFile, "r");
-            const size = fs.fstatSync(fd).size;
-            const CHUNK = 8192;
-            const chunks = [];
-            let pos = size;
-            let count = 0;
-            while (pos > 0 && count <= lines) {
-                const n = Math.min(CHUNK, pos);
-                const buf = Buffer.alloc(n);
-                pos -= n;
-                fs.readSync(fd, buf, 0, n, pos);
-                chunks.unshift(buf);
-                for (let i = 0; i < n; i++)
-                    if (buf[i] === 10)
-                        count++;
-            }
-            /*  decode once after re-assembly to avoid splitting
-                multi-byte UTF-8 sequences at chunk boundaries  */
-            const all = Buffer.concat(chunks).toString("utf8")
-                .split("\n").filter((l) => l.length > 0);
-            return all.slice(-lines).join("\n");
-        }
-        catch {
-            return "";
-        }
-        finally {
-            if (fd !== null)
-                fs.closeSync(fd);
-        }
-    }
-    /*  show a log file on stdout, either completely or its last <lines> lines only, and
-        optionally follow it for newly appended lines (default: the last 10 lines first),
-        where each line is passed through <transform> (e.g. to colorize parts of it)  */
-    static async showLog(logFile, opts, transform = (line) => line) {
-        const lines = opts.lines !== undefined ? Number(opts.lines) : null;
-        if (lines !== null && (!Number.isInteger(lines) || lines < 1))
-            throw new Error(`invalid number of lines: ${opts.lines}`);
-        if (!fs.existsSync(logFile))
-            return 0;
-        if (opts.follow) {
-            /*  follow until interrupted (on log trimming,
-                "tail" continues at the new end of the file)  */
-            const tail = new Tail(logFile, { nLines: lines ?? 10 });
-            tail.on("line", (line) => {
-                process.stdout.write(`${transform(line)}\n`);
-            });
-            return await new Promise((_resolve, reject) => {
-                tail.on("error", (err) => {
-                    reject(err instanceof Error ? err : new Error(String(err)));
-                });
-            });
-        }
-        const text = lines !== null ?
-            Service.readLogTail(logFile, lines) :
-            fs.readFileSync(logFile, "utf8").replace(/\n$/, "");
-        process.stdout.write(text.length > 0 ? `${text.split("\n").map(transform).join("\n")}\n` : "");
-        return 0;
-    }
 }
 /*  MCP registration entry point for service-identity tools  */
 export class ServiceMCP {
@@ -332,6 +224,68 @@ export default class ServiceCommand {
         }
         return { method: bMethod, info };
     }
+    /*  register the endpoints of the AI usage accounting: the usage records forwarded
+        by the OTLP ingress, the session end, the task assignment on behalf of a session,
+        and the task rename  */
+    static registerUsageRoutes(server, usage) {
+        server.route({
+            method: "POST",
+            path: "/usage/records",
+            options: { payload: { parse: true, allow: "application/json", maxBytes: 32 * 1024 * 1024 } },
+            handler: (request, h) => {
+                const payload = request.payload;
+                if (!Array.isArray(payload?.records))
+                    return h.response({ error: "missing or invalid 'records' field" }).code(400);
+                usage.ingest(payload.records);
+                return h.response({ ok: true }).code(200);
+            }
+        });
+        server.route({
+            method: "POST",
+            path: "/usage/detach",
+            options: { payload: { parse: true, allow: "application/json" } },
+            handler: (request, h) => {
+                const payload = request.payload;
+                if (typeof payload?.session !== "string")
+                    return h.response({ error: "missing or invalid 'session' field" }).code(400);
+                usage.detach(payload.session);
+                return h.response({ ok: true }).code(200);
+            }
+        });
+        server.route({
+            method: "POST",
+            path: "/usage/rename",
+            options: { payload: { parse: true, allow: "application/json" } },
+            handler: (request, h) => {
+                const payload = request.payload;
+                if (typeof payload?.old !== "string" || typeof payload.new !== "string")
+                    return h.response({ error: "missing or invalid 'old' or 'new' field" }).code(400);
+                try {
+                    usage.rename(payload.old, payload.new);
+                }
+                catch (err) {
+                    return h.response({ error: err instanceof Error ? err.message : String(err) }).code(422);
+                }
+                return h.response({ ok: true }).code(200);
+            }
+        });
+        server.route({
+            method: "POST",
+            path: "/usage/assign",
+            options: { payload: { parse: true, allow: "application/json" } },
+            handler: async (request, h) => {
+                const payload = request.payload;
+                if (typeof payload?.id !== "string" || typeof payload.assignee !== "string" || typeof payload.session !== "string")
+                    return h.response({ error: "missing or invalid 'id', 'assignee', or 'session' field" }).code(400);
+                try {
+                    return h.response(await usage.assign(payload.id, payload.assignee, payload.session)).code(200);
+                }
+                catch (err) {
+                    return h.response({ error: err instanceof Error ? err.message : String(err) }).code(422);
+                }
+            }
+        });
+    }
     /*  service-side: bind HAPI server until "/stop" command is received or idle timeout happens
         (or, in the foreground, until "/stop" command is received or a termination signal arrives)  */
     async runService(ctx, foreground = false) {
@@ -361,6 +315,18 @@ export default class ServiceCommand {
         const usage = new UsageTracker(this.log, Task.projectRoot(), ctx.projectId, ctx.aseDir, () => {
             lastActivity = Date.now();
         });
+        /*  stop the HTTP server and the usage tracker, clear the persisted port, and exit  */
+        const stopService = async () => {
+            try {
+                await server.stop({ timeout: 1000 });
+            }
+            catch (err) {
+                this.log.write("error", `service: stop failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            await usage.stop();
+            Service.clearPort(ctx.svc);
+            process.exit(0);
+        };
         /*  listen to HTTP/REST endpoints  */
         server.route({
             method: "OPTIONS",
@@ -379,17 +345,7 @@ export default class ServiceCommand {
                 if (!ct.startsWith("application/json"))
                     return h.response({ error: "unsupported media type" }).code(415);
                 this.log.write("info", "service: stop requested");
-                setImmediate(async () => {
-                    try {
-                        await server.stop({ timeout: 1000 });
-                    }
-                    catch (err) {
-                        const e = err;
-                        this.log.write("error", `service: stop failed: ${e.message}`);
-                    }
-                    await usage.stop();
-                    process.exit(0);
-                });
+                setImmediate(stopService);
                 return h.response({ ok: true }).code(200);
             }
         });
@@ -456,66 +412,8 @@ export default class ServiceCommand {
                 return h.response({ error: "unknown command", command: cmd }).code(400);
             }
         });
-        /*  listen to the endpoints of the AI usage accounting: the usage records forwarded
-            by the OTLP ingress, the session end, the task assignment on behalf of a session,
-            and the task rename  */
-        server.route({
-            method: "POST",
-            path: "/usage/records",
-            options: { payload: { parse: true, allow: "application/json", maxBytes: 32 * 1024 * 1024 } },
-            handler: (request, h) => {
-                const payload = request.payload;
-                if (!Array.isArray(payload?.records))
-                    return h.response({ error: "missing or invalid 'records' field" }).code(400);
-                usage.ingest(payload.records);
-                return h.response({ ok: true }).code(200);
-            }
-        });
-        server.route({
-            method: "POST",
-            path: "/usage/detach",
-            options: { payload: { parse: true, allow: "application/json" } },
-            handler: (request, h) => {
-                const payload = request.payload;
-                if (typeof payload?.session !== "string")
-                    return h.response({ error: "missing or invalid 'session' field" }).code(400);
-                usage.detach(payload.session);
-                return h.response({ ok: true }).code(200);
-            }
-        });
-        server.route({
-            method: "POST",
-            path: "/usage/rename",
-            options: { payload: { parse: true, allow: "application/json" } },
-            handler: (request, h) => {
-                const payload = request.payload;
-                if (typeof payload?.old !== "string" || typeof payload.new !== "string")
-                    return h.response({ error: "missing or invalid 'old' or 'new' field" }).code(400);
-                try {
-                    usage.rename(payload.old, payload.new);
-                }
-                catch (err) {
-                    return h.response({ error: err instanceof Error ? err.message : String(err) }).code(422);
-                }
-                return h.response({ ok: true }).code(200);
-            }
-        });
-        server.route({
-            method: "POST",
-            path: "/usage/assign",
-            options: { payload: { parse: true, allow: "application/json" } },
-            handler: async (request, h) => {
-                const payload = request.payload;
-                if (typeof payload?.id !== "string" || typeof payload.assignee !== "string" || typeof payload.session !== "string")
-                    return h.response({ error: "missing or invalid 'id', 'assignee', or 'session' field" }).code(400);
-                try {
-                    return h.response(await usage.assign(payload.id, payload.assignee, payload.session)).code(200);
-                }
-                catch (err) {
-                    return h.response({ error: err instanceof Error ? err.message : String(err) }).code(422);
-                }
-            }
-        });
+        /*  listen to the endpoints of the AI usage accounting  */
+        ServiceCommand.registerUsageRoutes(server, usage);
         /*  serve the web board of the project (imported dynamically to keep it out of all
             other CLI commands; its rendering dependencies marked, MRCS, and ELK load on
             first request only, its board core dependencies at service startup)  */
@@ -549,16 +447,7 @@ export default class ServiceCommand {
                     return;
                 stopping = true;
                 this.log.write("info", `service: received ${signal}, stopping`);
-                try {
-                    await server.stop({ timeout: 1000 });
-                }
-                catch (err) {
-                    const e = err;
-                    this.log.write("error", `service: stop failed: ${e.message}`);
-                }
-                await usage.stop();
-                Service.clearPort(ctx.svc);
-                process.exit(0);
+                await stopService();
             };
             process.on("SIGTERM", () => shutdown("SIGTERM"));
             process.on("SIGINT", () => shutdown("SIGINT"));
@@ -578,25 +467,13 @@ export default class ServiceCommand {
             if (Date.now() - lastActivity > IDLE_MS) {
                 stopping = true;
                 this.log.write("info", "service: idle timeout reached, stopping");
-                try {
-                    await server.stop({ timeout: 1000 });
-                    await usage.stop();
-                    Service.clearPort(ctx.svc);
-                    process.exit(0);
-                }
-                catch (err) {
-                    const e = err;
-                    this.log.write("error", `service: stop failed: ${e.message}`);
-                    await usage.stop();
-                    Service.clearPort(ctx.svc);
-                    process.exit(1);
-                }
+                await stopService();
             }
         }, TICK_MS).unref();
     }
     /*  allocate the service port, preferring the configured one, else falling back to a random one  */
     async allocatePort(ctx) {
-        const port = await Service.allocatePort(ctx.portPref);
+        const port = await Daemon.allocatePort(ctx.portPref);
         if (ctx.portPref !== null && port !== ctx.portPref)
             this.log.write("warning", `service: preferred port ${ctx.portPref} unavailable, falling back to port ${port}`);
         return port;
@@ -612,7 +489,7 @@ export default class ServiceCommand {
             if (level !== undefined && isLogLevel(level))
                 this.log.logLevel(level);
             const raw = process.env[PORT_ENV];
-            port = raw !== undefined ? Number(raw) : await Service.allocatePort();
+            port = raw !== undefined ? Number(raw) : await Daemon.allocatePort();
             await this.runService({ ...ctx, port });
             return await new Promise(() => { });
         }
@@ -668,7 +545,7 @@ export default class ServiceCommand {
                         break;
                     }
                 }
-                const tail = Service.readLogTail(logFile, 20);
+                const tail = Daemon.readLogTail(logFile, 20);
                 const reason = exited ?
                     `service exited during startup (code ${exitCode})` :
                     foreign ?
@@ -755,7 +632,7 @@ export default class ServiceCommand {
     /*  log flow: show the (tail of the) log file and optionally follow it  */
     async doLog(opts) {
         const ctx = this.loadContext();
-        return Service.showLog(path.join(ctx.aseDir, "service.log"), opts);
+        return Daemon.showLog(path.join(ctx.aseDir, "service.log"), opts);
     }
     /*  stop flow: no-op if no port configured or connection refused  */
     async doStop() {

package/dst/ase-setup-common.js

@@ -51,8 +51,7 @@ export class SetupRunner {
         if (process.platform === "win32")
             return false;
         /*  already running as root  */
-        const getuid = process.getuid;
-        if (typeof getuid === "function" && getuid.call(process) === 0)
+        if (process.getuid?.() === 0)
             return false;
         /*  determine the npm global prefix and probe writability of the
             directories that "npm -g" actually mutates  */