@event4u/agent-config 8.1.0 → 8.2.0

package/src/scripts/hooks/replay_hook.ts

@@ -356,9 +356,30 @@ function _py_json_dumps(value: unknown, indent: number): string {
   return render(value, 0);
 }
 
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
 const isCliEntry =
-  process.argv[1] !== undefined &&
-  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+  _isCliEntry();
 if (isCliEntry) {
   process.exit(main(process.argv.slice(2)));
 }

package/src/scripts/hooks/rtk_wrap_hook.ts

@@ -27,7 +27,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 import {
   shlexSplit,
@@ -220,9 +220,28 @@ export function main(): number {
   return EXIT_WARN;
 }
 
-const _isCliEntry =
-  process.argv[1] !== undefined &&
-  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
-if (_isCliEntry) {
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
   process.exit(main());
 }

package/src/scripts/hooks_doctor.ts

@@ -410,9 +410,30 @@ export function main(argv?: string[]): number {
   return _final_exit_code(payload, args.strict);
 }
 
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
 const isCliEntry =
-  process.argv[1] !== undefined &&
-  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+  _isCliEntry();
 if (isCliEntry) {
   process.exit(main(process.argv.slice(2)));
 }

package/src/scripts/hooks_status.ts

@@ -284,9 +284,30 @@ export function main(argv?: string[]): number {
   return _final_exit_code(matrix, args.strict);
 }
 
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
 const isCliEntry =
-  process.argv[1] !== undefined &&
-  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+  _isCliEntry();
 if (isCliEntry) {
   process.exit(main(process.argv.slice(2)));
 }

package/src/scripts/injection_scan_hook.ts

@@ -28,7 +28,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const SETTINGS_FILE = ".agent-settings.yml";
 const EXIT_ALLOW = 0;
@@ -277,9 +277,28 @@ function _readStdin(): string {
   return fs.readFileSync(0, "utf-8");
 }
 
-const _isCliEntry =
-  process.argv[1] !== undefined &&
-  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
-if (_isCliEntry) {
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
   process.exit(main());
 }

package/src/scripts/install.ts

@@ -62,7 +62,7 @@
  * - `signal.SIGTERM`/`SIGKILL` + `os.kill(pid, 0)` liveness → `process.kill`.
  */
 
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync, type ChildProcess } from 'node:child_process';
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
@@ -3247,7 +3247,7 @@ function install_global(
 
     if (!state.QUIET) {
         process.stdout.write('\n');
-        success('Global install completed.');
+        success(`Global install completed (v${installed_version}).`);
         process.stdout.write('\n');
     }
     return 0;
@@ -3843,76 +3843,104 @@ function _wizard_spawn(project_root: string, pass_project_root: boolean = true):
     }
     const env = { ...process.env };
 
-    // The Python uses subprocess.Popen + a stderr-draining thread + a
-    // readline loop with progressive timeouts, then child.wait(). Node has no
-    // synchronous equivalent that also streams; we run the whole wizard
-    // handoff via a synchronous helper that mirrors the observable behaviour
-    // (URL banner, stderr tail, browser open, blocking wait). Implemented with
-    // spawnSync for the simple boot+wait, and a bounded readiness poll.
+    // The wizard child is a long-running local server — it must NOT keep the
+    // installer process in the foreground (a blocking wait here forced users
+    // to Ctrl-C out of `agent-config global` / `upgrade`, which then reported
+    // the step as failed). Spawn it detached, poll for the WIZARD_READY line,
+    // print the banner + open the browser, and return while the server keeps
+    // running in the background.
     return _wizard_run_sync(cmd, env, cli);
 }
 
 /**
- * Synchronous wizard run mirroring `_wizard_spawn` + `_wizard_await_ready`.
- * spawnSync blocks until the child exits and captures stdout/stderr; we then
- * scan the captured stdout for the WIZARD_READY line, print the banner / open
- * the browser, and return the child's exit code. A child that never prints
- * WIZARD_READY before exiting falls through to the timeout fallback message.
- *
- * Divergence note: the Python streams stdout line-by-line with a 150s
- * progressive-timeout budget and hands the terminal to a still-running child
- * (Ctrl-C forwarding). spawnSync cannot hand off an interactive child, so this
- * twin runs the child to completion under the same total budget and surfaces
- * the same banner/fallback text. This path is network/subprocess-bound and is
- * NOT exercised by the deterministic golden tests (guarded behind the TTY +
- * dist-present gates).
+ * Detached wizard launch mirroring `_wizard_spawn` + `_wizard_await_ready`.
+ * The child (a local server that keeps running until the wizard finishes) is
+ * spawned detached with its output redirected to a temp log; a bounded poll
+ * scans the log for the WIZARD_READY line, then prints the banner and opens
+ * the browser. The installer returns immediately after — it never blocks on
+ * the server's lifetime. A child that exits or stays silent past the budget
+ * falls through to the fallback message. This path is network/subprocess-
+ * bound and is NOT exercised by the deterministic golden tests (guarded
+ * behind the TTY + dist-present gates).
  */
 function _wizard_run_sync(cmd: string[], env: NodeJS.ProcessEnv, cli: string): number {
     const total = _WIZARD_TIMEOUTS.reduce((a, b) => a + b, 0);
-    let res;
+    const log_path = path.join(
+        os.tmpdir(),
+        `agent-config-wizard-${process.pid}-${Date.now()}.log`,
+    );
+    let child: ChildProcess;
+    let log_fd: number | null = null;
     try {
-        res = spawnSync(cmd[0] as string, cmd.slice(1), {
+        log_fd = fs.openSync(log_path, 'w');
+        child = spawn(cmd[0] as string, cmd.slice(1), {
             env,
-            encoding: 'utf-8',
-            timeout: total * 1000,
-            maxBuffer: 64 * 1024 * 1024,
+            detached: true,
+            stdio: ['ignore', log_fd, log_fd],
         });
+        // ENOENT & friends surface as an async 'error' event on a detached
+        // spawn — swallow it here; the readiness poll below reports the
+        // failure via the fallback message instead of crashing the installer.
+        child.on('error', () => {});
+        child.unref();
     } catch (exc) {
         process.stdout.write(
             `(Wizard failed to start: ${String(exc)}; run 'node ${cli} install --no-open' manually.)\n`,
         );
         return 0;
+    } finally {
+        if (log_fd !== null) {
+            try {
+                fs.closeSync(log_fd);
+            } catch {
+                /* already closed */
+            }
+        }
     }
-    if (res.error && (res.error as NodeJS.ErrnoException).code === 'ENOENT') {
-        process.stdout.write(
-            `(Wizard failed to start: ${String(res.error)}; run 'node ${cli} install --no-open' manually.)\n`,
-        );
-        return 0;
-    }
-    const stdout = res.stdout || '';
+
+    const read_log = (): string => {
+        try {
+            return readText(log_path);
+        } catch {
+            return '';
+        }
+    };
+    const deadline = Date.now() + total * 1000;
     let matched_url: string | null = null;
-    for (const line of stdout.split('\n')) {
-        const m = _WIZARD_READY_RE.exec(line + '\n');
-        if (m) {
-            matched_url = m[1] as string;
-            break;
+    for (;;) {
+        for (const line of read_log().split('\n')) {
+            const m = _WIZARD_READY_RE.exec(line + '\n');
+            if (m) {
+                matched_url = m[1] as string;
+                break;
+            }
         }
+        if (matched_url !== null) break;
+        const pid = child.pid;
+        if (pid === undefined || !pidAlive(pid)) break; // child died before ready
+        if (Date.now() >= deadline) break;
+        sleepMs(200);
     }
     if (matched_url === null) {
-        const stderrLines = (res.stderr || '').split('\n').filter((l) => l !== '');
-        const tail = stderrLines.length ? stderrLines.slice(-20).join('\n  ') : '(no stderr captured)';
+        const logLines = read_log()
+            .split('\n')
+            .filter((l) => l !== '');
+        const tail = logLines.length ? logLines.slice(-20).join('\n  ') : '(no output captured)';
         process.stdout.write(
-            `(Wizard server boot timed out after ${Math.trunc(total)}s; ` +
+            `(Wizard server did not report ready within ${Math.trunc(total)}s; ` +
                 `run 'node ${cli} install --no-open' manually.)\n` +
-                `  Last stderr:\n  ${tail}\n`,
+                `  Last output:\n  ${tail}\n`,
         );
         return 0;
     }
     process.stdout.write('\n');
     process.stdout.write(`Setup wizard ready: ${matched_url}\n`);
     _openBrowser(matched_url);
-    process.stdout.write('(Wizard runs in the background; close the tab or press Ctrl-C to stop.)\n');
-    return res.status ?? 0;
+    process.stdout.write(
+        '(Wizard server keeps running in the background — finish the wizard in the ' +
+            'browser tab; the next install run stops any stale server.)\n',
+    );
+    return 0;
 }
 
 /** `webbrowser.open` — best-effort platform open; never fatal. */

package/src/scripts/inventory_abstraction_budget.ts

@@ -1098,7 +1098,29 @@ export function main(argv: string[] | null = null): number {
     return 0;
 }
 
-const _isMain = import.meta.url === pathToFileURL(path.resolve(process.argv[1] ?? '')).href;
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+const _isMain = _isCliEntry();
 if (_isMain) {
     process.exitCode = main();
 }

package/src/scripts/inventory_frontmatter.ts

@@ -315,6 +315,28 @@ function _isPySpace(ch: string): boolean {
     return /\s/u.test(ch);
 }
 
-if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
     process.exitCode = main();
 }

package/src/scripts/inventory_meta_layers.ts

@@ -514,7 +514,29 @@ function _stableSort<T>(items: T[], cmp: (a: T, b: T) => number): T[] {
     return indexed.map((e) => e.item);
 }
 
-if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
     try {
         process.exitCode = main();
     } catch (e) {

package/src/scripts/iron_law_sha.ts

@@ -214,10 +214,29 @@ function _ljust(s: string, width: number): string {
     return pad > 0 ? s + ' '.repeat(pad) : s;
 }
 
-const _isCliEntry =
-    process.argv[1] !== undefined &&
-    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
-if (_isCliEntry || process.argv[1] === _HERE) {
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
     try {
         process.exitCode = main();
     } catch (err) {

package/src/scripts/janitor.ts

@@ -248,10 +248,29 @@ function main(argv?: readonly string[]): number {
     return 0;
 }
 
-const _isCliEntry =
-    process.argv[1] !== undefined &&
-    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
-if (_isCliEntry || process.argv[1] === _HERE) {
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
     process.exit(main());
 }
 

package/src/scripts/knowledge_global_cli.ts

@@ -36,7 +36,7 @@ import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import process from 'node:process';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import type { SettingsDict, SettingsValue } from './_lib/agent_settings.js';
 import { write_atomic } from './_lib/fs_atomic.js';
@@ -1097,8 +1097,30 @@ function _repoRoot(): string {
     return path.resolve(path.dirname(_thisFile()), '..', '..');
 }
 
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
 const _isMain =
-    process.argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+    _isCliEntry();
 if (_isMain) {
     // Mirror `raise SystemExit(main())`.
     process.exit(main());

package/src/scripts/linked_projects_list.ts

@@ -302,9 +302,28 @@ function _dumpString(s: string): string {
     return out + '"';
 }
 
-const _isCliEntry =
-    process.argv[1] !== undefined &&
-    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
-if (_isCliEntry || process.argv[1] === _HERE) {
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
     process.exitCode = main();
 }

package/src/scripts/lint_agent_security.ts

@@ -217,9 +217,28 @@ export function main(argv: string[] | null = null): number {
   return 0;
 }
 
-const _isCliEntry =
-  process.argv[1] !== undefined &&
-  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
-if (_isCliEntry) {
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
   process.exit(main());
 }

package/src/scripts/lint_agent_skill_names.ts

@@ -233,9 +233,28 @@ export function main(argv?: readonly string[]): number {
 }
 
 const _HERE = fileURLToPath(import.meta.url);
-const _isCliEntry =
-    process.argv[1] !== undefined &&
-    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
-if (_isCliEntry || process.argv[1] === _HERE) {
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
     process.exit(main());
 }