@rse/ase 0.9.8 → 0.9.9

package/dst/ase-getopt.js

@@ -56,6 +56,7 @@ export class GetoptMCP {
                 const tokens = args.spec.split(/\s+/).filter((e) => e.length > 0);
                 const re = /^--([A-Za-z][A-Za-z0-9-]*)(?:\|-([A-Za-z]))?(?:=(\((.*)\)(\.\.\.)?|.*))?$/;
                 const internals = new Set();
+                const flagTakesValue = new Map();
                 for (const tok of tokens) {
                     const m = re.exec(tok);
                     if (m === null)
@@ -69,6 +70,9 @@ export class GetoptMCP {
                     const choices = choicePart !== null ? choicePart.split("|") : null;
                     const isList = listMarker !== null;
                     const dflt = choices !== null ? choices[0] : valuePart;
+                    flagTakesValue.set(`--${long}`, takesValue);
+                    if (short !== null)
+                        flagTakesValue.set(`-${short}`, takesValue);
                     const head = short !== null ? `-${short}, --${long}` : `--${long}`;
                     const flags = takesValue ? `${head} <value>` : head;
                     const opt = new Option(flags);
@@ -143,11 +147,63 @@ export class GetoptMCP {
                         }
                         ranges.push({ start, end: i });
                     }
-                    const consumed = argsVec.length - cmd.args.length;
-                    if (cmd.args.length > 0 && consumed >= 0 && consumed < ranges.length) {
-                        const first = ranges[consumed].start;
-                        argsVerbatim = argsRaw.slice(first);
+                    /*  helper function: strip surrounding quotes/escapes from a raw
+                        range so it can be compared against an option flag spelling  */
+                    const unquote = (s) => {
+                        let out = "";
+                        let j = 0;
+                        while (j < s.length) {
+                            const ch = s[j];
+                            if (ch === "\"" || ch === "'") {
+                                const quote = ch;
+                                j++;
+                                while (j < s.length && s[j] !== quote) {
+                                    if (s[j] === "\\" && j + 1 < s.length) {
+                                        out += s[j + 1];
+                                        j += 2;
+                                    }
+                                    else {
+                                        out += s[j];
+                                        j++;
+                                    }
+                                }
+                                j++;
+                            }
+                            else if (ch === "\\" && j + 1 < s.length) {
+                                out += s[j + 1];
+                                j += 2;
+                            }
+                            else {
+                                out += ch;
+                                j++;
+                            }
+                        }
+                        return out;
+                    };
+                    /*  walk the raw ranges, consuming leading option tokens (and any
+                        separate value tokens they take) until the first positional
+                        is reached, then slice the original input from there -- this
+                        mirrors commander's pass-through semantics while staying on
+                        the verbatim text and is robust against value-consuming
+                        options and shell-operator characters in the input  */
+                    let idx = 0;
+                    while (idx < ranges.length) {
+                        const tok = unquote(argsRaw.slice(ranges[idx].start, ranges[idx].end));
+                        if (tok === "--") {
+                            idx++;
+                            break;
+                        }
+                        if (!tok.startsWith("-") || tok === "-")
+                            break;
+                        let consumesNext = false;
+                        if (/^--[^=]+$/.test(tok) || /^-[^-]$/.test(tok))
+                            consumesNext = flagTakesValue.get(tok) === true;
+                        idx++;
+                        if (consumesNext && idx < ranges.length)
+                            idx++;
                     }
+                    if (idx < ranges.length)
+                        argsVerbatim = argsRaw.slice(ranges[idx].start);
                 }
                 else
                     argsVerbatim = cmd.args.join(" ");

package/dst/ase-hook.js

@@ -92,7 +92,7 @@ export default class HookCommand {
         return text.replace(/@(\S+)/g, (match, ref) => {
             let resolved = ref;
             if (resolved.startsWith("~/"))
-                resolved = path.join(process.env.HOME ?? "", resolved.slice(2));
+                resolved = path.join(os.homedir(), resolved.slice(2));
             const abs = path.isAbsolute(resolved) ? resolved : path.resolve(baseDir, resolved);
             if (visited.has(abs))
                 return match;
@@ -265,24 +265,6 @@ export default class HookCommand {
     /*  handler for "ase hook stop" (both tools)  */
     doStop(_tool) {
         this.writeAgentStatus("ready");
-        /*  safety net: clear any lingering "agent.skill" marker so a
-            crashed or aborted skill loop does not leave information active  */
-        const sessionId = this.readSessionIdFromStdin();
-        if (this.isValidSessionId(sessionId)) {
-            try {
-                const cfg = new Config("config", configSchema, this.log, parseScope(`session:${sessionId}`));
-                cfg.lock(() => {
-                    cfg.read();
-                    if (typeof cfg.get("agent.skill") === "string") {
-                        cfg.delete("agent.skill");
-                        cfg.write();
-                    }
-                });
-            }
-            catch (_e) {
-                /*  best-effort: ignore failures  */
-            }
-        }
         return 0;
     }
     /*  handler for "ase hook session-end" (both tools)  */
@@ -334,6 +316,9 @@ export default class HookCommand {
             return "";
         }
     }
+    /*  the edit-capable skills whose active state lets the pre-tool-use
+        hook auto-approve subsequent "Edit" invocations  */
+    editCapableSkills = ["ase-code-lint", "ase-docs-proofread"];
     /*  handler for "ase hook pre-tool-use" (both tools)  */
     doPreToolUse(tool) {
         const spec = toolSpecs[tool];
@@ -377,9 +362,9 @@ export default class HookCommand {
         else if (toolName === "Edit") {
             const sessionId = this.pickSessionId(input);
             const activeSkill = this.readActiveSkill(sessionId);
-            if (activeSkill === "ase-docs-proofread" || activeSkill === "ase-code-lint") {
+            if (this.editCapableSkills.includes(activeSkill)) {
                 approve = true;
-                reason = `${activeSkill}: user already consented via AskUserQuestion`;
+                reason = `${activeSkill}: edit auto-approved for active edit-capable skill`;
             }
         }
         /*  emit permission decision (or stay silent to defer to default flow).

package/dst/ase-markdown.js

@@ -65,8 +65,8 @@ export class Markdown {
     /*  apply the inline-span and bullet-marker rewriting passes to a chunk of
         non-fenced Markdown text (see prepare() for fenced-block handling)  */
     static rewrite(text) {
-        /*  PASS 1: rewrite single-backtick inline code spans that carry
-            backslash-escaped backticks (`\``) into CommonMark-correct spans.  */
+        /*  PASS 1: rewrite inline code spans that carry backslash-escaped
+            backticks (`\``) into CommonMark-correct spans.  */
         {
             let pre = "";
             let j = 0;
@@ -79,10 +79,19 @@ export class Markdown {
                     j++;
                     continue;
                 }
-                /*  scan an opening single-backtick span, capturing its raw
-                    inner content up to the matching unescaped close backtick  */
+                /*  measure the full opening backtick run: a code-span
+                    delimiter is a *run* of backticks and a span opened by a
+                    run of N backticks is closed only by a run of exactly N
+                    backticks, so the opening-run length determines what we
+                    scan for as the closing delimiter  */
+                let open = 0;
+                while (j + open < text.length && text[j + open] === "`")
+                    open++;
+                /*  scan the opening backtick-run span, capturing its raw
+                    inner content up to the matching unescaped closing run of
+                    exactly `open` backticks  */
                 let inner = "";
-                let k = j + 1;
+                let k = j + open;
                 let closed = false;
                 let escaped = false;
                 while (k < text.length) {
@@ -94,17 +103,29 @@ export class Markdown {
                         continue;
                     }
                     if (c === "`") {
-                        closed = true;
-                        break;
+                        /*  measure this backtick run and treat it as the
+                            closing delimiter only if it matches the opening
+                            run length exactly; a shorter or longer run is
+                            literal content of the span  */
+                        let runLen = 0;
+                        while (k + runLen < text.length && text[k + runLen] === "`")
+                            runLen++;
+                        if (runLen === open) {
+                            closed = true;
+                            break;
+                        }
+                        inner += "`".repeat(runLen);
+                        k += runLen;
+                        continue;
                     }
                     inner += c;
                     k++;
                 }
                 if (!closed || !escaped) {
-                    /*  not an escaped-backtick span: emit the opening backtick
+                    /*  not an escaped-backtick span: emit the opening run
                         verbatim and continue scanning from just after it  */
-                    pre += "`";
-                    j++;
+                    pre += "`".repeat(open);
+                    j += open;
                     continue;
                 }
                 /*  un-escape inner `\`` into literal backticks, then choose a
@@ -124,7 +145,7 @@ export class Markdown {
                 const fence = "`".repeat(maxRun + 1);
                 const pad = (content.startsWith("`") || content.endsWith("`")) ? " " : "";
                 pre += `${fence}${pad}${content}${pad}${fence}`;
-                j = k + 1;
+                j = k + open;
             }
             text = pre;
         }

package/dst/ase-mcp.js

@@ -62,15 +62,21 @@ export default class MCPCommand {
         const server = new StdioServerTransport();
         /*  track active client and bridge-level closed state  */
         let client = null;
-        let closedByUs = false; /*  set when we initiated the client close  */
         let bridgeDone = false; /*  set when stdio side closes              */
         let reconnecting = false; /*  set while a reconnect chain is active   */
+        /*  mark the individual transports we intentionally closed, so their
+            onclose is not mistaken for an unexpected connection loss; using
+            a per-transport set (instead of a single bridge-wide flag) avoids
+            suppressing a legitimate retry when a freshly-created connection
+            fails during the brief window right after we initiated a close  */
+        const closedByUs = new WeakSet();
         /*  cleanly shut down the whole bridge  */
         const shutdown = async () => {
             if (bridgeDone)
                 return;
             bridgeDone = true;
-            closedByUs = true;
+            if (client !== null)
+                closedByUs.add(client);
             const timeout = new Promise((resolve) => setTimeout(resolve, 3000));
             await Promise.race([
                 Promise.allSettled([server.close(), client?.close()]),
@@ -92,7 +98,7 @@ export default class MCPCommand {
             };
             /*  service closed the connection — try to recover  */
             next.onclose = () => {
-                if (client !== next || closedByUs || bridgeDone || reconnecting)
+                if (client !== next || closedByUs.has(next) || bridgeDone || reconnecting)
                     return;
                 triggerReconnect("http connection lost");
             };
@@ -110,15 +116,17 @@ export default class MCPCommand {
             try {
                 const ctx = await this.ensureService();
                 port = ctx.port;
-                closedByUs = true;
-                await client?.close();
+                const stale = client;
+                client = null;
+                if (stale !== null) {
+                    closedByUs.add(stale);
+                    await stale.close();
+                }
                 await connectClient();
-                closedByUs = false;
                 reconnecting = false;
                 this.log.write("info", "mcp: reconnected to service");
             }
             catch (err) {
-                closedByUs = false;
                 this.log.write("error", `mcp: reconnect failed: ${this.asError(err).message}`);
                 reconnect(attempt + 1).catch(() => { });
             }
@@ -143,7 +151,13 @@ export default class MCPCommand {
         };
         /*  start server and initial client  */
         await server.start();
-        await connectClient();
+        try {
+            await connectClient();
+        }
+        catch (err) {
+            /*  service vanished between probe and connect — recover instead of crashing  */
+            triggerReconnect(`initial connect failed: ${this.asError(err).message}`);
+        }
         /*  periodically probe the service; trigger reconnect if it is gone  */
         const HEALTH_INTERVAL_MS = 30_000;
         const healthTimer = setInterval(async () => {

package/dst/ase-notify.js

@@ -0,0 +1,32 @@
+/*
+**  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";
+/*  MCP registration entry point for user notification tool  */
+export class NotifyMCP {
+    register(mcp) {
+        mcp.registerTool("ase_notify", {
+            title: "ASE user notification",
+            description: "Display a `message` to the user in the terminal of the agent harness. " +
+                "The display happens deterministically through the accompanying PostToolUse hook, " +
+                "independent of any assistant text output. " +
+                "Use this to surface intermediate skill progress or status information " +
+                "which otherwise would not be visible to the user before the final response. " +
+                "Returns a status `text` acknowledging the notification.",
+            inputSchema: {
+                message: z.string().min(1).max(4096)
+                    .describe("message to display to the user (plain text, up to 4096 characters)")
+            }
+        }, async (args) => {
+            /*  the tool itself is a deliberate no-op: the user-visible display
+                happens in the PostToolUse hook ("ase hook post-tool-use"),
+                which receives this tool call's input from the agent harness
+                and reflects the message back as a "systemMessage"  */
+            return {
+                content: [{ type: "text", text: "notify: OK: message displayed to user" }]
+            };
+        });
+    }
+}

package/dst/ase-service.js

@@ -43,7 +43,7 @@ export const isConnRefused = (err) => {
 /*  probe the service and verify ASE identity banner  */
 export const probe = async (port, projectId) => {
     try {
-        const r = await ofetch.raw(`http://${SERVICE_HOST}:${port}/`, {
+        const r = await ofetch.raw(`http://${HOST}:${port}/`, {
             method: "OPTIONS",
             signal: AbortSignal.timeout(2000),
             ignoreResponseError: true
@@ -509,12 +509,15 @@ export default class ServiceCommand {
             if (ctx.port === null)
                 throw new Error("service not running (no port configured after auto-start)");
         }
-        const match = await probe(ctx.port, ctx.projectId);
+        let match = await probe(ctx.port, ctx.projectId);
         if (match !== true) {
             await this.doStart();
             ctx = this.loadContext();
             if (ctx.port === null)
                 throw new Error("service not running (no port configured after auto-start)");
+            match = await probe(ctx.port, ctx.projectId);
+            if (match !== true)
+                throw new Error(`service not responding on port ${ctx.port} after auto-start`);
         }
         const r = await ofetch.raw(`http://${HOST}:${ctx.port}/command`, {
             method: "POST",

package/dst/ase-setup.js

@@ -107,11 +107,19 @@ export default class SetupCommand {
             try {
                 if (quiet) {
                     const result = await execa(cmd, args, { stdio: "ignore", cwd, reject: false });
-                    if (typeof result.exitCode === "number" && result.exitCode !== 0 && !final) {
-                        this.log.write("info", `setup: attempt ${i + 1}/${retries} failed for "${cmd} ${args.join(" ")}" ` +
-                            `(exit code: ${result.exitCode}): retrying...`);
-                        await new Promise((resolve) => setTimeout(resolve, 1000));
-                        continue;
+                    if (typeof result.exitCode === "number" && result.exitCode !== 0) {
+                        if (!final) {
+                            this.log.write("info", `setup: attempt ${i + 1}/${retries} failed for "${cmd} ${args.join(" ")}" ` +
+                                `(exit code: ${result.exitCode}): retrying...`);
+                            await new Promise((resolve) => setTimeout(resolve, 1000));
+                            continue;
+                        }
+                        if (ignoreError !== undefined) {
+                            this.log.write("info", `setup: ${ignoreError} (skipped)`);
+                            return;
+                        }
+                        this.log.write("error", `setup: command failed: exit code: ${result.exitCode}`);
+                        throw new Error(`command "${cmd} ${args.join(" ")}" failed (exit code: ${result.exitCode})`);
                     }
                     return;
                 }
@@ -386,6 +394,32 @@ export default class SetupCommand {
             ["mcp", "remove", name];
         await this.run(toolSpecs[tool].cli, args, { ignoreError: `MCP server "${name}" not registered` });
     }
+    /*  build a chat-model MCP handler from the per-model direct and
+        OPENROUTER url/api/model triples, factoring out the shared
+        mcp-to-openai stdio scaffold common to all chat-model servers  */
+    chatMcpHandler(direct, router) {
+        return async (spec, tool, action, envKey, envVal) => {
+            if (action === "activate")
+                await this.mcpAdd(tool, spec.server, { OPENAI_KEY: envVal }, {
+                    type: "stdio", command: [
+                        "npx", "-y", "mcp-to-openai",
+                        "--service", spec.name,
+                        "--mcp-tool", "query",
+                        ...(envKey === "OPENROUTER" ? [
+                            "--openai-url", "https://openrouter.ai/api/v1",
+                            "--openai-api", "completion",
+                            "--openai-model", router.model
+                        ] : [
+                            "--openai-url", direct.url,
+                            "--openai-api", direct.api,
+                            "--openai-model", direct.model
+                        ])
+                    ]
+                });
+            else
+                await this.mcpRemove(tool, spec.server);
+        };
+    }
     /*  registry of pre-defined MCP servers: maps each server id onto its
         dedicated handler which performs the activate/deactivate operation  */
     mcpServers = [
@@ -396,27 +430,7 @@ export default class SetupCommand {
             env: ["OPENAI_CHATGPT", "OPENROUTER"],
             server: "chat-openai-chatgpt",
             skills: ["ase-meta-chat", "ase-meta-quorum"],
-            handler: async (spec, tool, action, envKey, envVal) => {
-                if (action === "activate")
-                    await this.mcpAdd(tool, spec.server, { OPENAI_KEY: envVal }, {
-                        type: "stdio", command: [
-                            "npx", "-y", "mcp-to-openai",
-                            "--service", spec.name,
-                            "--mcp-tool", "query",
-                            ...(envKey === "OPENROUTER" ? [
-                                "--openai-url", "https://openrouter.ai/api/v1",
-                                "--openai-api", "completion",
-                                "--openai-model", "openai/gpt-5.5"
-                            ] : [
-                                "--openai-url", "https://api.openai.com/v1",
-                                "--openai-api", "responses",
-                                "--openai-model", "gpt-5.5"
-                            ])
-                        ]
-                    });
-                else
-                    await this.mcpRemove(tool, spec.server);
-            }
+            handler: this.chatMcpHandler({ url: "https://api.openai.com/v1", api: "responses", model: "gpt-5.5" }, { model: "openai/gpt-5.5" })
         },
         {
             id: "google-gemini",
@@ -425,27 +439,7 @@ export default class SetupCommand {
             env: ["GOOGLE_GEMINI", "OPENROUTER"],
             server: "chat-google-gemini",
             skills: ["ase-meta-chat", "ase-meta-quorum"],
-            handler: async (spec, tool, action, envKey, envVal) => {
-                if (action === "activate")
-                    await this.mcpAdd(tool, spec.server, { OPENAI_KEY: envVal }, {
-                        type: "stdio", command: [
-                            "npx", "-y", "mcp-to-openai",
-                            "--service", spec.name,
-                            "--mcp-tool", "query",
-                            ...(envKey === "OPENROUTER" ? [
-                                "--openai-url", "https://openrouter.ai/api/v1",
-                                "--openai-api", "completion",
-                                "--openai-model", "google/gemini-3.5-flash"
-                            ] : [
-                                "--openai-url", "https://generativelanguage.googleapis.com/v1beta/openai/",
-                                "--openai-api", "completion",
-                                "--openai-model", "gemini-3.5-flash"
-                            ])
-                        ]
-                    });
-                else
-                    await this.mcpRemove(tool, spec.server);
-            }
+            handler: this.chatMcpHandler({ url: "https://generativelanguage.googleapis.com/v1beta/openai/", api: "completion", model: "gemini-3.5-flash" }, { model: "google/gemini-3.5-flash" })
         },
         {
             id: "deepseek",
@@ -454,27 +448,7 @@ export default class SetupCommand {
             env: ["DEEPSEEK", "OPENROUTER"],
             server: "chat-deepseek",
             skills: ["ase-meta-chat", "ase-meta-quorum"],
-            handler: async (spec, tool, action, envKey, envVal) => {
-                if (action === "activate")
-                    await this.mcpAdd(tool, spec.server, { OPENAI_KEY: envVal }, {
-                        type: "stdio", command: [
-                            "npx", "-y", "mcp-to-openai",
-                            "--service", spec.name,
-                            "--mcp-tool", "query",
-                            ...(envKey === "OPENROUTER" ? [
-                                "--openai-url", "https://openrouter.ai/api/v1",
-                                "--openai-api", "completion",
-                                "--openai-model", "deepseek/deepseek-v4-flash"
-                            ] : [
-                                "--openai-url", "https://api.deepseek.com/v1",
-                                "--openai-api", "completion",
-                                "--openai-model", "deepseek-v4-flash"
-                            ])
-                        ]
-                    });
-                else
-                    await this.mcpRemove(tool, spec.server);
-            }
+            handler: this.chatMcpHandler({ url: "https://api.deepseek.com/v1", api: "completion", model: "deepseek-v4-flash" }, { model: "deepseek/deepseek-v4-flash" })
         },
         {
             id: "xai-grok",
@@ -483,27 +457,7 @@ export default class SetupCommand {
             env: ["XAI_GROK", "OPENROUTER"],
             server: "chat-xai-grok",
             skills: ["ase-meta-chat", "ase-meta-quorum"],
-            handler: async (spec, tool, action, envKey, envVal) => {
-                if (action === "activate")
-                    await this.mcpAdd(tool, spec.server, { OPENAI_KEY: envVal }, {
-                        type: "stdio", command: [
-                            "npx", "-y", "mcp-to-openai",
-                            "--service", spec.name,
-                            "--mcp-tool", "query",
-                            ...(envKey === "OPENROUTER" ? [
-                                "--openai-url", "https://openrouter.ai/api/v1",
-                                "--openai-api", "completion",
-                                "--openai-model", "x-ai/grok-4.3"
-                            ] : [
-                                "--openai-url", "https://api.x.ai/v1",
-                                "--openai-api", "completion",
-                                "--openai-model", "grok-4.3"
-                            ])
-                        ]
-                    });
-                else
-                    await this.mcpRemove(tool, spec.server);
-            }
+            handler: this.chatMcpHandler({ url: "https://api.x.ai/v1", api: "completion", model: "grok-4.3" }, { model: "x-ai/grok-4.3" })
         },
         {
             id: "alibaba-qwen",
@@ -512,27 +466,7 @@ export default class SetupCommand {
             env: ["ALIBABA_QWEN", "OPENROUTER"],
             server: "chat-alibaba-qwen",
             skills: ["ase-meta-chat", "ase-meta-quorum"],
-            handler: async (spec, tool, action, envKey, envVal) => {
-                if (action === "activate")
-                    await this.mcpAdd(tool, spec.server, { OPENAI_KEY: envVal }, {
-                        type: "stdio", command: [
-                            "npx", "-y", "mcp-to-openai",
-                            "--service", spec.name,
-                            "--mcp-tool", "query",
-                            ...(envKey === "OPENROUTER" ? [
-                                "--openai-url", "https://openrouter.ai/api/v1",
-                                "--openai-api", "completion",
-                                "--openai-model", "qwen/qwen3.7-max"
-                            ] : [
-                                "--openai-url", "https://dashscope.aliyuncs.com/compatible-mode/v1",
-                                "--openai-api", "completion",
-                                "--openai-model", "qwen3.7-max"
-                            ])
-                        ]
-                    });
-                else
-                    await this.mcpRemove(tool, spec.server);
-            }
+            handler: this.chatMcpHandler({ url: "https://dashscope.aliyuncs.com/compatible-mode/v1", api: "completion", model: "qwen3.7-max" }, { model: "qwen/qwen3.7-max" })
         },
         {
             id: "zai-glm",
@@ -541,27 +475,7 @@ export default class SetupCommand {
             env: ["ZAI_GLM", "OPENROUTER"],
             server: "chat-zai-glm",
             skills: ["ase-meta-chat", "ase-meta-quorum"],
-            handler: async (spec, tool, action, envKey, envVal) => {
-                if (action === "activate")
-                    await this.mcpAdd(tool, spec.server, { OPENAI_KEY: envVal }, {
-                        type: "stdio", command: [
-                            "npx", "-y", "mcp-to-openai",
-                            "--service", spec.name,
-                            "--mcp-tool", "query",
-                            ...(envKey === "OPENROUTER" ? [
-                                "--openai-url", "https://openrouter.ai/api/v1",
-                                "--openai-api", "completion",
-                                "--openai-model", "z-ai/glm-5.1"
-                            ] : [
-                                "--openai-url", "https://api.z.ai/api/paas/v4/",
-                                "--openai-api", "completion",
-                                "--openai-model", "glm-5.1"
-                            ])
-                        ]
-                    });
-                else
-                    await this.mcpRemove(tool, spec.server);
-            }
+            handler: this.chatMcpHandler({ url: "https://api.z.ai/api/paas/v4/", api: "completion", model: "glm-5.1" }, { model: "z-ai/glm-5.1" })
         },
         {
             id: "brave",

package/dst/ase-skills.js

@@ -242,27 +242,31 @@ export class Skills {
             return [];
     }
     /*  compute composite rank score from weighted metrics:
-        downloads x
-        stars x
+        (downloads + 1) x
+        (stars + 1) x
         ([lifespan =] (updated - created)) x
         ([recentness =] exp(-(now - updated) / halfLife))
-        `"N.A."` factors are treated as neutral `1` so that stacks for which
-        a particular metric is structurally unavailable (e.g. Maven Central
-        exposes no per-artifact download counts) can still be ranked by the
-        remaining metrics, instead of collapsing the entire product to zero.  */
+        Numeric count metrics are shifted by `+1` so that a genuine `0`
+        (e.g. a real package with zero downloads or stars) contributes a
+        neutral `1` instead of collapsing the entire product to zero, while
+        still ordering `0 < 1 < 2 ...`. The `"N.A."` sentinel (a metric that
+        is structurally unavailable, e.g. Maven Central exposes no
+        per-artifact download counts) is likewise treated as neutral `1`, so
+        such stacks can still be ranked by the remaining metrics.  */
     static computeRank(downloads, stars, created, updated) {
-        const d = typeof downloads === "number" ? downloads : 1;
-        const s = typeof stars === "number" ? stars : 1;
+        const d = typeof downloads === "number" ? downloads + 1 : 1;
+        const s = typeof stars === "number" ? stars + 1 : 1;
         const cMs = created !== "" ? Date.parse(created) : NaN;
         const uMs = updated !== "" ? Date.parse(updated) : NaN;
-        if (Number.isNaN(cMs) || Number.isNaN(uMs))
-            return 0;
         const now = Date.now();
         const msPerDay = 1000 * 60 * 60 * 24;
         const halfLife = 365 / 2;
-        const lifespan = Math.max(0, uMs - cMs);
-        const ageDays = Math.max(0, (now - uMs) / msPerDay);
-        const recentness = Math.exp(-ageDays / halfLife);
+        /*  lifespan requires both timestamps; recentness requires the
+            updated timestamp -- any unavailable date-derived factor is
+            treated as neutral `1` so the entry can still be ranked by the
+            remaining metrics, instead of collapsing the product to zero  */
+        const lifespan = (!Number.isNaN(cMs) && !Number.isNaN(uMs)) ? Math.max(0, uMs - cMs) : 1;
+        const recentness = !Number.isNaN(uMs) ? Math.exp(-Math.max(0, (now - uMs) / msPerDay) / halfLife) : 1;
         return d * s * lifespan * recentness;
     }
     /*  compute the per-alternative product-sum (rating) row from a