@event4u/agent-config 8.1.0 → 8.3.0

package/src/scripts/_cli/cmd_doctor.ts

@@ -26,10 +26,10 @@
  *   here; files without frontmatter are skipped (P5.1 contract).
  *
  * Health checks (see `CHECK_IDS`):
- * scope · stale-orphans · manifest-integrity · lockfile-freshness · bridge-drift ·
- * mcp-mode · mcp-beta-readiness · offline-readiness · python-runtime ·
- * tier-usage-readiness · council-cli · unsupported-combos ·
- * wizard-state.
+ * scope · global-binary · claude-plugin · stale-orphans · manifest-integrity ·
+ * lockfile-freshness · bridge-drift · mcp-mode · mcp-beta-readiness ·
+ * offline-readiness · python-runtime · tier-usage-readiness · council-cli ·
+ * unsupported-combos · wizard-state.
  * Each emits a structured `{id, status, message, remedy}` record with
  * `status` ∈ `ok` / `warn` / `fail` / `skipped` (rendered
  * `✅` / `⚠️` / `❌` / `⏭️`). `--check <id>` runs a single check.
@@ -80,6 +80,9 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import * as YAML from 'yaml';
 
+import * as claude_plugin from '../_lib/claude_plugin.js';
+import * as claude_settings_hooks from '../_lib/claude_settings_hooks.js';
+import { _is_source_repo } from './cmd_refresh.js';
 import * as installed_lock from '../_lib/installed_lock.js';
 import * as installed_tools from '../_lib/installed_tools.js';
 import * as user_global_paths from '../_lib/user_global_paths.js';
@@ -727,6 +730,8 @@ function relativeTo(p: string, base: string): string | null {
 const CHECK_IDS = [
     'scope',
     'global-binary',
+    'claude-plugin',
+    'hook-wiring',
     'stale-orphans',
     'manifest-integrity',
     'lockfile-freshness',
@@ -745,6 +750,8 @@ const CHECK_IDS = [
 const GLOBAL_CHECK_IDS: ReadonlySet<string> = new Set([
     'scope',
     'global-binary',
+    'claude-plugin',
+    'hook-wiring',
     'stale-orphans',
     'mcp-mode',
     'mcp-beta-readiness',
@@ -1000,6 +1007,149 @@ function lstripV(s: string): string {
     return out;
 }
 
+/**
+ * Claude Code plugin state under the single-surface model
+ * (road-to-claude-code-single-surface): the `~/.claude/` file projection is
+ * THE distribution surface for Claude Code — content, and hooks via the
+ * managed settings.json block. An installed marketplace plugin next to the
+ * projection is a **duplicate surface**: every skill/command lists twice
+ * and the plugin's SHA snapshot rots silently. That is `fail`, with the
+ * uninstall command as the fix (never uninstalled autonomously — the plugin
+ * is a user-owned surface).
+ */
+function _check_claude_plugin(): Dict {
+    const claude = shutilWhich('claude');
+    if (claude === null) {
+        return {
+            id: 'claude-plugin',
+            status: 'skipped',
+            message: 'Claude Code CLI not on PATH — plugin check not applicable',
+            remedy: '',
+        };
+    }
+    if (!claude_plugin.claude_plugin_installed()) {
+        return {
+            id: 'claude-plugin',
+            status: 'ok',
+            message:
+                'plugin not installed (single-surface model — the ~/.claude/ file ' +
+                'projection carries content AND hooks)',
+            remedy: '',
+        };
+    }
+    const projection = path.join(os.homedir(), '.claude', 'skills');
+    const projection_present = isDir(projection);
+    if (projection_present) {
+        return {
+            id: 'claude-plugin',
+            status: 'fail',
+            message:
+                'duplicate surface: the marketplace plugin AND the ~/.claude/ file ' +
+                'projection are both installed — every skill/command lists twice and ' +
+                'the plugin snapshot rots silently',
+            remedy:
+                `claude plugin uninstall ${claude_plugin.CLAUDE_PLUGIN_ID}@${claude_plugin.CLAUDE_MARKETPLACE_NAME} ` +
+                '(hooks stay — they are registered in ~/.claude/settings.json; ' +
+                'verify with the hook-wiring check)',
+        };
+    }
+    const snapshot_v = lstripV(claude_plugin.claude_plugin_snapshot_version() || '');
+    const binary_v = lstripV(_current_package_version() || '');
+    if (snapshot_v && binary_v && snapshot_v !== binary_v) {
+        return {
+            id: 'claude-plugin',
+            status: 'warn',
+            message: `plugin snapshot ${snapshot_v} lags binary ${binary_v} — its command surface is stale`,
+            remedy:
+                'agent-config upgrade (refreshes the plugin), or ' +
+                `claude plugin update ${claude_plugin.CLAUDE_PLUGIN_ID}@${claude_plugin.CLAUDE_MARKETPLACE_NAME}`,
+        };
+    }
+    return {
+        id: 'claude-plugin',
+        status: 'warn',
+        message:
+            `plugin installed${snapshot_v ? ` (snapshot ${snapshot_v})` : ''} without the ` +
+            'file projection — deprecated surface; the projection is the supported path',
+        remedy: 'agent-config global (then uninstall the plugin per the printed hint)',
+    };
+}
+
+/**
+ * Managed hook wiring (single-surface model): the deterministic hook matrix
+ * must be registered in ~/.claude/settings.json AND the dispatch target
+ * (`agent-config` binary) must resolve on PATH. Both halves are required —
+ * hooks without a binary silently no-op every session.
+ */
+function _check_hook_wiring(): Dict {
+    const claude = shutilWhich('claude');
+    if (claude === null) {
+        return {
+            id: 'hook-wiring',
+            status: 'skipped',
+            message: 'Claude Code CLI not on PATH — hook-wiring check not applicable',
+            remedy: '',
+        };
+    }
+    const settings_path = path.join(os.homedir(), '.claude', 'settings.json');
+    let missing: string[];
+    try {
+        const matrix = claude_settings_hooks.build_claude_hook_matrix(
+            path.join(_package_root(), 'src', 'scripts', 'hook_manifest.yaml'),
+        );
+        const settings = pathExists(settings_path)
+            ? (JSON.parse(fs.readFileSync(settings_path, 'utf8')) as Record<string, unknown>)
+            : {};
+        const hooks = ((settings['hooks'] ?? {}) as Record<string, unknown>) || {};
+        missing = Object.keys(matrix).filter((ev) => {
+            const groups = hooks[ev];
+            if (!Array.isArray(groups)) return true;
+            return !JSON.stringify(groups).includes(claude_settings_hooks.MANAGED_SIGNATURE);
+        });
+    } catch (e) {
+        return {
+            id: 'hook-wiring',
+            status: 'fail',
+            message: `cannot evaluate managed hooks: ${String(e)}`,
+            remedy: 'fix ~/.claude/settings.json (invalid JSON?), then agent-config refresh --global',
+        };
+    }
+    const binary_ok = shutilWhich('agent-config') !== null;
+    if (missing.length === 0 && binary_ok) {
+        return {
+            id: 'hook-wiring',
+            status: 'ok',
+            message: 'managed hooks registered in ~/.claude/settings.json; dispatch binary on PATH',
+            remedy: '',
+        };
+    }
+    if (missing.length > 0 && claude_plugin.claude_plugin_installed()) {
+        return {
+            id: 'hook-wiring',
+            status: 'warn',
+            message:
+                `managed hooks missing for: ${missing.join(', ')} — currently carried by the ` +
+                'installed plugin (deprecated surface)',
+            remedy: 'agent-config refresh --global (writes the managed settings.json block)',
+        };
+    }
+    const parts: string[] = [];
+    if (missing.length > 0) parts.push(`managed hooks missing for: ${missing.join(', ')}`);
+    if (!binary_ok) parts.push('`agent-config` not on PATH (hooks would silently no-op)');
+    if (parts.length === 0) {
+        // hooks complete, binary missing was the only issue → covered above.
+        parts.push('`agent-config` not on PATH');
+    }
+    return {
+        id: 'hook-wiring',
+        status: 'fail',
+        message: parts.join('; '),
+        remedy: binary_ok
+            ? 'agent-config refresh --global'
+            : 'npm install -g @event4u/agent-config, then agent-config refresh --global',
+    };
+}
+
 function _check_bridge_drift(
     missing: Dict[],
     modified: Dict[],
@@ -1196,6 +1346,20 @@ function _check_python_runtime(): Dict {
 }
 
 function _check_mcp_beta_readiness(project_root: string): Dict {
+    // Maintainer-scoped gate: the six artefacts live in the agent-config
+    // SOURCE repo. In a consumer project the paths can never exist, so the
+    // check used to emit a meaningless "6/6 gates pending" warning on every
+    // consumer doctor run — skip instead.
+    if (!_is_source_repo(project_root)) {
+        return {
+            id: 'mcp-beta-readiness',
+            status: 'skipped',
+            message:
+                'MCP beta promotion gates apply to the agent-config source repo, ' +
+                'not consumer projects',
+            remedy: '',
+        };
+    }
     const pending: string[] = [];
     for (const [gate_id, rel] of MCP_BETA_GATES) {
         if (!pathExists(path.join(project_root, rel))) {
@@ -1751,6 +1915,8 @@ function _run_checks(
     const runners: Record<string, CheckRunner> = {
         scope: () => _check_scope(project_root),
         'global-binary': () => _check_global_binary(project_root),
+        'claude-plugin': _check_claude_plugin,
+        'hook-wiring': _check_hook_wiring,
         'stale-orphans': _check_stale_orphans,
         'manifest-integrity': () => _check_manifest_integrity(manifest),
         'lockfile-freshness': () => _check_lockfile_freshness(manifest),
@@ -1822,6 +1988,8 @@ function _run_checks_no_manifest(
     const runners: Record<string, CheckRunner> = {
         scope: () => _check_scope(project_root),
         'global-binary': () => _check_global_binary(project_root),
+        'claude-plugin': _check_claude_plugin,
+        'hook-wiring': _check_hook_wiring,
         'stale-orphans': _check_stale_orphans,
         'manifest-integrity': () => _skipped_manifest_check('manifest-integrity'),
         'lockfile-freshness': () => _skipped_manifest_check('lockfile-freshness'),
@@ -2258,10 +2426,29 @@ function main(argv: string[] | null = null): number {
 
 // --- CLI entry ---
 
-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(process.argv.slice(2));
     } catch (e) {
@@ -2290,6 +2477,7 @@ export {
     _check_manifest_integrity,
     _check_lockfile_freshness,
     _check_global_binary,
+    _check_claude_plugin,
     _check_bridge_drift,
     _check_mcp_mode,
     _check_offline_readiness,

package/src/scripts/_cli/cmd_explain.ts

@@ -713,10 +713,29 @@ export function main(argv: string[] | null = null): number {
 
 // --- CLI entry ---
 
-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(process.argv.slice(2));
     } catch (e) {

package/src/scripts/_cli/cmd_export.ts

@@ -359,10 +359,29 @@ export function main(argv: string[] | null = null, options: MainOptions = {}): n
 // Python: `if __name__ == "__main__": sys.exit(main())` (argparse reads
 // sys.argv[1:] inside the parser default).
 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) {
     try {
         process.exitCode = main();
     } catch (exc) {

package/src/scripts/_cli/cmd_fleet.ts

@@ -385,10 +385,29 @@ export async function main(argv: string[] | null = null): Promise<number> {
 
 // --- CLI entry ---
 
-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) {
     main(process.argv.slice(2)).then(
         (code) => {
             process.exitCode = code;

package/src/scripts/_cli/cmd_migrate.ts

@@ -935,10 +935,29 @@ declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
 const _bundled =
     typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
 const _HERE = fileURLToPath(import.meta.url);
-const _isCliEntry =
-    process.argv[1] !== undefined &&
-    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
-if (!_bundled && (_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 (!_bundled && (_isCliEntry() || process.argv[1] === _HERE)) {
     try {
         process.exitCode = main(process.argv.slice(2));
     } catch (exc) {

package/src/scripts/_cli/cmd_preflight.ts

@@ -18,6 +18,7 @@
 import * as os from 'node:os';
 import * as path from 'node:path';
 import process from 'node:process';
+import * as fs from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import {
@@ -151,9 +152,28 @@ export function main(argv: string[] | null = null): number {
 
 // --- CLI entry ---
 
-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(process.argv.slice(2));
 }

package/src/scripts/_cli/cmd_prune.ts

@@ -594,10 +594,29 @@ export function main(argv: string[] | null = null): number {
 
 // CLI entry guard — set process.exitCode; never call process.exit().
 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) {
     try {
         process.exitCode = main(process.argv.slice(2));
     } catch (exc) {

package/src/scripts/_cli/cmd_refresh.ts

@@ -502,10 +502,29 @@ export function main(argv: string[] | null = null, options: MainOptions = {}): n
 
 // --- CLI entry ---
 
-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(process.argv.slice(2));
     } catch (e) {

package/src/scripts/_cli/cmd_settings_check.ts

@@ -391,10 +391,29 @@ export function main(argv: string[] | null = null, options: MainOptions = {}): n
 
 // CLI entry guard — set process.exitCode; never call process.exit().
 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) {
     try {
         process.exitCode = main(process.argv.slice(2));
     } catch (exc) {

package/src/scripts/_cli/cmd_settings_migrate.ts

@@ -328,10 +328,29 @@ export function main(argv: string[] | null = null, options: MainOptions = {}): n
 // CLI entry guard — set process.exitCode; never call process.exit().
 // Python: `if __name__ == "__main__": sys.exit(main())`.
 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) {
     try {
         process.exitCode = main();
     } catch (exc) {

package/src/scripts/_cli/cmd_sync.ts

@@ -365,10 +365,29 @@ export function main(argv: string[] | null = null, options: MainOptions = {}): n
 // CLI entry guard — set process.exitCode; never call process.exit().
 // Python: `if __name__ == "__main__": sys.exit(main(sys.argv[1:]))`.
 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) {
     try {
         process.exitCode = main(process.argv.slice(2));
     } catch (exc) {