@rse/ase 0.0.28 → 0.0.29

package/dst/ase-config.js

@@ -11,6 +11,8 @@ import { Document, parseDocument, isMap, isScalar } from "yaml";
 import { execaSync } from "execa";
 import * as v from "valibot";
 import Table from "cli-table3";
+import writeFileAtomic from "write-file-atomic";
+import lockfile from "proper-lockfile";
 /*  classification taxonomy  */
 export const projectClassification = {
     boxing: ["white", "grey", "black"]
@@ -207,8 +209,9 @@ export class Config {
     findUpward(start, stop, rel) {
         let dir = fs.realpathSync(start);
         const end = fs.realpathSync(stop);
-        const between = path.relative(end, dir);
-        const steps = between === "" ? 0 : between.split(path.sep).length;
+        const steps = dir.split(path.sep).length - end.split(path.sep).length;
+        if (steps < 0)
+            return null;
         for (let i = 0; i <= steps; i++) {
             const candidate = path.join(dir, rel);
             if (fs.existsSync(candidate))
@@ -280,6 +283,23 @@ export class Config {
             this.validateDoc(docs[i].doc, docs[i].filename, perDocMode);
         }
     }
+    /*  acquire a cross-process advisory lock on the target scope's file,
+        execute the callback, then release the lock  */
+    lock(cb) {
+        const td = this.docs[this.target];
+        if (td.scope.kind === "default")
+            throw new Error("internal error: \"default\" scope is not lockable");
+        fs.mkdirSync(path.dirname(td.filename), { recursive: true });
+        if (!fs.existsSync(td.filename))
+            fs.writeFileSync(td.filename, "", "utf8");
+        const release = lockfile.lockSync(td.filename);
+        try {
+            cb();
+        }
+        finally {
+            release();
+        }
+    }
     /*  write in-memory configuration back to the target scope's file  */
     write() {
         const td = this.docs[this.target];
@@ -287,7 +307,7 @@ export class Config {
             throw new Error("internal error: \"default\" scope is not writable");
         this.validateDoc(td.doc, td.filename, "strict");
         fs.mkdirSync(path.dirname(td.filename), { recursive: true });
-        fs.writeFileSync(td.filename, td.doc.toString({ indent: 4 }), "utf8");
+        writeFileAtomic.sync(td.filename, td.doc.toString({ indent: 4 }), { encoding: "utf8" });
     }
     /*  validate a single YAML document against the optional schema  */
     validateDoc(doc, filename, mode = "strict") {
@@ -314,9 +334,9 @@ export class Config {
                     progressed = true;
                 }
                 else
-                    /*  root-level issue is structurally unrecoverable: do not wipe
-                        the document, let the next strict validate() surface it  */
-                    return;
+                    /*  root-level issue cannot be deleted; skip it and process
+                        remaining issues so progressed is tracked correctly  */
+                    continue;
             }
             if (!progressed)
                 return;
@@ -509,14 +529,16 @@ export default class ConfigCommand {
             if (preset === undefined)
                 throw new Error(`unknown preset "${type}" (expected: default|vibe|pro|industry)`);
             const cfg = new Config("config", configSchema, this.log, scope);
-            cfg.read();
-            const targetKind = scope[scope.length - 1].kind;
-            for (const [k, val] of Object.entries(preset)) {
-                if (!cfg.isWritableOn(k, targetKind))
-                    continue;
-                cfg.set(k, val);
-            }
-            cfg.write();
+            cfg.lock(() => {
+                cfg.read();
+                const targetKind = scope[scope.length - 1].kind;
+                for (const [k, val] of Object.entries(preset)) {
+                    if (!cfg.isWritableOn(k, targetKind))
+                        continue;
+                    cfg.set(k, val);
+                }
+                cfg.write();
+            });
         });
         /*  register CLI sub-command "ase config list"  */
         configCmd
@@ -594,9 +616,11 @@ export default class ConfigCommand {
             .action((key, value, _opts, cmd) => {
             const scope = parseScope(cmd.optsWithGlobals().scope);
             const cfg = new Config("config", configSchema, this.log, scope);
-            cfg.read();
-            cfg.set(key, value);
-            cfg.write();
+            cfg.lock(() => {
+                cfg.read();
+                cfg.set(key, value);
+                cfg.write();
+            });
         });
     }
 }

package/dst/ase-foo.js

@@ -0,0 +1,21 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
+*/
+/*  command-line handling  */
+export default class FooCommand {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    /*  register commands  */
+    register(program) {
+        program
+            .command("foo")
+            .description("Print a nice Hello World message")
+            .action(() => {
+            process.stdout.write("Hello, World!\n");
+        });
+    }
+}

package/dst/ase-hook.js

@@ -7,6 +7,7 @@ import path from "node:path";
 import fs from "node:fs";
 import os from "node:os";
 import { execaSync } from "execa";
+import { quote } from "shell-quote";
 import Version from "./ase-version.js";
 import { Config, configSchema, parseScope } from "./ase-config.js";
 const toolSpecs = {
@@ -95,23 +96,16 @@ export default class HookCommand {
         /*  establish config context (session-scoped only if a valid sessionId is present)  */
         const hasSession = /^[A-Za-z0-9._-]+$/.test(sessionId);
         const cfg = new Config("config", configSchema, this.log, hasSession ? parseScope(`session:${sessionId}`) : parseScope(undefined));
-        try {
+        cfg.lock(() => {
             cfg.read();
-        }
-        catch (_e) {
-            /*  best-effort: ignore failures  */
-        }
+        });
         /*  determine task id (only persist when scoped to a real session)  */
         const taskId = process.env.ASE_TASK_ID ?? "default";
-        if (hasSession) {
-            try {
+        if (hasSession)
+            cfg.lock(() => {
                 cfg.set("agent.task", taskId);
                 cfg.write();
-            }
-            catch (_e) {
-                /*  best-effort: ignore failures  */
-            }
-        }
+            });
         /*  determine project id  */
         const cwd = input.cwd ?? process.cwd();
         let projectDir = cwd;
@@ -139,12 +133,12 @@ export default class HookCommand {
             (Claude Code only -- Copilot CLI has no equivalent mechanism)  */
         const envFile = tool === "claude" ? (process.env.CLAUDE_ENV_FILE ?? "") : "";
         if (envFile !== "") {
-            const script = `export ASE_VERSION="${versionCurrentPlugin}"\n` +
-                `export ASE_USER_ID="${userId}"\n` +
-                `export ASE_PROJECT_ID="${projectId}"\n` +
-                `export ASE_TASK_ID="${taskId}"\n` +
-                `export ASE_SESSION_ID="${sessionId}"\n` +
-                `export ASE_HEADLESS="${headless}"\n`;
+            const script = `export ASE_VERSION=${quote([versionCurrentPlugin])}\n` +
+                `export ASE_USER_ID=${quote([userId])}\n` +
+                `export ASE_PROJECT_ID=${quote([projectId])}\n` +
+                `export ASE_TASK_ID=${quote([taskId])}\n` +
+                `export ASE_SESSION_ID=${quote([sessionId])}\n` +
+                `export ASE_HEADLESS=${quote([headless])}\n`;
             fs.appendFileSync(envFile, script, "utf8");
         }
         /*  prepend ASE information to constitution markdown  */

package/dst/ase-kv.js

@@ -0,0 +1,136 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
+*/
+import { z } from "zod";
+/*  reusable functionality: in-memory key/value store living inside the
+    "ase service" process; per-project (one service per project) and
+    not persisted; intended for sharing information between skills
+    across multiple Claude Code instances connected to the same service  */
+export class KV {
+    /*  the actual in-memory store  */
+    static store = new Map();
+    /*  maximum allowed key length, to keep memory bounded  */
+    static KEY_MAX_LEN = 1024;
+    /*  validate the key to keep it non-empty and bounded in length  */
+    static validateKey(key) {
+        if (typeof key !== "string" || key.length === 0)
+            throw new Error("kv: key must be a non-empty string");
+        if (key.length > KV.KEY_MAX_LEN)
+            throw new Error(`kv: key must be no longer than ${KV.KEY_MAX_LEN} characters`);
+    }
+    /*  test whether a value is stored under the given key  */
+    static has(key) {
+        KV.validateKey(key);
+        return KV.store.has(key);
+    }
+    /*  get a value by key; returns undefined if no value is stored  */
+    static get(key) {
+        KV.validateKey(key);
+        return KV.store.get(key);
+    }
+    /*  set a value under the given key; overwrites any existing value  */
+    static set(key, val) {
+        KV.validateKey(key);
+        KV.store.set(key, val);
+    }
+    /*  delete a value by key; returns true if a value existed  */
+    static delete(key) {
+        KV.validateKey(key);
+        return KV.store.delete(key);
+    }
+    /*  clear all keys; returns the number of keys removed  */
+    static clear() {
+        const n = KV.store.size;
+        KV.store.clear();
+        return n;
+    }
+}
+/*  MCP registration entry point for in-memory key/value tools  */
+export class KVMCP {
+    register(mcp) {
+        /*  key/value get  */
+        mcp.registerTool("kv_get", {
+            title: "ASE key/value get",
+            description: "Get a value from the in-memory key/value store by `key`. " +
+                "Returns the value as JSON-encoded `text`; returns an empty string if no value is stored.",
+            inputSchema: {
+                key: z.string()
+                    .describe("key identifier (non-empty string, up to 1024 characters)")
+            }
+        }, async (args) => {
+            try {
+                if (!KV.has(args.key))
+                    return { content: [{ type: "text", text: "" }] };
+                const val = KV.get(args.key);
+                const text = JSON.stringify(val);
+                return { content: [{ type: "text", text }] };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return { isError: true, content: [{ type: "text", text: `kv_get: ERROR: ${message}` }] };
+            }
+        });
+        /*  key/value set  */
+        mcp.registerTool("kv_set", {
+            title: "ASE key/value set",
+            description: "Store a `val` under the given `key` in the in-memory key/value store. " +
+                "Overwrites any existing value for the same `key`. " +
+                "The value can be any JSON-compatible type (string, number, boolean, null, array, object).",
+            inputSchema: {
+                key: z.string()
+                    .describe("key identifier (non-empty string, up to 1024 characters)"),
+                val: z.any()
+                    .describe("arbitrary JSON-compatible value to store under `key`")
+            }
+        }, async (args) => {
+            try {
+                KV.set(args.key, args.val);
+                return { content: [{ type: "text", text: `kv_set: OK: stored key "${args.key}"` }] };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return { isError: true, content: [{ type: "text", text: `kv_set: ERROR: ${message}` }] };
+            }
+        });
+        /*  key/value clear  */
+        mcp.registerTool("kv_clear", {
+            title: "ASE key/value clear",
+            description: "Remove all keys from the in-memory key/value store. " +
+                "Returns a status `text` indicating how many keys were removed.",
+            inputSchema: {}
+        }, async () => {
+            try {
+                const n = KV.clear();
+                return { content: [{ type: "text", text: `kv_clear: OK: removed ${n} key(s)` }] };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return { isError: true, content: [{ type: "text", text: `kv_clear: ERROR: ${message}` }] };
+            }
+        });
+        /*  key/value delete  */
+        mcp.registerTool("kv_delete", {
+            title: "ASE key/value delete",
+            description: "Delete a value from the in-memory key/value store by `key`. " +
+                "Returns a status `text` indicating whether a value existed and was removed.",
+            inputSchema: {
+                key: z.string()
+                    .describe("key identifier (non-empty string, up to 1024 characters)")
+            }
+        }, async (args) => {
+            try {
+                const removed = KV.delete(args.key);
+                const msg = removed ?
+                    `kv_delete: OK: removed key "${args.key}"` :
+                    `kv_delete: WARNING: no key "${args.key}" to remove`;
+                return { content: [{ type: "text", text: msg }] };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return { isError: true, content: [{ type: "text", text: `kv_delete: ERROR: ${message}` }] };
+            }
+        });
+    }
+}

package/dst/ase-mcp.js

@@ -68,10 +68,12 @@ export default class MCPCommand {
                 return;
             bridgeDone = true;
             closedByUs = true;
-            await Promise.allSettled([
-                server.close(),
-                client?.close()
+            const timeout = new Promise((resolve) => setTimeout(resolve, 3000));
+            await Promise.race([
+                Promise.allSettled([server.close(), client?.close()]),
+                timeout
             ]);
+            process.exit(0);
         };
         /*  (re-)connect the HTTP client to the service  */
         const connectClient = async () => {
@@ -97,11 +99,13 @@ export default class MCPCommand {
             await next.start();
         };
         /*  reconnect loop: restart service if needed, then reconnect client  */
-        const reconnect = async (attempt = 0) => {
+        const reconnect = async (attempt = 0, done) => {
             const delay = Math.min(500 * 2 ** attempt, 10000);
             await new Promise((resolve) => setTimeout(resolve, delay));
-            if (bridgeDone)
+            if (bridgeDone) {
+                done?.();
                 return;
+            }
             try {
                 const ctx = await this.ensureService();
                 port = ctx.port;
@@ -110,11 +114,12 @@ export default class MCPCommand {
                 closedByUs = false;
                 await connectClient();
                 this.log.write("info", "mcp: reconnected to service");
+                done?.();
             }
             catch (_err) {
                 const err = _err instanceof Error ? _err : new Error(String(_err));
                 this.log.write("error", `mcp: reconnect failed: ${err.message}`);
-                reconnect(attempt + 1).catch(() => { });
+                reconnect(attempt + 1, done).catch(() => { });
             }
         };
         /*  wire stdio server  */
@@ -145,7 +150,7 @@ export default class MCPCommand {
                 if (match !== true) {
                     reconnecting = true;
                     this.log.write("warning", "mcp: health check failed — reconnecting");
-                    reconnect().catch(() => { }).finally(() => { reconnecting = false; });
+                    reconnect(0, () => { reconnecting = false; }).catch(() => { });
                 }
             }
             catch { /* ignore probe errors */ }

package/dst/ase-persona.js

@@ -29,9 +29,11 @@ export class Persona {
             parseScope(`session:${session}`) :
             parseScope(undefined);
         const cfg = new Config("config", configSchema, log, scope);
-        cfg.read();
-        cfg.set("agent.persona", style);
-        cfg.write();
+        cfg.lock(() => {
+            cfg.read();
+            cfg.set("agent.persona", style);
+            cfg.write();
+        });
     }
 }
 /*  MCP registration entry point for persona tools  */
@@ -47,7 +49,7 @@ export default class PersonaMCP {
                 "If `style` is provided, it sets the persona style, " +
                 "otherwise it returns the current persona `style`. " +
                 "If `session` is provided, the operation is scoped to that session, " +
-                "otherwise it operates on the broadest scope (user/project cascade). " +
+                "otherwise it operates on the strongest/closest scope (user/project cascade). " +
                 "Allowed styles: \"writer\" (decorative, eloquent, explaining), " +
                 "\"engineer\" (brief, factual, accurate), " +
                 "\"telegrapher\" (very brief, factual, abbreviating), " +

package/dst/ase-service.js

@@ -15,12 +15,12 @@ import prettyMs from "pretty-ms";
 import * as v from "valibot";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { z } from "zod";
-import { DateTime } from "luxon";
 import { Config, configSchema } from "./ase-config.js";
 import { DiagramMCP } from "./ase-diagram.js";
 import { TaskMCP } from "./ase-task.js";
+import { KVMCP } from "./ase-kv.js";
 import PersonaMCP from "./ase-persona.js";
+import { TimestampMCP } from "./ase-timestamp.js";
 import pkg from "../package.json" with { type: "json" };
 /*  shared service host  */
 export const SERVICE_HOST = "127.0.0.1";
@@ -87,20 +87,26 @@ export class Service {
     }
     /*  persist an allocated port into ".ase/service.yaml"  */
     static persistPort(svc, port) {
-        svc.set("port", port);
-        svc.write();
+        svc.lock(() => {
+            svc.read();
+            svc.set("port", port);
+            svc.write();
+        });
     }
     /*  clear the persisted port and remove ".ase/service.yaml" if it is empty  */
     static clearPort(svc) {
-        svc.delete("port");
-        const root = svc.get();
-        const empty = root === undefined || root === null || (isMap(root) && root.items.length === 0);
-        if (empty) {
-            if (fs.existsSync(svc.filename))
-                fs.rmSync(svc.filename);
-        }
-        else
-            svc.write();
+        svc.lock(() => {
+            svc.read();
+            svc.delete("port");
+            const root = svc.get();
+            const empty = root === undefined || root === null || (isMap(root) && root.items.length === 0);
+            if (empty) {
+                if (fs.existsSync(svc.filename))
+                    fs.rmSync(svc.filename);
+            }
+            else
+                svc.write();
+        });
     }
     /*  spawn the current executable detached as a background service  */
     static spawnDetached(aseDir, port) {
@@ -171,30 +177,6 @@ export class ServiceMCP {
                 content: [{ type: "text", text: JSON.stringify(status) }]
             };
         });
-        mcp.registerTool("timestamp", {
-            title: "ASE timestamp",
-            description: "Return the current local date/time formatted via a Luxon format string. " +
-                "Pass the Luxon format tokens as `format` (default: `yyyy-LL-dd HH:mm`). " +
-                "Returns the formatted timestamp as `text`.",
-            inputSchema: {
-                format: z.string().default("yyyy-LL-dd HH:mm")
-                    .describe("Luxon format tokens (default: `yyyy-LL-dd HH:mm`)")
-            }
-        }, async (args) => {
-            try {
-                const text = DateTime.now().toFormat(args.format);
-                return {
-                    content: [{ type: "text", text }]
-                };
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                return {
-                    isError: true,
-                    content: [{ type: "text", text: `timestamp: format failed: ${message}` }]
-                };
-            }
-        });
     }
 }
 /*  CLI command "ase service"  */
@@ -233,8 +215,15 @@ export default class ServiceCommand {
         /*  track start time and last activity  */
         const startTime = Date.now();
         let lastActivity = Date.now();
+        let inFlight = 0;
         let stopping = false;
         server.ext("onRequest", (_request, h) => {
+            inFlight++;
+            lastActivity = Date.now();
+            return h.continue;
+        });
+        server.ext("onPreResponse", (_request, h) => {
+            inFlight = Math.max(0, inFlight - 1);
             lastActivity = Date.now();
             return h.continue;
         });
@@ -244,7 +233,9 @@ export default class ServiceCommand {
             new ServiceMCP({ projectId: ctx.projectId, port: ctx.port, startTime }).register(mcp);
             new DiagramMCP().register(mcp);
             new TaskMCP(this.log).register(mcp);
+            new KVMCP().register(mcp);
             new PersonaMCP(this.log).register(mcp);
+            new TimestampMCP().register(mcp);
             return mcp;
         };
         /*  listen to HTTP/REST endpoints  */
@@ -359,6 +350,8 @@ export default class ServiceCommand {
         setInterval(async () => {
             if (stopping)
                 return;
+            if (inFlight > 0)
+                return;
             if (Date.now() - lastActivity > IDLE_MS) {
                 stopping = true;
                 this.log.write("info", "service: idle timeout reached, stopping");
@@ -394,7 +387,7 @@ export default class ServiceCommand {
             }
         }
         /*  bounded retry across the bind/start TOCTOU window: on each attempt
-            re-allocate, re-persist, re-spawn; early-break on foreign listener  */
+            re-allocate, re-spawn; early-break on foreign listener  */
         let lastErr = new Error("service failed to start within timeout");
         for (let attempt = 0; attempt < 3; attempt++) {
             port = await Service.allocatePort();
@@ -449,12 +442,17 @@ export default class ServiceCommand {
                     ]);
                     if (!exited) {
                         child.kill("SIGKILL");
-                        await exitPromise;
+                        await Promise.race([
+                            exitPromise,
+                            new Promise((resolve) => setTimeout(resolve, 2000))
+                        ]);
+                        child.unref();
                     }
                 }
+                if (!success)
+                    Service.clearPort(ctx.svc);
             }
         }
-        Service.clearPort(ctx.svc);
         throw lastErr;
     }
     /*  status flow: report whether the service is running  */

package/dst/ase-task.js

@@ -131,9 +131,11 @@ export class Task {
     static setId(log, session, id) {
         const scope = parseScope(`session:${session}`);
         const cfg = new Config("config", configSchema, log, scope);
-        cfg.read();
-        cfg.set("agent.task", id);
-        cfg.write();
+        cfg.lock(() => {
+            cfg.read();
+            cfg.set("agent.task", id);
+            cfg.write();
+        });
     }
 }
 /*  read all of stdin as a UTF-8 string  */

package/dst/ase-timestamp.js

@@ -0,0 +1,36 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
+*/
+import { z } from "zod";
+import { DateTime } from "luxon";
+/*  MCP registration entry point for timestamp tool  */
+export class TimestampMCP {
+    register(mcp) {
+        mcp.registerTool("timestamp", {
+            title: "ASE timestamp",
+            description: "Return the current local date/time formatted via a Luxon format string. " +
+                "Pass the Luxon format tokens as `format` (default: `yyyy-LL-dd HH:mm`). " +
+                "Returns the formatted timestamp as `text`.",
+            inputSchema: {
+                format: z.string().default("yyyy-LL-dd HH:mm")
+                    .describe("Luxon format tokens (default: `yyyy-LL-dd HH:mm`)")
+            }
+        }, async (args) => {
+            try {
+                const text = DateTime.now().toFormat(args.format);
+                return {
+                    content: [{ type: "text", text }]
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `timestamp: format failed: ${message}` }]
+                };
+            }
+        });
+    }
+}

package/package.json

@@ -6,7 +6,7 @@
     "homepage":                             "http://github.com/rse/ase",
     "repository":                           { "url": "git+https://github.com/rse/ase.git", "type": "git" },
     "bugs":                                 { "url": "http://github.com/rse/ase/issues" },
-    "version":                              "0.0.28",
+    "version":                              "0.0.29",
     "license":                              "GPL-3.0-only",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",
@@ -33,7 +33,10 @@
         "@types/node":                      "25.8.0",
         "@types/luxon":                     "3.7.1",
         "@types/which":                     "3.0.4",
-        "@types/update-notifier":           "6.0.8"
+        "@types/update-notifier":           "6.0.8",
+        "@types/shell-quote":               "1.7.5",
+        "@types/proper-lockfile":           "4.1.4",
+        "@types/write-file-atomic":         "4.0.3"
     },
     "dependencies": {
         "commander":                        "14.0.3",
@@ -51,7 +54,10 @@
         "@modelcontextprotocol/sdk":        "1.29.0",
         "zod":                              "4.4.3",
         "which":                            "7.0.0",
-        "update-notifier":                  "7.3.1"
+        "update-notifier":                  "7.3.1",
+        "shell-quote":                      "1.8.3",
+        "proper-lockfile":                  "4.1.2",
+        "write-file-atomic":                "4.0.0"
     },
     "engines": {
         "npm":                              ">=10.0.0",