@rse/ase 0.0.27 → 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-diagram.js

@@ -6,6 +6,7 @@
 import fs from "node:fs";
 import { InvalidArgumentError } from "commander";
 import { renderMermaidASCII } from "beautiful-mermaid";
+import { z } from "zod";
 /*  custom argument parser for Commander: non-negative integer  */
 const parseInteger = (name) => (value) => {
     const n = Number.parseInt(value, 10);
@@ -19,57 +20,6 @@ const parseColorMode = (name) => (value) => {
         throw new InvalidArgumentError(`${name} must be "none", "ansi16", or "ansi256"`);
     return value;
 };
-/*  detect terminal column width  */
-export const detectTermWidth = () => {
-    let width = 0;
-    /*  attempt 1: query environment variable  */
-    if (process.env.ASE_TERM_WIDTH !== undefined) {
-        const cols = Number.parseInt(process.env.ASE_TERM_WIDTH, 10);
-        if (Number.isFinite(cols) && cols > 0)
-            width = cols;
-    }
-    /*  attempt 2: query stdout  */
-    if (width === 0 && process.stdout.isTTY) {
-        const cols = process.stdout.columns;
-        if (typeof cols === "number" && cols > 0)
-            width = cols;
-    }
-    return width;
-};
-/*  detect terminal row height  */
-export const detectTermHeight = () => {
-    let height = 0;
-    /*  attempt 1: query environment variable  */
-    if (process.env.ASE_TERM_HEIGHT !== undefined) {
-        const rows = Number.parseInt(process.env.ASE_TERM_HEIGHT, 10);
-        if (Number.isFinite(rows) && rows > 0)
-            height = rows;
-    }
-    /*  attempt 2: query stdout  */
-    if (height === 0 && process.stdout.isTTY) {
-        const rows = process.stdout.rows;
-        if (typeof rows === "number" && rows > 0)
-            height = rows;
-    }
-    return height;
-};
-/*  detect terminal color capability  */
-const detectColorMode = () => {
-    let mode = "none";
-    /*  attempt 1: query environment variable (explicitly)  */
-    if (process.env.ASE_TERM_COLORS !== undefined)
-        if (process.env.ASE_TERM_COLORS.match(/^(?:none|ansi16|ansi256)$/) !== null)
-            mode = process.env.ASE_TERM_COLORS;
-    /*  attempt 2: query stdout  */
-    if (mode === "none" && process.stdout.isTTY) {
-        const depth = process.stdout.getColorDepth();
-        if (depth >= 8)
-            mode = "ansi256";
-        else if (depth >= 4)
-            mode = "ansi16";
-    }
-    return mode;
-};
 /*  truncate a single rendered line to a maximum visible column,
     preserving ANSI escape sequences (CSI ...m) and appending an ANSI
     reset sequence if any styling was active at the truncation point  */
@@ -135,70 +85,124 @@ const visibleWidth = (line) => {
     }
     return visible;
 };
-/*  pure rendering helper: turn a Mermaid source string plus options into
-    a rendered Unicode/ASCII diagram string. Throws on render failure.  */
-export const renderDiagram = (src, opts) => {
-    /*  create diagram rendering  */
-    let out = renderMermaidASCII(src, {
-        useAscii: opts.ascii,
-        paddingX: opts.nodeMarginX,
-        paddingY: opts.nodeMarginY,
-        boxBorderPadding: opts.nodePadding,
-        colorMode: opts.colorMode,
-        theme: opts.colorMode !== "none" ? {
-            fg: "#000000",
-            border: "#a0a0a0",
-            junction: "#a0a0a0",
-            arrow: "#404040",
-            line: "#707070",
-            corner: "#707070"
-        } : {
-            fg: "#000000",
-            border: "#000000",
-            junction: "#000000",
-            arrow: "#000000",
-            line: "#000000",
-            corner: "#000000"
+/*  reusable functionality: Mermaid diagram rendering as Unicode/ASCII art  */
+export class Diagram {
+    /*  detect terminal column width  */
+    static detectTermWidth() {
+        let width = 0;
+        /*  attempt 1: query environment variable  */
+        if (process.env.ASE_TERM_WIDTH !== undefined) {
+            const cols = Number.parseInt(process.env.ASE_TERM_WIDTH, 10);
+            if (Number.isFinite(cols) && cols > 0)
+                width = cols;
         }
-    });
-    /*  optionally clip diagram rendering  */
-    const termWidth = opts.terminalWidth;
-    const termHeight = opts.terminalHeight;
-    if (termWidth > 0 || termHeight > 0) {
-        const maxWidth = termWidth > 0 ? termWidth - opts.diagramClipX : 0;
-        const maxHeight = termHeight > 0 ? termHeight - opts.diagramClipY : 0;
-        const trailingNL = out.endsWith("\n");
-        let lines = (trailingNL ? out.slice(0, -1) : out).split("\n");
-        let widthWarn = "";
-        let heightWarn = "";
-        if (maxWidth > 0) {
-            const widest = lines.reduce((m, l) => Math.max(m, visibleWidth(l)), 0);
-            if (widest > maxWidth)
-                widthWarn =
-                    `ase diagram: WARNING: rendered diagram width ${widest} exceeds budget ${maxWidth}; ` +
-                        "rightmost content was clipped. Please regenerate the Mermaid source to fit " +
-                        `within ${maxWidth} chars by preferring a portrait orientation ` +
-                        "(\"flowchart TB\", top-to-bottom) over landscape (\"LR\"/\"RL\"/\"BT\"), " +
-                        "reducing siblings per row, abbreviating node labels, or restructuring " +
-                        "into nested subgraph hierarchies.";
-            lines = lines.map((l) => truncateAnsiLine(l, maxWidth));
+        /*  attempt 2: query stdout  */
+        if (width === 0 && process.stdout.isTTY) {
+            const cols = process.stdout.columns;
+            if (typeof cols === "number" && cols > 0)
+                width = cols;
         }
-        if (maxHeight > 0 && lines.length > maxHeight) {
-            const overflow = lines.length - maxHeight;
-            heightWarn =
-                `ase diagram: WARNING: rendered diagram height ${lines.length} exceeds budget ${maxHeight}; ` +
-                    `bottom ${overflow} line(s) were clipped. Please regenerate the Mermaid source to fit ` +
-                    `within ${maxHeight} lines by reducing depth or splitting into multiple diagrams.`;
-            lines = lines.slice(0, maxHeight);
+        return width;
+    }
+    /*  detect terminal row height  */
+    static detectTermHeight() {
+        let height = 0;
+        /*  attempt 1: query environment variable  */
+        if (process.env.ASE_TERM_HEIGHT !== undefined) {
+            const rows = Number.parseInt(process.env.ASE_TERM_HEIGHT, 10);
+            if (Number.isFinite(rows) && rows > 0)
+                height = rows;
+        }
+        /*  attempt 2: query stdout  */
+        if (height === 0 && process.stdout.isTTY) {
+            const rows = process.stdout.rows;
+            if (typeof rows === "number" && rows > 0)
+                height = rows;
         }
-        out = lines.join("\n") + (trailingNL ? "\n" : "");
-        if (widthWarn !== "")
-            out += "\n" + widthWarn + "\n";
-        if (heightWarn !== "")
-            out += "\n" + heightWarn + "\n";
+        return height;
     }
-    return out;
-};
+    /*  detect terminal color capability  */
+    static detectColorMode() {
+        let mode = "none";
+        /*  attempt 1: query environment variable (explicitly)  */
+        if (process.env.ASE_TERM_COLORS !== undefined)
+            if (process.env.ASE_TERM_COLORS.match(/^(?:none|ansi16|ansi256)$/) !== null)
+                mode = process.env.ASE_TERM_COLORS;
+        /*  attempt 2: query stdout  */
+        if (mode === "none" && process.stdout.isTTY) {
+            const depth = process.stdout.getColorDepth();
+            if (depth >= 8)
+                mode = "ansi256";
+            else if (depth >= 4)
+                mode = "ansi16";
+        }
+        return mode;
+    }
+    /*  pure rendering helper: turn a Mermaid source string plus options into
+        a rendered Unicode/ASCII diagram string. Throws on render failure.  */
+    static render(src, opts) {
+        /*  create diagram rendering  */
+        let out = renderMermaidASCII(src, {
+            useAscii: opts.ascii,
+            paddingX: opts.nodeMarginX,
+            paddingY: opts.nodeMarginY,
+            boxBorderPadding: opts.nodePadding,
+            colorMode: opts.colorMode,
+            theme: opts.colorMode !== "none" ? {
+                fg: "#000000",
+                border: "#a0a0a0",
+                junction: "#a0a0a0",
+                arrow: "#404040",
+                line: "#707070",
+                corner: "#707070"
+            } : {
+                fg: "#000000",
+                border: "#000000",
+                junction: "#000000",
+                arrow: "#000000",
+                line: "#000000",
+                corner: "#000000"
+            }
+        });
+        /*  optionally clip diagram rendering  */
+        const termWidth = opts.terminalWidth;
+        const termHeight = opts.terminalHeight;
+        if (termWidth > 0 || termHeight > 0) {
+            const maxWidth = termWidth > 0 ? termWidth - opts.diagramClipX : 0;
+            const maxHeight = termHeight > 0 ? termHeight - opts.diagramClipY : 0;
+            const trailingNL = out.endsWith("\n");
+            let lines = (trailingNL ? out.slice(0, -1) : out).split("\n");
+            let widthWarn = "";
+            let heightWarn = "";
+            if (maxWidth > 0) {
+                const widest = lines.reduce((m, l) => Math.max(m, visibleWidth(l)), 0);
+                if (widest > maxWidth)
+                    widthWarn =
+                        `ase diagram: WARNING: rendered diagram width ${widest} exceeds budget ${maxWidth}; ` +
+                            "rightmost content was clipped. Please regenerate the Mermaid source to fit " +
+                            `within ${maxWidth} chars by preferring a portrait orientation ` +
+                            "(\"flowchart TB\", top-to-bottom) over landscape (\"LR\"/\"RL\"/\"BT\"), " +
+                            "reducing siblings per row, abbreviating node labels, or restructuring " +
+                            "into nested subgraph hierarchies.";
+                lines = lines.map((l) => truncateAnsiLine(l, maxWidth));
+            }
+            if (maxHeight > 0 && lines.length > maxHeight) {
+                const overflow = lines.length - maxHeight;
+                heightWarn =
+                    `ase diagram: WARNING: rendered diagram height ${lines.length} exceeds budget ${maxHeight}; ` +
+                        `bottom ${overflow} line(s) were clipped. Please regenerate the Mermaid source to fit ` +
+                        `within ${maxHeight} lines by reducing depth or splitting into multiple diagrams.`;
+                lines = lines.slice(0, maxHeight);
+            }
+            out = lines.join("\n") + (trailingNL ? "\n" : "");
+            if (widthWarn !== "")
+                out += "\n" + widthWarn + "\n";
+            if (heightWarn !== "")
+                out += "\n" + heightWarn + "\n";
+        }
+        return out;
+    }
+}
 /*  read stdin into a single string  */
 const readStdin = async () => {
     const chunks = [];
@@ -219,14 +223,14 @@ export default class DiagramCommand {
             .description("Render Mermaid diagram specification as Unicode/ASCII art")
             .option("-i, --input <file>", "read Mermaid source from file instead of stdin")
             .option("-a, --ascii", "emit plain ASCII (+-|) instead of Unicode box-drawing", false)
-            .option("-c, --color-mode <mode>", "force color mode (\"none\", \"ansi16\", or \"ansi256\")", parseColorMode("--color-mode"), detectColorMode())
+            .option("-c, --color-mode <mode>", "force color mode (\"none\", \"ansi16\", or \"ansi256\")", parseColorMode("--color-mode"), Diagram.detectColorMode())
             .option("--node-margin-x <n>", "horizontal margin between nodes of <n> characters", parseInteger("--node-margin-x"), 3)
             .option("--node-margin-y <n>", "vertical margin between nodes of <n> lines", parseInteger("--node-margin-y"), 3)
             .option("--node-padding <n>", "horizontal and vertical inner node padding with <n> characters", parseInteger("--node-padding"), 1)
             .option("--diagram-clip-x <n>", "extra horizontal clipping of diagram to terminal width minus <n> characters", parseInteger("--diagram-clip-x"), 0)
             .option("--diagram-clip-y <n>", "extra vertical clipping of diagram to terminal height minus <n> lines", parseInteger("--diagram-clip-y"), 0)
-            .option("--terminal-width <n>", "width of terminal of <n> characters (for diagram clipping)", parseInteger("--terminal-width"), detectTermWidth())
-            .option("--terminal-height <n>", "height of terminal of <n> lines (for diagram clipping)", parseInteger("--terminal-height"), detectTermHeight())
+            .option("--terminal-width <n>", "width of terminal of <n> characters (for diagram clipping)", parseInteger("--terminal-width"), Diagram.detectTermWidth())
+            .option("--terminal-height <n>", "height of terminal of <n> lines (for diagram clipping)", parseInteger("--terminal-height"), Diagram.detectTermHeight())
             .action(async (opts) => {
             /*  fetch Mermaid diagram specification from stdin  */
             let src;
@@ -241,7 +245,7 @@ export default class DiagramCommand {
             /*  create diagram rendering  */
             let out;
             try {
-                out = renderDiagram(src, {
+                out = Diagram.render(src, {
                     ascii: opts.ascii ?? false,
                     colorMode: opts.colorMode,
                     nodeMarginX: opts.nodeMarginX,
@@ -265,3 +269,68 @@ export default class DiagramCommand {
         });
     }
 }
+/*  MCP registration entry point for diagram tools  */
+export class DiagramMCP {
+    register(mcp) {
+        mcp.registerTool("diagram", {
+            title: "ASE diagram render",
+            description: "Render a Mermaid diagram as Unicode/ASCII art. " +
+                "Use for visualizing " +
+                "structure/layout/components/dependencies as a Flowchart, " +
+                "control-flow/branching/concurrency as a Flowchart, " +
+                "state-machine/states/transitions as an UML State Diagram, " +
+                "data-flow/actors/messages/protocols as an UML Sequence Diagram, " +
+                "data-structure/classes/methods as an UML Class Diagram, " +
+                "data-model/entities/relationships as an ER Diagram, or " +
+                "metrics/distributions/time-series as an XY-Chart. " +
+                "Pass the Mermaid diagram specification as `diagram`. " +
+                "Returns the rendered art as `text`.",
+            inputSchema: {
+                diagram: z.string()
+                    .describe("Mermaid diagram specification"),
+                ascii: z.boolean().default(false)
+                    .describe("emit plain ASCII (+-|) instead of Unicode box-drawing characters"),
+                colorMode: z.enum(["none", "ansi16", "ansi256"]).default("none")
+                    .describe("color mode for ANSI escape sequences in the rendered output"),
+                nodeMarginX: z.number().int().min(0).default(3)
+                    .describe("horizontal margin between nodes, in characters"),
+                nodeMarginY: z.number().int().min(0).default(3)
+                    .describe("vertical margin between nodes, in lines"),
+                nodePadding: z.number().int().min(0).default(1)
+                    .describe("inner horizontal and vertical padding within each node, in characters"),
+                diagramClipX: z.number().int().min(0).default(0)
+                    .describe("extra horizontal clipping: subtract this many characters from `terminalWidth`"),
+                diagramClipY: z.number().int().min(0).default(0)
+                    .describe("extra vertical clipping: subtract this many lines from `terminalHeight`"),
+                terminalWidth: z.number().int().min(0).default(Diagram.detectTermWidth())
+                    .describe("terminal width in characters; 0 disables horizontal clipping; defaults to ASE_TERM_WIDTH env var if set"),
+                terminalHeight: z.number().int().min(0).default(Diagram.detectTermHeight())
+                    .describe("terminal height in lines; 0 disables vertical clipping; defaults to ASE_TERM_HEIGHT env var if set")
+            }
+        }, async (args) => {
+            try {
+                const out = Diagram.render(args.diagram, {
+                    ascii: args.ascii,
+                    colorMode: args.colorMode,
+                    nodeMarginX: args.nodeMarginX,
+                    nodeMarginY: args.nodeMarginY,
+                    nodePadding: args.nodePadding,
+                    diagramClipX: args.diagramClipX,
+                    diagramClipY: args.diagramClipY,
+                    terminalWidth: args.terminalWidth,
+                    terminalHeight: args.terminalHeight
+                });
+                return {
+                    content: [{ type: "text", text: out }]
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `diagram: render failed: ${message}` }]
+                };
+            }
+        });
+    }
+}

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

@@ -5,7 +5,9 @@
 */
 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 = {
@@ -94,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;
@@ -138,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  */
@@ -173,6 +168,26 @@ export default class HookCommand {
         process.stdout.write(JSON.stringify(payload));
         return 0;
     }
+    /*  handler for "ase hook session-end" (both tools)  */
+    doSessionEnd(_tool) {
+        /*  read session information (Claude Code uses snake_case fields,
+            Copilot CLI uses camelCase fields)  */
+        const stdin = fs.readFileSync(0, "utf8");
+        const input = stdin.trim() !== "" ? JSON.parse(stdin) : {};
+        /*  determine session id  */
+        const sessionId = input.session_id ?? input.sessionId ?? "";
+        /*  remove the session directory ~/.ase/session/<id> (only for a valid sessionId)  */
+        if (/^[A-Za-z0-9._-]+$/.test(sessionId)) {
+            const dir = path.join(os.homedir(), ".ase", "session", sessionId);
+            try {
+                fs.rmSync(dir, { recursive: true, force: true });
+            }
+            catch (_e) {
+                /*  best-effort: ignore failures  */
+            }
+        }
+        return 0;
+    }
     /*  handler for "ase hook pre-tool-use" (both tools)  */
     doPreToolUse(tool) {
         const spec = toolSpecs[tool];
@@ -254,6 +269,14 @@ export default class HookCommand {
             .action(async (opts) => {
             process.exit(await this.doSessionStart(this.parseTool(opts.tool)));
         });
+        /*  register CLI sub-command "ase hook session-end"  */
+        hookCmd
+            .command("session-end")
+            .description("handle SessionEnd hook event")
+            .option("-t, --tool <tool>", "target tool (\"claude\" or \"copilot\")", toolDflt)
+            .action((opts) => {
+            process.exit(this.doSessionEnd(this.parseTool(opts.tool)));
+        });
         /*  register CLI sub-command "ase hook pre-tool-use"  */
         hookCmd
             .command("pre-tool-use")