@event4u/agent-config 8.1.0 → 8.3.0

package/src/scripts/sync_gitignore.ts

@@ -626,9 +626,28 @@ export 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(process.argv.slice(2)));
 }

package/src/scripts/telegraph_stats.ts

@@ -439,9 +439,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/tool_registry.ts

@@ -20,6 +20,7 @@
  *     ./scripts-run src/scripts/tool_registry --validate-skill SKILL_TOOLS
  */
 import * as path from 'node:path';
+import * as fs from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 /** Definition of an available tool (mirrors the `ToolDefinition` dataclass). */
@@ -322,9 +323,28 @@ export function main(argv: readonly string[] = process.argv.slice(2)): 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());
 }

package/src/scripts/trigger_coverage.ts

@@ -243,9 +243,28 @@ export function main(argv: string[] | null = null): number {
     return misses ? 1 : 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/update_counts.ts

@@ -276,9 +276,28 @@ export function main(argv: readonly string[] = process.argv.slice(2)): 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(process.argv.slice(2)));
 }

package/src/scripts/update_prices.ts

@@ -211,7 +211,29 @@ export async function main(argv: string[] | null = null): Promise<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) {
     void main().then((rc) => {
         process.exitCode = rc;

package/src/scripts/validate_agent_settings.ts

@@ -255,10 +255,29 @@ export function main(): 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/validate_decision_engine.ts

@@ -343,10 +343,29 @@ function main(): 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) {
     try {
         process.exit(main());
     } catch (exc) {

package/src/scripts/validate_discovery_manifest.ts

@@ -142,10 +142,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) {
     try {
         process.exit(main(process.argv.slice(2)));
     } catch (exc) {

package/src/scripts/validate_frontmatter.ts

@@ -1023,9 +1023,30 @@ function _globSorted(dir: string, pattern: string): string[] {
 
 // Run the CLI only when executed directly (via tsx / the dispatcher), not
 // when imported by a test.
+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/validate_safe_paths.ts

@@ -22,6 +22,7 @@
  */
 
 import * as path from 'node:path';
+import * as fs from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 /** Raised when a path matches the sensitive-file denylist. Subclass of TS Error;
@@ -154,10 +155,29 @@ 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) {
     // Python passes the full sys.argv (program name + args); replicate by
     // prepending a placeholder program name to the user args.
     process.exit(_main(['validate_safe_paths.ts', ...process.argv.slice(2)]));

package/src/scripts/validate_telegraph_carveouts.ts

@@ -477,9 +477,28 @@ class SequenceMatcher {
 }
 
 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());
 }

package/src/scripts/verify_before_complete_hook.ts

@@ -34,7 +34,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { atomic_write_json } from "./hooks/state_io.js";
 
@@ -298,9 +298,30 @@ export function main(argv?: string[]): number {
   return run(_readStdin(), { consumer_root: process.cwd(), verbose: args.verbose });
 }
 
+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/verify_physical_move.ts

@@ -403,9 +403,28 @@ export function main(argv: string[] | null = null): number {
     return ok ? 0 : 1;
 }
 
-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/wrapper_freshness_hook.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 /**
- * session_start concern — keep the project-local `./agent-config` fresh.
+ * session_start concern — keep the project-local `./agent-config` wrapper
+ * AND the installed `.git/hooks/pre-commit` gate fresh.
  *
  * TypeScript twin of `src/scripts/wrapper_freshness_hook.py` (ADR-200 —
  * Python→TS migration, Phase 6 / hooks). Public API mirrors the Python
@@ -10,7 +11,12 @@
  * `refresh --project`). On every session_start the dispatcher runs this in
  * the consumer workspace; if a `./agent-config` wrapper exists there and
  * differs from the canonical template, it is re-stamped so an outdated,
- * fallback-less copy cannot keep breaking the hooks.
+ * fallback-less copy cannot keep breaking the hooks. The same self-heal
+ * covers `.git/hooks/pre-commit` when it is OURS (identified by the
+ * `pre-commit-roadmap-progress` marker) and differs from the shipped
+ * template — a hook installed under an older release otherwise keeps its
+ * stale body forever (the py2ts-era hooks silently no-op'd exactly this
+ * way; `agent-config upgrade` only reaches projects it is run from).
  *
  * Bootstrapping note: this can only heal a wrapper functional enough to
  * invoke the dispatcher in the first place (the current template's global +
@@ -18,14 +24,15 @@
  * this concern — that recovery path is `agent-config upgrade` /
  * `refresh --project`.
  *
- * Contract: never creates a wrapper where none exists (that is an install
- * action); never touches the agent-config source repo; always fail-open
- * (exit 0) — hook self-heal must not block a session.
+ * Contract: never creates a wrapper or hook where none exists (that is an
+ * install action); never overwrites a foreign pre-commit hook; never touches
+ * the agent-config source repo; always fail-open (exit 0) — hook self-heal
+ * must not block a session.
  */
 
 import fs from "node:fs";
 import path from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 import {
   install_cli_wrapper,
@@ -127,6 +134,71 @@ function _parseRoot(argv: string[]): string | null {
   return null;
 }
 
+/** Marker that identifies OUR installed pre-commit hook (never foreign ones). */
+const _PRECOMMIT_MARKER = "pre-commit-roadmap-progress";
+
+/** Resolve `<root>/.git/hooks` — plain dir or worktree/submodule gitdir file. */
+function _git_hooks_dir(root: string): string | null {
+  const dotGit = path.join(root, ".git");
+  if (_isDir(dotGit)) {
+    return path.join(dotGit, "hooks");
+  }
+  if (_isFile(dotGit)) {
+    try {
+      const m = /^gitdir:\s*(.+)\s*$/m.exec(fs.readFileSync(dotGit, "utf-8"));
+      if (m && m[1] !== undefined) {
+        const gitDir = path.isAbsolute(m[1]) ? m[1] : path.join(root, m[1]);
+        return path.join(gitDir, "hooks");
+      }
+    } catch {
+      /* fail-open */
+    }
+  }
+  return null;
+}
+
+/**
+ * Re-stamp a marker-identified, stale `.git/hooks/pre-commit` from the
+ * shipped template. Returns the hook path when re-stamped, else null.
+ * Never creates a hook, never touches foreign hooks, never throws.
+ */
+export function refresh_precommit_hook(root: string): string | null {
+  try {
+    const template = path.join(
+      path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", ".."),
+      "dist",
+      "agent-src",
+      "templates",
+      "hooks",
+      "pre-commit-roadmap-progress",
+    );
+    if (!_isFile(template)) {
+      return null;
+    }
+    const hooksDir = _git_hooks_dir(root);
+    if (hooksDir === null) {
+      return null;
+    }
+    const target = path.join(hooksDir, "pre-commit");
+    if (!_isFile(target)) {
+      return null; // no hook installed — never create one
+    }
+    const current = fs.readFileSync(target, "utf-8");
+    if (!current.includes(_PRECOMMIT_MARKER)) {
+      return null; // foreign hook — never overwrite
+    }
+    const canonical = fs.readFileSync(template, "utf-8");
+    if (current === canonical) {
+      return null; // already fresh
+    }
+    fs.writeFileSync(target, canonical);
+    fs.chmodSync(target, 0o755);
+    return target;
+  } catch {
+    return null; // fail-open — never block the session
+  }
+}
+
 export function main(argv?: string[]): number {
   const args = argv ?? process.argv.slice(2);
   const rootArg = _parseRoot(args);
@@ -140,6 +212,12 @@ export function main(argv?: string[]): number {
     if (_is_source_repo(root)) {
       return EXIT_ALLOW;
     }
+    const hook = refresh_precommit_hook(root);
+    if (hook !== null) {
+      process.stderr.write(
+        `[wrapper] re-stamped stale .git/hooks/pre-commit at ${hook}\n`,
+      );
+    }
     if (!_isFile(path.join(root, "agent-config"))) {
       return EXIT_ALLOW; // no wrapper here — never create one
     }
@@ -171,9 +249,30 @@ export function main(argv?: string[]): number {
   return EXIT_ALLOW;
 }
 
+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)));
 }