@rse/ase 0.9.43 → 0.9.45

package/dst/ase-service.js

@@ -67,6 +67,23 @@ const TICK_MS = 60 * 1000;
 const PORT_MIN = 42000;
 const PORT_MAX = 44000;
 const PORT_TRIES = 20;
+/*  load the optional "config.yaml" and "service.yaml" files and derive
+    the service identity context (project id, port, service config)  */
+export const loadServiceContext = (log) => {
+    /*  load files  */
+    const cfg = new Config("config", configSchema, log);
+    cfg.read();
+    const svc = new Config("service", serviceSchema, log);
+    svc.read();
+    /*  determine project id  */
+    const projectId = cfg.get("project.id") ?? path.basename(process.cwd());
+    /*  determine service port  */
+    const port = svc.get("port") ?? null;
+    /*  determine path to ".ase" directory  */
+    const aseDir = path.dirname(svc.filename);
+    /*  return context information  */
+    return { projectId, port, svc, aseDir };
+};
 /*  reusable functionality: port allocation, persistence, and process spawning  */
 export class Service {
     /*  try binding a single candidate port to verify availability  */
@@ -135,21 +152,23 @@ export class Service {
             fd = fs.openSync(logFile, "r");
             const size = fs.fstatSync(fd).size;
             const CHUNK = 8192;
-            const buf = Buffer.alloc(CHUNK);
+            const chunks = [];
             let pos = size;
-            let tail = "";
             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);
-                const chunk = buf.toString("utf8", 0, n);
-                tail = chunk + tail;
-                for (let i = 0; i < chunk.length; i++)
-                    if (chunk.charCodeAt(i) === 10)
+                chunks.unshift(buf);
+                for (let i = 0; i < n; i++)
+                    if (buf[i] === 10)
                         count++;
             }
-            const all = tail.split("\n").filter((l) => l.length > 0);
+            /*  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 {
@@ -193,26 +212,7 @@ export default class ServiceCommand {
     }
     /*  load optional ".ase/config.yaml" and ".ase/service.yaml" files  */
     loadContext() {
-        /*  load files  */
-        const cfg = new Config("config", configSchema, this.log);
-        cfg.read();
-        const svc = new Config("service", serviceSchema, this.log);
-        svc.read();
-        /*  determine project id  */
-        const rawId = cfg.get("project.id");
-        const projectId = rawId ?? path.basename(process.cwd());
-        /*  determine service port  */
-        const rawPort = svc.get("port");
-        const port = rawPort ?? null;
-        /*  determine path to ".ase" directory  */
-        const aseDir = path.dirname(svc.filename);
-        /*  return context information  */
-        return {
-            projectId,
-            port,
-            svc,
-            aseDir
-        };
+        return loadServiceContext(this.log);
     }
     /*  service-side: bind HAPI server until "/stop" command is received or idle timeout happens  */
     async runService(ctx) {
@@ -433,7 +433,7 @@ export default class ServiceCommand {
                     await new Promise((resolve) => setTimeout(resolve, 100));
                     if (exited)
                         break;
-                    const s = await probe(port, ctx.projectId);
+                    const s = await probe(port, ctx.projectId).catch(() => null);
                     if (s === true) {
                         this.log.write("info", `service: started on port ${port}`);
                         child.unref();

package/dst/ase-setup.js

@@ -104,7 +104,7 @@ export default class SetupCommand {
     /*  run a sub-process, suppressing output on success and emitting it on failure  */
     async run(cmd, args, opts = {}) {
         const { cwd, quiet = false, retries = 1, ignoreError } = opts;
-        const argsLog = args.map((arg) => arg.replace(/(_KEY=)(\S+)/, (_, k, v) => k + "*".repeat(v.length)));
+        const argsLog = args.map((arg) => arg.replace(/(\w*key=)([^\s&]+)/gi, (_, k, v) => k + "*".repeat(v.length)));
         this.log.write("info", `setup: $ ${cmd} ${argsLog.join(" ")}` +
             (cwd !== undefined ? ` (cwd: ${cwd})` : ""));
         for (let i = 0; i < retries; i++) {
@@ -182,7 +182,7 @@ export default class SetupCommand {
         /*  best-effort stop of background service  */
         this.log.write("info", `setup: update${dev ? "[dev]" : ""}: ` +
             "stopping potentially running ASE service");
-        await this.run("ase", ["service", "stop"], { quiet: true });
+        await this.run("ase", ["service", "stop"], { quiet: true, ignoreError: "ASE service not running" });
         if (dev) {
             /*  update ASE CLI Tool  */
             this.log.write("info", `setup: update[dev]: used ASE version: ${Version.current()}`);
@@ -226,33 +226,20 @@ export default class SetupCommand {
         }
         return 0;
     }
-    /*  handler for "ase setup enable" (both tools)  */
-    async doEnable(tool, scope) {
+    /*  handler for "ase setup enable|disable" (both tools)  */
+    async doToggle(tool, scope, action) {
         this.requireClaudeScope(tool, scope);
         const spec = toolSpecs[tool];
         await this.ensureTool(spec.cli);
-        this.log.write("info", `setup: enable: enabling ASE ${spec.label} plugin`);
+        this.log.write("info", `setup: ${action}: ${action === "enable" ? "enabling" : "disabling"} ` +
+            `ASE ${spec.label} plugin`);
         /*  the GitHub Copilot CLI and OpenAI Codex CLI have no "plugin
-            enable" subcommand, so (re-)install the plugin instead  */
+            enable"/"plugin disable" subcommand, so (re-)install or
+            uninstall the plugin instead  */
         const scopeArgs = scope !== "user" ? ["--scope", scope] : [];
         const args = tool === "claude" ?
-            ["plugin", "enable", "ase@ase", ...scopeArgs] :
-            ["plugin", spec.pInstall, "ase@ase"];
-        await this.run(spec.cli, args, { retries: tool === "claude" ? 1 : 3 });
-        return 0;
-    }
-    /*  handler for "ase setup disable" (both tools)  */
-    async doDisable(tool, scope) {
-        this.requireClaudeScope(tool, scope);
-        const spec = toolSpecs[tool];
-        await this.ensureTool(spec.cli);
-        this.log.write("info", `setup: disable: disabling ASE ${spec.label} plugin`);
-        /*  the GitHub Copilot CLI and OpenAI Codex CLI have no "plugin
-            disable" subcommand, so uninstall the plugin instead  */
-        const scopeArgs = scope !== "user" ? ["--scope", scope] : [];
-        const args = tool === "claude" ?
-            ["plugin", "disable", "ase@ase", ...scopeArgs] :
-            ["plugin", spec.pRemove, "ase@ase"];
+            ["plugin", action, "ase@ase", ...scopeArgs] :
+            ["plugin", action === "enable" ? spec.pInstall : spec.pRemove, "ase@ase"];
         await this.run(spec.cli, args, { retries: tool === "claude" ? 1 : 3 });
         return 0;
     }
@@ -266,7 +253,7 @@ export default class SetupCommand {
         /*  best-effort stop of background service  */
         this.log.write("info", `setup: uninstall${dev ? "[dev]" : ""}: ` +
             "stopping potentially running ASE service");
-        await this.run("ase", ["service", "stop"], { quiet: true });
+        await this.run("ase", ["service", "stop"], { quiet: true, ignoreError: "ASE service not running" });
         /*  uninstall ASE plugin  */
         this.log.write("info", `setup: uninstall${dev ? "[dev]" : ""}: ` +
             `uninstalling ASE ${spec.label} plugin (origin: ${dev ? "local" : "remote/bundled"})`);
@@ -466,6 +453,29 @@ export default class SetupCommand {
                 await this.mcpRemove(tool, spec.server, scope);
         };
     }
+    /*  build a chat-model MCP handler which bridges to a locally
+        installed AI agent harness CLI via the mcp-to-harness stdio
+        scaffold; the API key environment variable carries no key at all,
+        but instead the harness model identifier, with the special value
+        "default" selecting the default model of the harness  */
+    harnessMcpHandler(harness) {
+        return async (spec, tool, scope, action, _envKey, envVal) => {
+            if (action === "activate")
+                await this.mcpAdd(tool, spec.server, {}, {
+                    type: "stdio", command: [
+                        "npx", "-y", "mcp-to-harness",
+                        "--service", spec.name,
+                        "--mcp-tool", "query",
+                        "--harness", harness,
+                        ...(envVal !== "default" ? [
+                            "--harness-model", envVal
+                        ] : [])
+                    ]
+                }, scope);
+            else
+                await this.mcpRemove(tool, spec.server, scope);
+        };
+    }
     /*  registry of pre-defined MCP servers: maps each server id onto its
         dedicated handler which performs the activate/deactivate operation  */
     mcpServers = [
@@ -523,6 +533,33 @@ export default class SetupCommand {
             skills: ["ase-meta-chat", "ase-meta-quorum"],
             handler: this.chatMcpHandler({ url: "https://api.z.ai/api/paas/v4/", api: "completion", model: "glm-5.1" }, { model: "z-ai/glm-5.1" })
         },
+        {
+            id: "anthropic-claude",
+            name: "Anthropic Claude",
+            version: "latest",
+            env: ["ANTHROPIC_CLAUDE"],
+            server: "chat-anthropic-claude",
+            skills: ["ase-meta-chat", "ase-meta-quorum"],
+            handler: this.harnessMcpHandler("claude")
+        },
+        {
+            id: "openai-codex",
+            name: "OpenAI Codex",
+            version: "latest",
+            env: ["OPENAI_CODEX"],
+            server: "chat-openai-codex",
+            skills: ["ase-meta-chat", "ase-meta-quorum"],
+            handler: this.harnessMcpHandler("codex")
+        },
+        {
+            id: "github-copilot",
+            name: "GitHub Copilot",
+            version: "latest",
+            env: ["GITHUB_COPILOT"],
+            server: "chat-github-copilot",
+            skills: ["ase-meta-chat", "ase-meta-quorum"],
+            handler: this.harnessMcpHandler("copilot")
+        },
         {
             id: "brave",
             name: "Brave",
@@ -565,7 +602,7 @@ export default class SetupCommand {
             skills: ["ase-meta-search", "ase-meta-evaluate", "ase-arch-discover"],
             handler: async (spec, tool, scope, action, _envKey, envVal) => {
                 if (action === "activate")
-                    await this.mcpAdd(tool, spec.server, {}, { type: "http", url: `https://mcp.exa.ai/mcp?exaApiKey=${envVal}` }, scope);
+                    await this.mcpAdd(tool, spec.server, {}, { type: "http", url: `https://mcp.exa.ai/mcp?exaApiKey=${encodeURIComponent(envVal)}` }, scope);
                 else
                     await this.mcpRemove(tool, spec.server, scope);
             }
@@ -699,7 +736,7 @@ export default class SetupCommand {
     async statuslineWriteAst(file, root) {
         await mkdirp(path.dirname(file));
         const text = JsonAsty.unparse(root);
-        writeFileAtomic.sync(file, text, { encoding: "utf8" });
+        await writeFileAtomic(file, text, { encoding: "utf8" });
     }
     /*  handler for "ase setup statusline activate"  */
     async doStatuslineActivate(tool, scope, opts, format) {
@@ -863,7 +900,7 @@ export default class SetupCommand {
             .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
             .option("-s, --scope <scope>", "target scope (\"user\", \"project\", or \"local\")", "user")
             .action(async (opts) => {
-            process.exit(await this.doEnable(this.parseTool(opts.tool), this.parseScope(opts.scope)));
+            process.exit(await this.doToggle(this.parseTool(opts.tool), this.parseScope(opts.scope), "enable"));
         });
         /*  register CLI sub-command "ase setup disable"  */
         setupCmd
@@ -872,7 +909,7 @@ export default class SetupCommand {
             .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
             .option("-s, --scope <scope>", "target scope (\"user\", \"project\", or \"local\")", "user")
             .action(async (opts) => {
-            process.exit(await this.doDisable(this.parseTool(opts.tool), this.parseScope(opts.scope)));
+            process.exit(await this.doToggle(this.parseTool(opts.tool), this.parseScope(opts.scope), "disable"));
         });
         /*  register CLI sub-command "ase setup mcp"  */
         const mcpCmd = setupCmd

package/dst/ase-skills.js

@@ -16,7 +16,7 @@ export class Skills {
     static httpActive = 0;
     static httpQueue = [];
     static async httpLimit(fn) {
-        if (Skills.httpActive >= Skills.HTTP_CONCURRENCY)
+        while (Skills.httpActive >= Skills.HTTP_CONCURRENCY)
             await new Promise((resolve) => Skills.httpQueue.push(resolve));
         Skills.httpActive++;
         try {
@@ -295,7 +295,7 @@ export class Skills {
             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.  */
-        const lifespan = (!Number.isNaN(cMs) && !Number.isNaN(uMs)) ? Math.max(0, uMs - cMs) : 1;
+        const lifespan = (!Number.isNaN(cMs) && !Number.isNaN(uMs)) ? Math.max(1, uMs - cMs) : 1;
         const recentness = !Number.isNaN(uMs) ? Math.exp(-Math.max(0, (now - uMs) / msPerDay) / halfLife) : 0.5;
         let rank = d * s * lifespan * recentness;
         /*  hard, caller-tunable staleness penalty on top of the soft

package/dst/ase-statusline.js

@@ -11,6 +11,7 @@ import { InvalidArgumentError } from "commander";
 import { execaSync } from "execa";
 import { Chalk } from "chalk";
 import { Config, configSchema, parseScope } from "./ase-config.js";
+import { writeStdout } from "./ase-stdout.js";
 import pkg from "../package.json" with { type: "json" };
 /*  forced-color chalk instance: stdout is a pipe under Anthropic Claude Code CLI,
     so chalk auto-detection would yield level 0; force level 1 to keep
@@ -58,18 +59,22 @@ const detectTermWidth = () => {
     }
     return width;
 };
-/*  format a token count as a compact human-readable string (e.g. 334k, 104.9M)  */
-const formatTokens = (n) => {
+/*  format a count as a compact human-readable string with the given scaling base  */
+const formatScaled = (n, base) => {
     if (!Number.isFinite(n) || n < 0)
         return "0";
-    if (n >= 1_000_000_000)
-        return `${(n / 1_000_000_000).toFixed(1)}G`;
-    if (n >= 1_000_000)
-        return `${(n / 1_000_000).toFixed(1)}M`;
-    if (n >= 1_000)
-        return `${(n / 1_000).toFixed(1)}k`;
+    if (n >= base ** 3)
+        return `${(n / base ** 3).toFixed(1)}G`;
+    if (n >= base ** 2)
+        return `${(n / base ** 2).toFixed(1)}M`;
+    if (n >= base)
+        return `${(n / base).toFixed(1)}k`;
     return `${n}`;
 };
+/*  format a token count as a compact human-readable string (e.g. 334k, 104.9M)  */
+const formatTokens = (n) => formatScaled(n, 1000);
+/*  format a byte count as a compact human-readable string (e.g. 33.2G, 512M)  */
+const formatBytes = (n) => formatScaled(n, 1024);
 /*  format a millisecond duration as a compact human-readable string (e.g. 6d 12hr 7m, 4hr 27m, 12m 30s)  */
 const formatDurationMs = (ms) => {
     if (!Number.isFinite(ms) || ms < 0)
@@ -122,33 +127,18 @@ const formatCostUsd = (n) => {
         return "$0.00";
     return `$${n.toFixed(2)}`;
 };
-/*  format a byte count as a compact human-readable string (e.g. 33.2G, 512M)  */
-const formatBytes = (n) => {
-    if (!Number.isFinite(n) || n < 0)
-        return "0";
-    if (n >= 1024 ** 3)
-        return `${(n / 1024 ** 3).toFixed(1)}G`;
-    if (n >= 1024 ** 2)
-        return `${(n / 1024 ** 2).toFixed(1)}M`;
-    if (n >= 1024)
-        return `${(n / 1024).toFixed(1)}k`;
-    return `${n}`;
-};
 /*  probe local git status for the given working directory  */
 const probeGit = (cwd) => {
+    const gitCmd = (...args) => execFileSync("git", ["-C", cwd, ...args], { stdio: ["ignore", "pipe", "ignore"], timeout: 1000 }).toString("utf8");
     try {
-        const branch = execFileSync("git", ["-C", cwd, "rev-parse", "--abbrev-ref", "HEAD"], { stdio: ["ignore", "pipe", "ignore"], timeout: 1000 })
-            .toString("utf8").trim();
-        const porc = execFileSync("git", ["-C", cwd, "status", "--porcelain"], { stdio: ["ignore", "pipe", "ignore"], timeout: 1000 })
-            .toString("utf8");
+        const branch = gitCmd("rev-parse", "--abbrev-ref", "HEAD").trim();
+        const porc = gitCmd("status", "--porcelain");
         const lines = porc.split("\n").filter((l) => l.length > 0);
         const untracked = lines.filter((l) => l.startsWith("??")).length;
-        const dirty = lines.length > 0;
         let added = 0;
         let removed = 0;
         try {
-            const shortstat = execFileSync("git", ["-C", cwd, "diff", "--shortstat", "HEAD"], { stdio: ["ignore", "pipe", "ignore"], timeout: 1000 })
-                .toString("utf8");
+            const shortstat = gitCmd("diff", "--shortstat", "HEAD");
             const mAdd = shortstat.match(/(\d+)\s+insertion/);
             const mDel = shortstat.match(/(\d+)\s+deletion/);
             if (mAdd !== null)
@@ -159,10 +149,10 @@ const probeGit = (cwd) => {
         catch (_e) {
             /*  no HEAD yet or git failure; leave counts at 0  */
         }
-        return { branch, dirty, untracked, added, removed };
+        return { branch, untracked, added, removed };
     }
     catch (_e) {
-        return { branch: "", dirty: false, untracked: 0, added: 0, removed: 0 };
+        return { branch: "", untracked: 0, added: 0, removed: 0 };
     }
 };
 /*  probe local memory usage in bytes (used/total) using OS-portable helpers  */
@@ -190,9 +180,11 @@ export default class StatuslineCommand {
     }
     /*  register commands  */
     register(program) {
-        /*  default for --tool derived from ASE_TOOL environment variable  */
+        /*  default for --tool derived from ASE_TOOL environment variable
+            (validated lazily by "parseTool" in the action, so an invalid
+            value cannot break unrelated "ase" commands at startup)  */
         const envTool = process.env.ASE_TOOL ?? "";
-        const toolDflt = envTool !== "" ? this.parseTool(envTool) : "claude";
+        const toolDflt = envTool !== "" ? envTool : "claude";
         program
             .command("statusline")
             .description("Render Anthropic Claude Code CLI or GitHub Copilot CLI statusline from stdin JSON")
@@ -339,7 +331,7 @@ export default class StatuslineCommand {
                     emit(`${prefix("⚒", "effort")}${c.bold(effort)}`);
                 },
                 t: () => {
-                    const thinking = (data.thinking?.enabled ?? false) === true ? "yes" : "no";
+                    const thinking = data.thinking?.enabled === true ? "yes" : "no";
                     emit(`${prefix("⚛", "thinking")}${c.bold(thinking)}`);
                 },
                 /*  ==== OUTPUT ====  */
@@ -355,7 +347,7 @@ export default class StatuslineCommand {
                 },
                 /*  ==== CONTEXT ====  */
                 c: () => {
-                    const pct = Math.floor(data.context_window?.used_percentage ?? 0);
+                    const pct = Math.min(100, Math.max(0, Math.floor(data.context_window?.used_percentage ?? 0)));
                     const barSize = 20;
                     const filled = Math.round(pct / 100 * barSize);
                     const bar = "█".repeat(filled) + "░".repeat(barSize - filled);
@@ -485,7 +477,7 @@ export default class StatuslineCommand {
                 col = 0;
             }
             /*  send output  */
-            process.stdout.write(out);
+            await writeStdout(out);
             /*  optionally publish task id to the calling tmux pane as a per-pane user
                 option, so something (like claudeX) can pick it up via #{@ase_task_id}  */
             if (process.env.TMUX !== undefined

package/dst/ase-task.js

@@ -10,6 +10,7 @@ import { DateTime } from "luxon";
 import picomatch from "picomatch";
 import { isScalar } from "yaml";
 import { z } from "zod";
+import { LRUCache } from "lru-cache";
 import { Config, configSchema, parseScope } from "./ase-config.js";
 import { Markdown } from "./ase-markdown.js";
 import { writeStdout } from "./ase-stdout.js";
@@ -24,19 +25,36 @@ export class Task {
         if (!/^[A-Za-z0-9_-]+$/.test(id))
             throw new Error("task: id must match [A-Za-z0-9_-]+");
     }
+    /*  validate the session id to keep it safe as a config scope term  */
+    static validateSession(session) {
+        if (typeof session !== "string" || session.length === 0)
+            throw new Error("task: session must be a non-empty string");
+        if (!/^[A-Za-z0-9_-]+$/.test(session))
+            throw new Error("task: session must match [A-Za-z0-9_-]+");
+    }
+    /*  cached project root determination (TTL-bounded, as the ASE
+        service is long-running and the Git context can change)  */
+    static projectRootCache = new LRUCache({ max: 4, ttl: 10 * 1000 });
     /*  determine the project root (Git top-level if inside a Git
-        working tree, otherwise the current working directory)  */
+        working tree, otherwise the current working directory);
+        cached, as each determination spawns a Git subprocess  */
     static projectRoot() {
+        const cwd = process.cwd();
+        const cached = Task.projectRootCache.get(cwd);
+        if (cached !== undefined)
+            return cached;
+        let root = cwd;
         try {
             const result = execaSync("git", ["rev-parse", "--show-toplevel"], { stderr: "ignore" });
             const top = result.stdout.trim();
             if (top !== "")
-                return top;
+                root = top;
         }
         catch {
             /*  not inside a Git working tree  */
         }
-        return process.cwd();
+        Task.projectRootCache.set(cwd, root);
+        return root;
     }
     /*  read the configured "basedir" anchor and "files" miniglob spec for
         task storage; "basedir" is project-root-relative (POSIX, defaults
@@ -166,10 +184,9 @@ export class Task {
         fs.rmSync(oldFile, { force: true });
         return true;
     }
-    /*  list all persisted tasks in lexicographic id order; if verbose is true,
-        each entry's `mtime` is set to the task file's modification time
-        formatted as "YYYY-MM-DD HH:MM", otherwise it is left undefined  */
-    static list(log, verbose = false) {
+    /*  scan the task base directory (after eager migration) for
+        "TASK-<id>.md" files matching the configured "files" miniglob  */
+    static scan(log) {
         if (Task.needsMigration(log))
             Task.migrateAll(log);
         const { basedir, files } = Task.spec(log);
@@ -186,41 +203,37 @@ export class Task {
             const st = fs.statSync(file);
             if (!st.isFile())
                 continue;
-            const mtime = verbose ? DateTime.fromJSDate(st.mtime).toFormat("yyyy-LL-dd HH:mm") : undefined;
-            out.push({ id: m[1], mtime });
+            out.push({ id: m[1], file, st });
         }
+        return out;
+    }
+    /*  list all persisted tasks in lexicographic id order; if verbose is true,
+        each entry's `mtime` is set to the task file's modification time
+        formatted as "YYYY-MM-DD HH:MM", otherwise it is left undefined  */
+    static list(log, verbose = false) {
+        const out = Task.scan(log).map((entry) => ({
+            id: entry.id,
+            mtime: verbose ? DateTime.fromJSDate(entry.st.mtime).toFormat("yyyy-LL-dd HH:mm") : undefined
+        }));
         out.sort((a, b) => a.id.localeCompare(b.id));
         return out;
     }
     /*  purge tasks whose modification time is older than the given cutoff in
         milliseconds; returns the list of removed task ids  */
     static purge(log, maxAgeMs) {
-        if (Task.needsMigration(log))
-            Task.migrateAll(log);
-        const { basedir, files } = Task.spec(log);
-        const dir = path.join(Task.projectRoot(), basedir);
-        if (!fs.existsSync(dir))
-            return [];
-        const isMatch = picomatch(files, { dot: true });
         const cutoff = Date.now() - maxAgeMs;
         const removed = [];
-        for (const entry of fs.readdirSync(dir)) {
-            const m = /^TASK-([A-Za-z0-9_-]+)\.md$/.exec(entry);
-            if (m === null || !isMatch(entry))
-                continue;
-            const file = path.join(dir, entry);
-            const st = fs.statSync(file);
-            if (!st.isFile())
-                continue;
-            if (st.mtimeMs < cutoff) {
-                fs.rmSync(file, { force: true });
-                removed.push(m[1]);
+        for (const entry of Task.scan(log)) {
+            if (entry.st.mtimeMs < cutoff) {
+                fs.rmSync(entry.file, { force: true });
+                removed.push(entry.id);
             }
         }
         return removed;
     }
     /*  get the active task id for a given session, or empty string if none  */
     static getId(log, session) {
+        Task.validateSession(session);
         const scope = parseScope(`session:${session}`);
         const cfg = new Config("config", configSchema, log, scope);
         cfg.read();
@@ -231,6 +244,7 @@ export class Task {
     }
     /*  set the active task id for a given session  */
     static setId(log, session, id) {
+        Task.validateSession(session);
         const scope = parseScope(`session:${session}`);
         const cfg = new Config("config", configSchema, log, scope);
         cfg.lock(() => {
@@ -357,10 +371,8 @@ export default class TaskCommand {
             const day = 24 * hour;
             const month = 30 * day;
             const year = 365 * day;
-            const factor = unit === "h" ? hour :
-                unit === "d" ? day :
-                    unit === "m" ? month :
-                        year;
+            const factors = { h: hour, d: day, m: month, y: year };
+            const factor = factors[unit];
             const removed = Task.purge(this.log, n * factor);
             if (removed.length === 0)
                 this.log.write("info", "task: no tasks to purge");
@@ -371,6 +383,14 @@ export default class TaskCommand {
         });
     }
 }
+/*  render a caught error as an MCP tool error result  */
+const mcpError = (err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+        isError: true,
+        content: [{ type: "text", text: `ERROR: ${message}` }]
+    };
+};
 /*  MCP registration entry point for task tools  */
 export class TaskMCP {
     log;
@@ -412,11 +432,7 @@ export class TaskMCP {
                 };
             }
             catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                return {
-                    isError: true,
-                    content: [{ type: "text", text: `ERROR: ${message}` }]
-                };
+                return mcpError(err);
             }
         });
         /*  task load  */
@@ -437,11 +453,7 @@ export class TaskMCP {
                 };
             }
             catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                return {
-                    isError: true,
-                    content: [{ type: "text", text: `ERROR: ${message}` }]
-                };
+                return mcpError(err);
             }
         });
         /*  task save  */
@@ -463,11 +475,7 @@ export class TaskMCP {
                 };
             }
             catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                return {
-                    isError: true,
-                    content: [{ type: "text", text: `ERROR: ${message}` }]
-                };
+                return mcpError(err);
             }
         });
         /*  task delete  */
@@ -490,18 +498,15 @@ export class TaskMCP {
                 };
             }
             catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                return {
-                    isError: true,
-                    content: [{ type: "text", text: `ERROR: ${message}` }]
-                };
+                return mcpError(err);
             }
         });
         /*  task rename  */
         mcp.registerTool("ase_task_rename", {
             title: "ASE task rename",
-            description: "Rename a previously persisted task from `old` to `new` by atomically moving the " +
-                "task `TASK-<id>.md` file. Returns a status `text` indicating whether the rename succeeded. " +
+            description: "Rename a previously persisted task from `old` to `new` by moving the " +
+                "task `TASK-<id>.md` file and rewriting its embedded task heading. " +
+                "Returns a status `text` indicating whether the rename succeeded. " +
                 "Fails with an error if the target id already exists.",
             inputSchema: {
                 old: z.string()
@@ -520,11 +525,7 @@ export class TaskMCP {
                 };
             }
             catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                return {
-                    isError: true,
-                    content: [{ type: "text", text: `ERROR: ${message}` }]
-                };
+                return mcpError(err);
             }
         });
         /*  task id get/set  */
@@ -556,11 +557,7 @@ export class TaskMCP {
                 };
             }
             catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                return {
-                    isError: true,
-                    content: [{ type: "text", text: `ERROR: ${message}` }]
-                };
+                return mcpError(err);
             }
         });
     }

package/dst/ase-version.js

@@ -11,7 +11,8 @@ export default class Version {
     static current() {
         return pkg.version;
     }
-    /*  return latest ASE version available on the NPM registry  */
+    /*  return latest ASE version known from the NPM registry
+        (cached background check, falling back to the current version)  */
     static async latest() {
         const notifier = updateNotifier({
             pkg,