@event4u/agent-config 8.1.0 → 8.3.0

package/src/scripts/release.ts

@@ -8,16 +8,27 @@
  * subprocess argv/cwd/env. No behaviour changes — latent quirks are
  * replicated and flagged inline, not fixed.
  *
- * Invoked via `task release`. The bump level (major/minor/patch) is
- * auto-detected from Conventional Commits since the last tag; pass
- * `--as {major,minor,patch}` to force, or `--version X.Y.Z` to pin.
+ * Invoked via `task release` (interactive, local) OR
+ * `.github/workflows/release.yml` (unattended, triggered by merging a PR
+ * labeled `release` / `release:major` / `release:minor` / `release:patch`
+ * — pass `--ci`). Both entry points share this one pipeline; `--ci` only
+ * changes the gh-auth probe (GITHUB_TOKEN, not a user token), adds a
+ * nothing-to-release short-circuit (see `nothing_to_release_ci`) so firing
+ * the label path twice is a clean no-op, and dispatch-chains
+ * release-guard.yml + publish-npm.yml + cloud-release.yml after the
+ * release (a bot-pushed tag does not trigger them — GitHub's GITHUB_TOKEN
+ * recursion guard). The bump
+ * level (major/minor/patch) is auto-detected from Conventional Commits
+ * since the last tag; pass `--as {major,minor,patch}` to force, or
+ * `--version X.Y.Z` to pin.
  *
  * Pipeline:
  *     1. Preflight         — on main, clean tree, origin in sync, gh available,
  *                            target tag doesn't exist yet.
  *     2. Plan              — compute new version, parse Conventional Commits
  *                            since the last tag, render CHANGELOG section.
- *     3. Confirm           — show preview, ask once (skippable with --yes).
+ *     3. Confirm           — show preview, ask once (skippable with --yes;
+ *                            `--ci` always needs --yes — CI has no terminal).
  *     4. Branch + bump     — create `release/X.Y.Z`, update package.json,
  *                            .claude-plugin/marketplace.json, CHANGELOG.md,
  *                            then run `task release-prepare` so pack
@@ -27,15 +38,22 @@
  *     5. Commit + push     — `release: X.Y.Z`, push branch, open PR.
  *     6. Wait for CI       — `gh pr checks --watch` (skippable with --no-wait).
  *     7. Merge             — `gh pr merge --merge --delete-branch`.
- *     8. Tag main          — fast-forward main, tag the merge commit,
- *                            push the tag (this triggers publish-npm.yml).
- *     9. GitHub Release     — `gh release create X.Y.Z --notes <changelog>`.
+ *     8. Tag main          — fast-forward main, tag the merge commit, push
+ *                            the tag (triggers publish-npm.yml — except
+ *                            under `--ci`, see step 9).
+ *     9. GitHub Release     — `gh release create X.Y.Z --notes <changelog>`;
+ *                            under `--ci`, also dispatches
+ *                            release-guard.yml + publish-npm.yml +
+ *                            cloud-release.yml explicitly.
  *
  * Idempotency: pass `--resume` to recover from a partial failure. Each
  * step then probes existing state (branch, commit, PR, tag, GitHub
  * Release) and skips work that is already done, instead of erroring out.
  * Without `--resume` the pipeline still mutates git/network state, so
- * re-running on a dirty tree needs `--resume` (or a manual cleanup).
+ * re-running on a dirty tree needs `--resume` (or a manual cleanup). The
+ * two entry points guard against colliding with each other via these same
+ * probes plus the CI workflow's concurrency group — whichever starts
+ * second sees the other's in-progress state and skips or refuses cleanly.
  * Each step prints what it's about to do before doing it, so a crash
  * leaves a recoverable trail.
  *
@@ -95,6 +113,7 @@ import type {
 import {
     CURRENT_ERA_BODY_CAP,
     current_era_accumulated_body_size,
+    current_era_body_size,
     current_era_insertion_point,
     perform_split,
     plan_split,
@@ -930,9 +949,13 @@ function set_template_pin(p: string, version: string): void {
  * Tree cleanliness, gh auth, and `main` in-sync with origin are still
  * enforced, so resuming has the same starting posture as a fresh run; only
  * step-level outcomes differ.
+ *
+ * `opts.ci` swaps the gh-auth probe (see below) for the CI-mode variant —
+ * everything else is identical between the two entry points.
  */
-function preflight(target: string, opts: { resume?: boolean } = {}): void {
+function preflight(target: string, opts: { resume?: boolean; ci?: boolean } = {}): void {
     const resume = opts.resume ?? false;
+    const ci = opts.ci ?? false;
     for (const b of ['git', 'gh']) {
         if (!have(b)) {
             die(`'${b}' not found on PATH`);
@@ -943,9 +966,22 @@ function preflight(target: string, opts: { resume?: boolean } = {}): void {
     // status` returns non-zero if *any* account in the keyring is broken, even
     // when the active one is fine — so we'd rather ask "does the token the
     // release will actually use work?" than parse multi-account status output.
-    const r = run(['gh', 'api', 'user', '--jq', '.login'], { check: false, capture: true });
+    //
+    // `--ci` runs under the GitHub Actions default GITHUB_TOKEN, which is an
+    // installation token, not a user token — `gh api user` returns 403
+    // ("Resource not accessible by integration") for it even when the token
+    // is perfectly valid for everything the release actually needs (repo
+    // read/write). Probe repo access instead, which the token always has.
+    const authCmd = ci
+        ? ['gh', 'api', `repos/${REPO_SLUG}`, '--jq', '.id']
+        : ['gh', 'api', 'user', '--jq', '.login'];
+    const r = run(authCmd, { check: false, capture: true });
     if (r.returncode !== 0) {
-        die('gh is not authenticated; run `gh auth login` first');
+        die(
+            ci
+                ? 'gh is not authenticated for this repo (GITHUB_TOKEN missing or invalid)'
+                : 'gh is not authenticated; run `gh auth login` first',
+        );
     }
 
     const branch = git(['rev-parse', '--abbrev-ref', 'HEAD'], { capture: true });
@@ -1159,11 +1195,12 @@ function _step(n: number, total: number, msg: string): void {
 
 function execute(
     plan: Plan,
-    opts: { wait_for_checks: boolean; dry_run: boolean; resume?: boolean },
+    opts: { wait_for_checks: boolean; dry_run: boolean; resume?: boolean; ci?: boolean },
 ): void {
     const wait_for_checks = opts.wait_for_checks;
     const dry_run = opts.dry_run;
     const resume = opts.resume ?? false;
+    const ci = opts.ci ?? false;
 
     const branch = `release/${plan.target}`;
     const total = 10;
@@ -1371,7 +1408,13 @@ function execute(
     if (_release_exists(plan.target)) {
         _step(9, total, `GitHub Release ${plan.target} already exists — skip`);
     } else {
-        _step(9, total, 'Create GitHub Release (triggers publish-npm on the tag)');
+        _step(
+            9,
+            total,
+            ci
+                ? 'Create GitHub Release (tag push under GITHUB_TOKEN triggers nothing — dispatching next)'
+                : 'Create GitHub Release (triggers publish-npm on the tag)',
+        );
         const notes = _cap_body(
             plan.changelog_body || `Release ${plan.target}`,
             GH_RELEASE_NOTES_LIMIT,
@@ -1387,6 +1430,23 @@ function execute(
             '--notes',
             notes,
         ]);
+
+        // ─── 9b. dispatch-chain the tag-triggered workflows (--ci only) ──────
+        // release-guard.yml, publish-npm.yml, and cloud-release.yml all
+        // trigger on `push: tags: [0-9]+.[0-9]+.[0-9]+`, but a tag pushed
+        // with the default GITHUB_TOKEN does NOT fire other workflows
+        // (GitHub's recursion guard). All three already accept a `tag`
+        // input for exactly this recovery case, so dispatch them
+        // explicitly instead of relying on an event that will never
+        // arrive. Only reached here (not in the `_release_exists` skip
+        // branch above), so a --resume re-run never re-dispatches a
+        // publish that already happened.
+        if (ci) {
+            _step(9, total, 'Dispatch release-guard.yml + publish-npm.yml + cloud-release.yml for the tag');
+            run(['gh', 'workflow', 'run', 'release-guard.yml', '--ref', MAIN_BRANCH, '-f', `tag=${plan.target}`]);
+            run(['gh', 'workflow', 'run', 'publish-npm.yml', '--ref', MAIN_BRANCH, '-f', `tag=${plan.target}`]);
+            run(['gh', 'workflow', 'run', 'cloud-release.yml', '--ref', MAIN_BRANCH, '-f', `tag=${plan.target}`]);
+        }
     }
 
     // ─── 10. delete the merged release branch (local + remote) ───────────────
@@ -1430,6 +1490,7 @@ interface Args {
     no_wait: boolean;
     resume: boolean;
     check_confirm: boolean;
+    ci: boolean;
 }
 
 const PROG = 'release.py';
@@ -1437,9 +1498,15 @@ const PROG = 'release.py';
 // (per-flag descriptions) is a documented divergence — argparse re-wraps it to
 // the live terminal width; the tests assert the `usage:` token + exit code,
 // not the body prose.
+//
+// `--ci` (added for the label-triggered GitHub Actions release path, see
+// `.github/workflows/release.yml`) is NOT part of the original argparse
+// contract this file mirrors byte-for-byte — it postdates the py2ts
+// migration (ADR-200) and has no Python counterpart. It is additive only:
+// every existing flag/behaviour is unchanged when `--ci` is absent.
 const USAGE =
     `usage: ${PROG} [-h] [--as {major,minor,patch}] [--version EXPLICIT] [--yes]\n` +
-    '                  [--dry-run] [--no-wait] [--resume] [--check-confirm]\n';
+    '                  [--dry-run] [--no-wait] [--resume] [--check-confirm] [--ci]\n';
 
 function _argError(msg: string): never {
     process.stderr.write(USAGE);
@@ -1456,6 +1523,7 @@ function _parse_args(argv: readonly string[]): Args {
         no_wait: false,
         resume: false,
         check_confirm: false,
+        ci: false,
     };
 
     const positionals: string[] = [];
@@ -1537,6 +1605,12 @@ function _parse_args(argv: readonly string[]): Args {
             i += 1;
             continue;
         }
+        if (flag === '--ci') {
+            if (inlineVal !== null) _argError(`argument --ci: ignored explicit argument '${inlineVal}'`);
+            args.ci = true;
+            i += 1;
+            continue;
+        }
         if (a.startsWith('-') && a !== '-') {
             _argError(`unrecognized arguments: ${a}`);
         }
@@ -1557,6 +1631,26 @@ function resolve_bump(override: string | null, commits: readonly Commit[]): stri
     return infer_bump(commits);
 }
 
+/**
+ * Should a `--ci` run stop early with no release? Empty commits + no
+ * explicit override + no bump override means `infer_bump` would fall back
+ * to a hollow 'patch' bump — fine for a deliberate interactive `task
+ * release`, but the label-triggered CI path (`.github/workflows/release.yml`)
+ * can fire on a merged `release`-labeled PR whose commits were already
+ * shipped by an earlier run in the same batch (the double-fire case). This
+ * is the guard that makes firing the CI path twice a clean no-op instead of
+ * a spurious empty release. The interactive path is unaffected — this only
+ * ever returns true when `ci` is true.
+ */
+export function nothing_to_release_ci(
+    ci: boolean,
+    explicit: string | null,
+    bump_override: string | null,
+    commits: readonly Commit[],
+): boolean {
+    return ci && explicit === null && bump_override === null && commits.length === 0;
+}
+
 const _RELEASE_BRANCH_RE = /^release\/(\d+\.\d+\.\d+)$/;
 
 /**
@@ -1613,6 +1707,64 @@ function _detect_in_flight_target(): string | null {
     return version;
 }
 
+/** Outcome of the release-time era-split gate (pure, unit-testable). */
+export interface SplitDecision {
+    split: SplitPlan | null;
+    die_message: string | null;
+    warning: string | null;
+}
+
+/**
+ * Decide whether releasing `target` must split the current era — measured
+ * against the POST-release state the drift test will see (the era's raw
+ * total today, because today's exempt newest section stops being exempt the
+ * moment the new release section is prepended).
+ *
+ * - post-release body over the cap + minor/major target → split.
+ * - post-release body over the cap + patch target:
+ *   - accumulated (prior releases beyond the newest) ALSO over the cap →
+ *     die — waiting cannot fix it; a minor release or manual split must
+ *     come first (pre-fix behaviour, unchanged).
+ *   - only the newest section busts the cap → proceed with a warning; a
+ *     patch cannot cross an era boundary, and blocking it was the failure
+ *     the newest-release exemption was introduced for. The drift gate will
+ *     be red until the next minor/major performs the split.
+ *
+ * Reads the CHANGELOG via the changelog_eras lib — tests point it at a
+ * fixture with `_set_changelog_path` (plan_split reads the same file).
+ */
+export function resolve_split_decision(target: string): SplitDecision {
+    const post_release_body = current_era_body_size();
+    if (post_release_body <= CURRENT_ERA_BODY_CAP) {
+        return { split: null, die_message: null, warning: null };
+    }
+    const candidate = plan_split(target);
+    if (candidate !== null) {
+        return { split: candidate, die_message: null, warning: null };
+    }
+    const accumulated = current_era_accumulated_body_size();
+    if (accumulated > CURRENT_ERA_BODY_CAP) {
+        return {
+            split: null,
+            die_message:
+                `current era body is ${accumulated} lines (cap ` +
+                `${CURRENT_ERA_BODY_CAP}) but release ${target} is a patch ` +
+                `within the same era — split needs a minor/major bump. ` +
+                'Cut a minor release or split CHANGELOG.md manually first.',
+            warning: null,
+        };
+    }
+    return {
+        split: null,
+        die_message: null,
+        warning:
+            `after this release the current era's accumulated body will be ` +
+            `${post_release_body} lines (cap ${CURRENT_ERA_BODY_CAP}); a patch ` +
+            `cannot split the era, so the changelog drift gate will be RED ` +
+            `until the next minor/major release performs the split.`,
+    };
+}
+
 function main(argv: readonly string[] | null = null): number {
     const args = _parse_args(argv === null ? process.argv.slice(2) : argv);
 
@@ -1649,6 +1801,14 @@ function main(argv: readonly string[] | null = null): number {
 
     const prev = latest_tag();
     const commits = commits_since(prev);
+
+    if (nothing_to_release_ci(args.ci, args.explicit, args.bump_override, commits)) {
+        process.stdout.write(
+            `nothing to release — no commits since ${prev ?? 'the start of history'}; exiting cleanly.\n`,
+        );
+        return 0;
+    }
+
     const bump = resolve_bump(args.bump_override, commits);
 
     // Resume mode: prefer an existing `release/X.Y.Z` over computed bump,
@@ -1669,7 +1829,7 @@ function main(argv: readonly string[] | null = null): number {
     parse_version(target);
 
     if (!args.dry_run) {
-        preflight(target, { resume: args.resume });
+        preflight(target, { resume: args.resume, ci: args.ci });
     }
 
     const today = todayIso();
@@ -1678,30 +1838,33 @@ function main(argv: readonly string[] | null = null): number {
         test_trend_line,
     });
 
-    // Era-split planning: only crosses the gate when the current era's
-    // *accumulated* body (prior releases, excluding the newest section) has
-    // grown past the drift cap AND the release crosses a minor/major boundary.
-    // The newest release is exempt — a single large catch-up release forces
-    // the split on the *next* minor/major once it has become a prior entry,
-    // not on the patch that immediately follows it. This is the same quantity
-    // the drift test enforces (current_era_accumulated_body_size); measuring
-    // the raw total here would re-fire the gate the exemption exists to clear.
-    // Patch overflow that genuinely accumulates is caught by the drift test
-    // (red CI), not by an auto-split into a nonsensical "pre-X.Y.Z" archive.
-    let split: SplitPlan | null = null;
-    const body_size = current_era_accumulated_body_size();
-    if (body_size > CURRENT_ERA_BODY_CAP) {
-        const candidate = plan_split(target);
-        if (candidate === null) {
-            die(
-                `current era body is ${body_size} lines (cap ` +
-                    `${CURRENT_ERA_BODY_CAP}) but release ${target} is a patch ` +
-                    `within the same era — split needs a minor/major bump. ` +
-                    'Cut a minor release or split CHANGELOG.md manually first.',
-            );
-        }
-        split = candidate;
-    }
+    // Era-split planning — gate on the POST-release view (2026-07-07 fix).
+    // The drift test measures the era AFTER this release's section is
+    // prepended: the new section becomes the exempt "newest", so everything
+    // currently in the era — INCLUDING today's still-exempt newest section —
+    // counts as accumulated the moment this release lands. That future
+    // quantity equals today's raw era total (current_era_body_size). The old
+    // gate measured current_era_accumulated_body_size (pre-release snapshot),
+    // which is ~0 right after a big catch-up release — so the 8.0.0 and 8.1.0
+    // releases each skipped the split and left main red on the drift gate
+    // until a manual chore split. Same function as the drift test, wrong
+    // moment in time.
+    //
+    // The newest-release exemption is still honoured where it matters: a
+    // PATCH release cannot cross an era boundary, so when only the newest
+    // section busts the cap (accumulated still under it) the patch proceeds
+    // with a loud warning instead of dying — the split then fires on the
+    // next minor/major. A patch on top of a genuinely over-cap accumulated
+    // body still dies (unchanged), because that state is unfixable by
+    // waiting and needs a minor release or a manual split.
+    const decision = resolve_split_decision(target);
+    if (decision.die_message !== null) {
+        die(decision.die_message);
+    }
+    if (decision.warning !== null) {
+        process.stderr.write(`warning: ${decision.warning}\n`);
+    }
+    const split: SplitPlan | null = decision.split;
 
     const plan = new Plan(current, target, bump, commits, prev, body, full, split);
     print_preview(plan);
@@ -1726,16 +1889,36 @@ function main(argv: readonly string[] | null = null): number {
         wait_for_checks: !args.no_wait,
         dry_run: false,
         resume: args.resume,
+        ci: args.ci,
     });
     return 0;
 }
 
 // ─── CLI entry (release.py:1090-1091 `raise SystemExit(main())`) ──────────────
 
-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 {
         // main() can return an int directly OR throw SystemExitError via die();
         // both flow into process.exitCode. CalledProcessError is intentionally

package/src/scripts/render_benchmark_composite.ts

@@ -370,9 +370,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/render_benchmark_md.ts

@@ -656,9 +656,28 @@ export function main(argv: string[] | null = null): number {
     return render(args.quiet);
 }
 
-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/roadmap_progress_hook.ts

@@ -289,24 +289,33 @@ function _isFile(p: string): boolean {
 /**
  * Resolve how to run the `.ts` regenerator: prefer the `tsx` binary from a
  * `node_modules/.bin` directory found by walking up from the regenerator's
- * directory; fall back to `npx tsx`. Mirrors
- * `dispatch_hook.ts::_resolve_tsx_invocation` so the regenerator runs as
- * TypeScript with no python3 dependency (the regenerator may live in a
- * consumer `.augment/scripts/` with the package's node_modules up the tree).
+ * directory, then from THIS module's own package tree; only then fall back
+ * to `npx tsx`. Mirrors `dispatch_hook.ts::_resolve_tsx_invocation` so the
+ * regenerator runs as TypeScript with no python3 dependency. The package-
+ * tree branch matters when the regenerator lives in a consumer
+ * `.augment/scripts/` whose tree carries no tsx — `npx tsx` there runs
+ * against the consumer's npm config and fails hard on e.g. devEngines pins
+ * (the 8.1.0 EBADDEVENGINES regression).
  */
 function _resolve_tsx_invocation(scriptPath: string): { command: string; args: string[] } {
   const binName = process.platform === "win32" ? "tsx.cmd" : "tsx";
-  let dir = path.dirname(scriptPath);
-  for (;;) {
-    const candidate = path.join(dir, "node_modules", ".bin", binName);
-    if (_isFile(candidate)) {
-      return { command: candidate, args: [scriptPath] };
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) {
-      break;
+  const walkUp = (start: string): string | null => {
+    let dir = start;
+    for (;;) {
+      const candidate = path.join(dir, "node_modules", ".bin", binName);
+      if (_isFile(candidate)) {
+        return candidate;
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) {
+        return null;
+      }
+      dir = parent;
     }
-    dir = parent;
+  };
+  const tsx = walkUp(path.dirname(scriptPath)) ?? walkUp(path.dirname(fileURLToPath(import.meta.url)));
+  if (tsx !== null) {
+    return { command: tsx, args: [scriptPath] };
   }
   return { command: "npx", args: ["tsx", scriptPath] };
 }
@@ -460,9 +469,30 @@ export function main(argv?: string[]): number {
   return run(_readStdin(), { consumer_root: root, 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/run_skill_evals.ts

@@ -507,9 +507,28 @@ function _runCli(): number {
     }
 }
 
-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(_runCli());
 }

package/src/scripts/runtime_dispatcher.ts

@@ -571,10 +571,29 @@ export function main(argv: string[]): number {
     return result.request.is_ready || result.request.status === 'blocked' ? 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) {
     try {
         process.exitCode = main(process.argv.slice(2));
     } catch (err) {