maqcli 0.6.1 → 0.6.2

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.1" });
+    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

@@ -7,7 +7,25 @@
  * 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;
@@ -24,17 +42,78 @@ 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,
- * run `npm install -g maqcli@<latest>`. `runner` is injectable for tests —
- * it defaults to execSafe (shell:false, argument array; never string-built).
+ * 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

@@ -7,7 +7,27 @@
  * 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) {
@@ -46,10 +66,50 @@ export async function checkForUpdate(currentVersion) {
         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,
- * run `npm install -g maqcli@<latest>`. `runner` is injectable for tests —
- * it defaults to execSafe (shell:false, argument array; never string-built).
+ * 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);
@@ -62,14 +122,64 @@ export async function performUpdate(currentVersion, opts = {}) {
     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@${version.latest}`]);
+    const outcome = await runner("npm", ["install", "-g", `maqcli@${latest}`]);
     if (outcome.code !== 0) {
         return {
             ok: false,
-            message: `update to v${version.latest} failed (exit ${outcome.code}): ${outcome.stderr.slice(0, 400) || outcome.stdout.slice(0, 400)}`,
+            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${version.latest}`, 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,10 +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 } from "./core/update.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.1";
+const VERSION = "0.6.2";
 async function main(argv) {
     const [command, ...rest] = argv;
     switch (command) {
@@ -432,22 +432,56 @@ function cmdSecurity(args) {
 async function cmdUpdate(args) {
     const { values } = parseArgs({
         args,
-        options: { ...commonFlags(), check: { type: "boolean", default: false } },
+        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 });
+    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 && !values.check) {
-        logger.out("restart your terminal (or open a new one) to pick up the updated binary.");
-    }
-    if (outcome.ok && outcome.version && !outcome.version.upToDate && values.check) {
-        logger.out("run 'maq update' (without --check) to install it.");
+    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;
 }
@@ -1202,7 +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]             Check npm for a newer maqcli and self-update",
+        "  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.1";
+    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.1",
+  "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": {