maqcli 0.6.0 → 0.6.2

package/dist/core/command-catalog.js

@@ -42,6 +42,7 @@ export const maqCommands = [
     { name: "flow", category: "control", summary: "Scheduled agent sessions (run under the daemon).", usage: "maq flow [list|add|remove]", needsInput: "none", args: [] },
     { name: "audit", category: "control", summary: "Verify a run's hash-chained audit log.", usage: "maq audit verify <run-dir>", needsInput: "none", args: [] },
     { name: "security", category: "system", summary: "Enforced security rules (protected paths, egress allowlist, injection scanning) + recent findings.", usage: "maq security [report|rules|scan <path>]", needsInput: "none", args: [] },
+    { name: "update", category: "system", summary: "Check npm for a newer maqcli and self-update.", usage: "maq update [--check]", needsInput: "none", args: [{ name: "check", type: "boolean", description: "only check, don't install" }] },
 ];
 /** Catalog of AI worker CLIs' own commands/flags (verified 2026-07-01). */
 export const aiCliCatalog = [

package/dist/core/launcher.js

@@ -353,7 +353,7 @@ async function connectMobile(rl) {
 async function launchUi(authKey) {
     // Reuse the daemon; open its landing page. Import lazily to avoid a cycle.
     const { createDaemon } = await import("../server/daemon.js");
-    const daemon = createDaemon({ token: authKey, version: "0.6.0" });
+    const daemon = createDaemon({ token: authKey, version: "0.6.2" });
     try {
         const { host, port } = await daemon.listen();
         const url = `http://${host}:${port}/`;

package/dist/core/update.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Self-update — lets a user run `maq update` from inside the CLI instead of
+ * remembering the npm incantation. Checks the npm registry for the latest
+ * published version, compares it to the running version, and (unless
+ * --check-only) re-installs globally via npm.
+ *
+ * Network access here is a deliberate, user-initiated exception to the
+ * default-deny egress posture (core/security.ts) — it only ever talks to the
+ * npm registry, and only when the user explicitly runs this command.
+ *
+ * THE WINDOWS FILE-LOCK PROBLEM AND ITS FIX
+ * ------------------------------------------
+ * `npm install -g` has to overwrite the `maq`/`maqcli` shim and the running
+ * package's files. If that `npm install` runs as a CHILD of the currently
+ * executing `maq` process (i.e. `maq` spawns it and waits), Windows can hold
+ * file/handle locks on the very binary being replaced for as long as the
+ * parent process tree is alive — npm's overwrite can fail or silently leave a
+ * half-updated install. Waiting-for-the-child is the actual cause, not npm
+ * itself.
+ *
+ * The fix: spawn the npm install fully DETACHED (`detached: true`,
+ * `stdio: "ignore"`, `.unref()`) so it is not a child of `maq` in any way
+ * meaningful to the OS's lock semantics, then have `maq` EXIT IMMEDIATELY
+ * instead of waiting on it. By the time npm actually touches the shim files,
+ * the process that used to hold them has already terminated. This is the same
+ * pattern self-updating CLIs (rustup, deno, bun) use on Windows.
+ */
+import { spawn } from "node:child_process";
+export interface VersionInfo {
+    current: string;
+    latest: string | null;
+    upToDate: boolean;
+    error?: string;
+}
+/** Returns true if `latest` is strictly newer than `current`. */
+export declare function isNewer(current: string, latest: string): boolean;
+/** Query the npm registry for the latest published version of `maqcli`. */
+export declare function fetchLatestVersion(registryUrl?: string, timeoutMs?: number): Promise<string>;
+/** Compare the running version against the registry; never throws. */
+export declare function checkForUpdate(currentVersion: string): Promise<VersionInfo>;
+export interface UpdateOutcome {
+    ok: boolean;
+    message: string;
+    version?: VersionInfo;
+    /** Set when the update was launched detached; the caller should exit(0) promptly instead of doing more work. */
+    detachedPid?: number;
+    /** Path a --wait caller can poll to see the detached install's result. */
+    logPath?: string;
+}
+/**
+ * Build the OS-appropriate command to run `npm install -g maqcli@<version>`
+ * fully detached from the current process (see module doc for why). On
+ * Windows this wraps npm in a new cmd.exe so the child truly detaches from
+ * the parent's console/job object; on POSIX, npm itself is spawned directly
+ * with `detached: true`.
+ */
+export declare function detachedInstallCommand(version: string, logPath: string, platform?: NodeJS.Platform): {
+    cmd: string;
+    args: string[];
+};
+/**
+ * Launch the update fully detached and return immediately — the caller
+ * (cmdUpdate) should print guidance and exit right away rather than await
+ * anything else, which is what avoids the Windows file-lock failure mode.
+ * `spawner` is injectable for tests so nothing is actually spawned there.
+ */
+export declare function launchDetachedUpdate(version: string, logPath: string, spawner?: typeof spawn): number | undefined;
+export interface UpdateOutcome {
+    ok: boolean;
+    message: string;
+    version?: VersionInfo;
+    /** Set when the update was launched detached; the caller should exit(0) promptly instead of doing more work. */
+    detachedPid?: number;
+    /** Path a caller can inspect afterward to see the detached install's own npm output. */
+    logPath?: string;
+}
+/**
+ * Perform the update: check the registry, and if a newer version exists,
+ * launch `npm install -g maqcli@<latest>` DETACHED from this process (see the
+ * module doc — this is what avoids the Windows file-lock failure mode where
+ * npm can't overwrite files the running `maq` process still holds open).
+ *
+ * The detached path is the default and recommended flow: this function
+ * returns as soon as the install is launched; it does not wait for npm to
+ * finish, because waiting would defeat the point (the parent would still be
+ * alive, still holding the lock, for the whole duration).
+ *
+ * `opts.wait: true` (used by tests, and by --wait for a CI/non-interactive
+ * caller that can tolerate the lock risk) runs synchronously via `runner`
+ * instead, so the outcome is available in the same process.
+ */
+export declare function performUpdate(currentVersion: string, opts?: {
+    checkOnly?: boolean;
+    /** Run synchronously in-process instead of detaching (tests; --wait). */
+    wait?: boolean;
+    runner?: (cmd: string, args: string[]) => Promise<{
+        code: number | null;
+        stdout: string;
+        stderr: string;
+    }>;
+    spawner?: typeof spawn;
+    logPath?: string;
+}): Promise<UpdateOutcome>;
+/**
+ * Read a detached update's log file (best-effort). Used by `maq update
+ * --status` to show what the background install actually did, since the
+ * `maq update` invocation that launched it already exited.
+ */
+export declare function readUpdateLog(logPath: string): Promise<string | null>;
+/**
+ * Ask npm what is ACTUALLY installed globally right now (ground truth, not
+ * "what did we ask for") — this is what confirms a detached update landed,
+ * independent of which process/terminal you're asking from.
+ */
+export declare function installedGlobalVersion(runner?: (cmd: string, args: string[]) => Promise<{
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}>): Promise<string | null>;

package/dist/core/update.js

@@ -0,0 +1,185 @@
+/**
+ * Self-update — lets a user run `maq update` from inside the CLI instead of
+ * remembering the npm incantation. Checks the npm registry for the latest
+ * published version, compares it to the running version, and (unless
+ * --check-only) re-installs globally via npm.
+ *
+ * Network access here is a deliberate, user-initiated exception to the
+ * default-deny egress posture (core/security.ts) — it only ever talks to the
+ * npm registry, and only when the user explicitly runs this command.
+ *
+ * THE WINDOWS FILE-LOCK PROBLEM AND ITS FIX
+ * ------------------------------------------
+ * `npm install -g` has to overwrite the `maq`/`maqcli` shim and the running
+ * package's files. If that `npm install` runs as a CHILD of the currently
+ * executing `maq` process (i.e. `maq` spawns it and waits), Windows can hold
+ * file/handle locks on the very binary being replaced for as long as the
+ * parent process tree is alive — npm's overwrite can fail or silently leave a
+ * half-updated install. Waiting-for-the-child is the actual cause, not npm
+ * itself.
+ *
+ * The fix: spawn the npm install fully DETACHED (`detached: true`,
+ * `stdio: "ignore"`, `.unref()`) so it is not a child of `maq` in any way
+ * meaningful to the OS's lock semantics, then have `maq` EXIT IMMEDIATELY
+ * instead of waiting on it. By the time npm actually touches the shim files,
+ * the process that used to hold them has already terminated. This is the same
+ * pattern self-updating CLIs (rustup, deno, bun) use on Windows.
+ */
+import { spawn } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execSafe } from "./exec.js";
+/** Parse "x.y.z" into a comparable tuple; non-numeric parts sort as 0. */
+function parseSemver(v) {
+    const parts = v.replace(/^v/, "").split(".").map((p) => parseInt(p, 10));
+    return [parts[0] || 0, parts[1] || 0, parts[2] || 0];
+}
+/** Returns true if `latest` is strictly newer than `current`. */
+export function isNewer(current, latest) {
+    const a = parseSemver(current);
+    const b = parseSemver(latest);
+    for (let i = 0; i < 3; i++) {
+        if (b[i] > a[i])
+            return true;
+        if (b[i] < a[i])
+            return false;
+    }
+    return false;
+}
+/** Query the npm registry for the latest published version of `maqcli`. */
+export async function fetchLatestVersion(registryUrl = "https://registry.npmjs.org/maqcli/latest", timeoutMs = 8000) {
+    const res = await fetch(registryUrl, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!res.ok)
+        throw new Error(`registry returned ${res.status}`);
+    const body = (await res.json());
+    if (!body.version)
+        throw new Error("registry response missing a version field");
+    return body.version;
+}
+/** Compare the running version against the registry; never throws. */
+export async function checkForUpdate(currentVersion) {
+    try {
+        const latest = await fetchLatestVersion();
+        return { current: currentVersion, latest, upToDate: !isNewer(currentVersion, latest) };
+    }
+    catch (e) {
+        return { current: currentVersion, latest: null, upToDate: true, error: e.message };
+    }
+}
+/**
+ * Build the OS-appropriate command to run `npm install -g maqcli@<version>`
+ * fully detached from the current process (see module doc for why). On
+ * Windows this wraps npm in a new cmd.exe so the child truly detaches from
+ * the parent's console/job object; on POSIX, npm itself is spawned directly
+ * with `detached: true`.
+ */
+export function detachedInstallCommand(version, logPath, platform = process.platform) {
+    const pkg = `maqcli@${version}`;
+    if (platform === "win32") {
+        // /c runs and closes; redirection captures npm's own output for later inspection.
+        return { cmd: "cmd.exe", args: ["/c", `npm install -g ${pkg} > "${logPath}" 2>&1`] };
+    }
+    return { cmd: "sh", args: ["-c", `npm install -g ${pkg} > '${logPath}' 2>&1`] };
+}
+/**
+ * Launch the update fully detached and return immediately — the caller
+ * (cmdUpdate) should print guidance and exit right away rather than await
+ * anything else, which is what avoids the Windows file-lock failure mode.
+ * `spawner` is injectable for tests so nothing is actually spawned there.
+ */
+export function launchDetachedUpdate(version, logPath, spawner = spawn) {
+    const { cmd, args } = detachedInstallCommand(version, logPath);
+    const child = spawner(cmd, args, { detached: true, stdio: "ignore", windowsHide: true });
+    child.on("error", () => {
+        /* best-effort; the log file (or its absence) is the source of truth */
+    });
+    child.unref();
+    return child.pid;
+}
+/**
+ * Perform the update: check the registry, and if a newer version exists,
+ * launch `npm install -g maqcli@<latest>` DETACHED from this process (see the
+ * module doc — this is what avoids the Windows file-lock failure mode where
+ * npm can't overwrite files the running `maq` process still holds open).
+ *
+ * The detached path is the default and recommended flow: this function
+ * returns as soon as the install is launched; it does not wait for npm to
+ * finish, because waiting would defeat the point (the parent would still be
+ * alive, still holding the lock, for the whole duration).
+ *
+ * `opts.wait: true` (used by tests, and by --wait for a CI/non-interactive
+ * caller that can tolerate the lock risk) runs synchronously via `runner`
+ * instead, so the outcome is available in the same process.
+ */
+export async function performUpdate(currentVersion, opts = {}) {
+    const version = await checkForUpdate(currentVersion);
+    if (version.error) {
+        return { ok: false, message: `could not check for updates: ${version.error}`, version };
+    }
+    if (version.upToDate) {
+        return { ok: true, message: `already up to date (v${version.current})`, version };
+    }
+    if (opts.checkOnly) {
+        return { ok: true, message: `update available: v${version.current} -> v${version.latest}`, version };
+    }
+    const latest = version.latest;
+    if (!opts.wait) {
+        const logPath = opts.logPath ?? defaultLogPath();
+        const pid = launchDetachedUpdate(latest, logPath, opts.spawner);
+        return {
+            ok: true,
+            message: `update to v${latest} launched in the background (detached, avoids file locks). Open a new terminal in a few seconds to pick it up.`,
+            version,
+            detachedPid: pid,
+            logPath,
+        };
+    }
+    // --wait / test path: run synchronously in this process. On Windows this
+    // can hit the file-lock failure mode described above if `maq` itself is
+    // the thing being replaced; it's kept for CI and for tests with a stubbed
+    // runner, not as the default interactive experience.
+    const runner = opts.runner ?? (async (cmd, args) => execSafe(cmd, args, { timeoutMs: 120000 }));
+    const outcome = await runner("npm", ["install", "-g", `maqcli@${latest}`]);
+    if (outcome.code !== 0) {
+        return {
+            ok: false,
+            message: `update to v${latest} failed (exit ${outcome.code}): ${outcome.stderr.slice(0, 400) || outcome.stdout.slice(0, 400)}`,
+            version,
+        };
+    }
+    return { ok: true, message: `updated v${version.current} -> v${latest}`, version };
+}
+function defaultLogPath() {
+    return join(tmpdir(), `maq-update-${Date.now()}.log`);
+}
+/**
+ * Read a detached update's log file (best-effort). Used by `maq update
+ * --status` to show what the background install actually did, since the
+ * `maq update` invocation that launched it already exited.
+ */
+export async function readUpdateLog(logPath) {
+    try {
+        const { readFile } = await import("node:fs/promises");
+        return await readFile(logPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Ask npm what is ACTUALLY installed globally right now (ground truth, not
+ * "what did we ask for") — this is what confirms a detached update landed,
+ * independent of which process/terminal you're asking from.
+ */
+export async function installedGlobalVersion(runner = (cmd, args) => execSafe(cmd, args, { timeoutMs: 15000 })) {
+    const outcome = await runner("npm", ["list", "-g", "maqcli", "--depth=0", "--json"]);
+    if (outcome.code !== 0)
+        return null;
+    try {
+        const parsed = JSON.parse(outcome.stdout);
+        return parsed.dependencies?.maqcli?.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/index.js

@@ -43,9 +43,10 @@ import { runInit } from "./core/init-wizard.js";
 import { CostTracker } from "./core/cost-tracker.js";
 import { runLauncher } from "./core/launcher.js";
 import { runOrchestration } from "./core/orchestrator.js";
+import { performUpdate, installedGlobalVersion } from "./core/update.js";
 import { checkProtectedPath, scanForInjection, securityLog, securityRules, } from "./core/security.js";
 import { readFileSync, statSync } from "node:fs";
-const VERSION = "0.6.0";
+const VERSION = "0.6.2";
 async function main(argv) {
     const [command, ...rest] = argv;
     switch (command) {
@@ -79,6 +80,8 @@ async function main(argv) {
             return cmdOrchestrate(rest);
         case "security":
             return cmdSecurity(rest);
+        case "update":
+            return cmdUpdate(rest);
         case "verify":
             return cmdVerify(rest);
         case "serve":
@@ -426,6 +429,62 @@ function cmdSecurity(args) {
     return 0;
 }
 /** Machine-readable rule set — shared shape with the daemon's GET /v1/security. */
+async function cmdUpdate(args) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            ...commonFlags(),
+            check: { type: "boolean", default: false },
+            wait: { type: "boolean", default: false },
+            status: { type: "boolean", default: false },
+        },
+        allowPositionals: true,
+    });
+    if (values.status) {
+        const installed = await installedGlobalVersion();
+        if (values.json) {
+            logger.out(JSON.stringify({ runningVersion: VERSION, installedGlobalVersion: installed }, null, 0));
+            return 0;
+        }
+        logger.out(`this terminal's maq:      v${VERSION}`);
+        logger.out(`globally installed maq:   ${installed ? "v" + installed : "unknown (npm list failed)"}`);
+        if (installed && installed !== VERSION) {
+            logger.out("\nThese differ — a background update likely finished. Open a NEW terminal window");
+            logger.out("(this one is still running the old code in memory) to pick up the new version.");
+        }
+        else if (installed) {
+            logger.out("\nUp to date and consistent.");
+        }
+        return 0;
+    }
+    logger.out(`current version: ${VERSION}`);
+    logger.out(values.check ? "checking npm for a newer version…" : "checking npm and updating if a newer version is available…");
+    const outcome = await performUpdate(VERSION, { checkOnly: values.check, wait: values.wait });
+    if (values.json) {
+        logger.out(JSON.stringify(outcome, null, 0));
+        return outcome.ok ? 0 : 1;
+    }
+    logger.out(outcome.message);
+    if (outcome.ok && outcome.version && !outcome.version.upToDate) {
+        if (values.check) {
+            logger.out("run 'maq update' (without --check) to install it.");
+        }
+        else if (outcome.detachedPid) {
+            // Detached path: THIS is the fix for the Windows file-lock problem —
+            // maq is exiting now, on purpose, so nothing holds a lock on the files
+            // npm is about to overwrite. Give the user a concrete way to confirm it
+            // landed instead of leaving them guessing.
+            logger.out("");
+            logger.out(`  install log: ${outcome.logPath}`);
+            logger.out("  check progress any time with:  maq update --status");
+            logger.out("  (open a NEW terminal window before running that — this one will keep showing the old version)");
+        }
+        else {
+            logger.out("restart your terminal (or open a new one) to pick up the updated binary.");
+        }
+    }
+    return outcome.ok ? 0 : 1;
+}
 async function cmdServe(args) {
     const { values } = parseArgs({
         args,
@@ -1177,6 +1236,7 @@ function printHelp() {
         '  completion <shell>           Shell completions (bash/zsh/fish/powershell)',
         "  audit verify <run-dir>       Verify a run's hash-chained audit log",
         "  security [report|rules|scan <path>|add|remove]  Enforced security rules + recent findings",
+        "  update [--check|--wait|--status]  Check npm for a newer maqcli and self-update (detached; avoids file locks)",
         "  config [get|set|path|reset]  Read or update ~/.maqcli/config.json",
         "  version | help [<topic>]",
         "",

package/dist/server/daemon.js

@@ -52,7 +52,7 @@ export function createDaemon(opts = {}) {
     const host = opts.host ?? process.env.MAQ_HOST ?? "127.0.0.1";
     const port = opts.port ?? Number(process.env.MAQ_PORT ?? 7717);
     const token = opts.token ?? process.env.MAQ_TOKEN ?? generateToken();
-    const version = opts.version ?? "0.6.0";
+    const version = opts.version ?? "0.6.2";
     const corsOrigin = opts.corsOrigin ?? process.env.MAQ_CORS_ORIGIN;
     const registry = opts.registry ?? new SessionRegistry();
     const interactive = new InteractiveRegistry();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maqcli",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "MAQ master orchestrator — a token-efficient, agent-agnostic supervisor CLI that sits on top of any worker CLI (AI or not) via a Scout -> Plan -> Execute -> Verify pipeline.",
   "type": "module",
   "bin": {