@event4u/agent-config 8.1.0 → 8.3.0

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

@@ -27,6 +27,9 @@
 #                     the comma-separated values are unioned.
 #   --list-tools      Print supported tool IDs with descriptions, then exit
 #   --yes, -y         Non-interactive mode: do not prompt (default for non-TTY)
+#   --no-ui           Unattended install: never launch the browser setup
+#                     wizard and skip the terminal tool picker (tools default
+#                     to all). Used by `agent-config upgrade`.
 #   --force           Overwrite existing bridge files
 #   --dry-run         Show what payload sync would do (does not run bridges)
 #   --verbose         Detailed payload sync output
@@ -95,12 +98,13 @@ MINIMAL=false
 VALIDATE_ONLY=false
 FLEET_CONFIG=""
 USER_TYPE=""
+NO_UI=false
 
 # Single source of truth for valid tool IDs (also referenced by install.sh / install.py).
 VALID_TOOLS="claude-code claude-desktop cursor windsurf cline gemini-cli copilot augment aider codex roocode continue kilocode zed jetbrains kiro all"
 
 show_help() {
-    sed -n '3,58p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    sed -n '3,61p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
 }
 
 list_tools() {
@@ -167,6 +171,7 @@ while [[ $# -gt 0 ]]; do
         --ai=*)          TOOLS="${TOOLS:+$TOOLS,}${1#*=}"; TOOLS_EXPLICIT=true; shift ;;
         --list-tools)    LIST_TOOLS=true; shift ;;
         --yes|-y)        YES=true; shift ;;
+        --no-ui)         NO_UI=true; shift ;;
         --force)         FORCE=true; shift ;;
         --dry-run)       DRY_RUN=true; shift ;;
         --verbose)       VERBOSE=true; shift ;;
@@ -194,6 +199,15 @@ if $LIST_TOOLS; then
     exit 0
 fi
 
+# --no-ui = unattended install (the `agent-config upgrade` path). Export the
+# suppression env so every downstream stage (install.ts honors both the flag
+# and AGENT_CONFIG_NO_UI) skips the browser setup wizard — the wizard is an
+# onboarding surface whose foreground server used to block `upgrade` until
+# Ctrl-C.
+if $NO_UI; then
+    export AGENT_CONFIG_NO_UI=1
+fi
+
 # road-to-global-only-install § Phase 3.3 — consumer-floor gate.
 #
 # Consumer installs are global-only (ADR-020). Explicit --scope=project
@@ -282,8 +296,8 @@ prompt_tools() {
 # When an interactive global install will hand off to the browser wizard,
 # the wizard is the single tool-selection surface — skip the terminal
 # picker so it does not pre-empt (and, via TOOLS_EXPLICIT, suppress) the
-# GUI. Mirrors install.py::_wizard_should_launch minus the --no-ui flag,
-# which the bash orchestrator never receives (it errors on unknown args).
+# GUI. Mirrors install.py::_wizard_should_launch (the --no-ui flag is
+# handled here too — it suppresses both the wizard and the picker).
 # Headless paths (no TTY / CI / AGENT_CONFIG_NO_UI) still get the picker.
 wizard_will_handle_tools=false
 if $GLOBAL && [[ -t 0 && -t 1 && -z "${CI:-}" ]] \
@@ -291,8 +305,12 @@ if $GLOBAL && [[ -t 0 && -t 1 && -z "${CI:-}" ]] \
     wizard_will_handle_tools=true
 fi
 
+# --no-ui also skips the terminal picker: the flag means "fully unattended"
+# (its only caller today is `agent-config upgrade`, where a mid-upgrade
+# prompt reads as a hang). Tools fall through to the "all" default below —
+# the same effective selection the wizard-handoff path used.
 if ! $MINIMAL && ! $TOOLS_EXPLICIT && ! $YES && ! $QUIET && ! $LIST_TOOLS \
-   && [[ -t 0 && -t 1 ]] && ! $wizard_will_handle_tools; then
+   && [[ -t 0 && -t 1 ]] && ! $wizard_will_handle_tools && ! $NO_UI; then
     prompt_tools
     TOOLS_EXPLICIT=true
 fi
@@ -416,6 +434,7 @@ run_bridges() {
     [[ -n "$CUSTOM_PATH" ]] && args+=(--custom-path="$CUSTOM_PATH")
     $OFFLINE && args+=(--offline)
     $MINIMAL && args+=(--minimal)
+    $NO_UI && args+=(--no-ui)
     args+=(--tools="$TOOLS")
     "${runner[@]}" "${args[@]}"
 }

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';
@@ -78,6 +78,7 @@ import * as global_deploy_inventory from './_lib/global_deploy_inventory.js';
 import * as installed_tools from './_lib/installed_tools.js';
 import * as user_global_paths from './_lib/user_global_paths.js';
 import * as claude_desktop_bundler from './_lib/claude_desktop_bundler.js';
+import * as claude_settings_hooks from './_lib/claude_settings_hooks.js';
 import { find_project_root_with_anchor, load_agent_settings } from './_lib/agent_settings.js';
 import { detect_module_roots } from './_lib/module_detection.js';
 import {
@@ -2914,6 +2915,35 @@ function _deploy_global_content(
         }
         _emit_progress({ type: 'reaped', tool: tool_id, count: reaped.length });
         results[tool_id] = [written_total, skipped_total, 'deployed', written_paths];
+
+        // Single-surface model (road-to-claude-code-single-surface): the
+        // deterministic hook matrix registers directly in the user-scope
+        // settings file — the marketplace plugin is no longer required for
+        // hooks. Failure here must not sink the content deploy (hooks can
+        // be re-wired via `agent-config refresh --global` / doctor).
+        if (tool_id === 'claude-code') {
+            try {
+                const manifest = path.join(package_root, 'src', 'scripts', 'hook_manifest.yaml');
+                const matrix = claude_settings_hooks.build_claude_hook_matrix(manifest);
+                const res = claude_settings_hooks.ensure_managed_hooks(
+                    path.join(anchor, 'settings.json'),
+                    matrix,
+                );
+                if (!state.QUIET) {
+                    if (res.changed) {
+                        success(
+                            `claude-code: managed hooks registered in ~/.claude/settings.json ` +
+                                `(${res.events.length} event(s))`,
+                        );
+                    } else {
+                        skip('claude-code: managed hooks already registered');
+                    }
+                }
+            } catch (e) {
+                warn(`claude-code: managed-hook registration failed — ${String(e)}`);
+                _emit_progress({ type: 'hooks_failed', tool: tool_id, error: String(e) });
+            }
+        }
     }
     return results;
 }
@@ -3247,7 +3277,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 +3873,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());