@kontourai/flow-agents 1.0.0 → 1.1.0

package/.github/workflows/ci.yml

@@ -196,6 +196,55 @@ jobs:
         continue-on-error: true
         run: bash evals/ci/run-baseline.sh --check bundle-install-integration
 
+      - name: Bundle lifecycle integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check bundle-lifecycle-integration
+
+      - name: Activate npx context integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check activate-npx-context-integration
+
+      - name: Kit conformance levels integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check kit-conformance-levels-integration
+
+      - name: Local Flow Kit install integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check local-flow-kit-install-integration
+
+      - name: Flow Kit install-git integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check flow-kit-install-git-integration
+
+
+      - name: Context map integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check context-map-integration
+
+      - name: Effective backlog settings integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check effective-backlog-settings-integration
+
+      - name: Flow agents statusline integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check flow-agents-statusline-integration
+
+      - name: Telemetry contract integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check telemetry-contract-integration
+
+      - name: Telemetry doctor integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check telemetry-doctor-integration
+
+      - name: Utterance check integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check utterance-check-integration
+
+      - name: Pull work provider integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check pull-work-provider-integration
+
       - name: Finalize CI evidence
         if: always()
         run: bash evals/ci/run-baseline.sh --finalize
@@ -208,3 +257,64 @@ jobs:
           path: evals/results/ci-baseline/runtime-and-kit/
           if-no-files-found: warn
           retention-days: 14
+
+  usage-feedback:
+    name: Usage Feedback
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      FLOW_AGENTS_CI_LANE: usage-feedback
+      FLOW_AGENTS_CI_RESULTS_DIR: evals/results/ci-baseline/usage-feedback
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "22"
+
+      - name: Install Node dependencies
+        run: npm ci
+
+      - name: Install shell tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y jq ripgrep
+
+      - name: Initialize CI evidence
+        run: bash evals/ci/run-baseline.sh --init
+
+      - name: Usage feedback import integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check usage-feedback-import-integration
+
+      - name: Usage feedback outcomes integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check usage-feedback-outcomes-integration
+
+      - name: Usage feedback report integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check usage-feedback-report-integration
+
+      - name: Usage feedback dashboard integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check usage-feedback-dashboard-integration
+
+      - name: Usage feedback global integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check usage-feedback-global-integration
+
+      - name: Finalize CI evidence
+        if: always()
+        run: bash evals/ci/run-baseline.sh --finalize
+
+      - name: Upload CI evidence artifacts
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: flow-agents-ci-usage-feedback
+          path: evals/results/ci-baseline/usage-feedback/
+          if-no-files-found: warn
+          retention-days: 14

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [1.1.0](https://github.com/kontourai/flow-agents/compare/v1.0.1...v1.1.0) (2026-06-15)
+
+
+### Features
+
+* activate skills and docs in kit runtime adapters (fix [#58](https://github.com/kontourai/flow-agents/issues/58)) ([dc726fd](https://github.com/kontourai/flow-agents/commit/dc726fd1d56e79b5bda577985aa87befe3a1eb9d))
+* activate skills and docs in kit runtime adapters (fix [#58](https://github.com/kontourai/flow-agents/issues/58)) ([dc774e0](https://github.com/kontourai/flow-agents/commit/dc774e001b54f7a09f6ab81a6aafcf2ad8552b6d))
+
+
+### Fixes
+
+* apply realpathSync entry-guard to 7 remaining CLI/tool files ([c1b3272](https://github.com/kontourai/flow-agents/commit/c1b3272c623055662a63c5d11c6dbef5aabe1cf0))
+* apply realpathSync entry-guard to all 16 affected CLI/tool files (closes [#71](https://github.com/kontourai/flow-agents/issues/71)) ([8a676b0](https://github.com/kontourai/flow-agents/commit/8a676b0c9c91464d64755719ff778a13e298beb9))
+* apply realpathSync entry-guard to remaining 10 CLI/tool files ([159bb78](https://github.com/kontourai/flow-agents/commit/159bb785b6b28f99b0a3a5c95e0d4428512f4314))
+* use hosted console io preset ([5b4bb7b](https://github.com/kontourai/flow-agents/commit/5b4bb7bc86d154bcf4d529a62e398a2196b702cc))
+
+## [1.0.1](https://github.com/kontourai/flow-agents/compare/v1.0.0...v1.0.1) (2026-06-12)
+
+
+### Fixes
+
+* resolve three kit-distribution blockers ([#55](https://github.com/kontourai/flow-agents/issues/55) [#56](https://github.com/kontourai/flow-agents/issues/56) [#57](https://github.com/kontourai/flow-agents/issues/57)) ([3350cb1](https://github.com/kontourai/flow-agents/commit/3350cb15f44bff92d8d9c57f447761d0e1a1b20c))
+* resolve three kit-distribution blockers ([#55](https://github.com/kontourai/flow-agents/issues/55), [#56](https://github.com/kontourai/flow-agents/issues/56), [#57](https://github.com/kontourai/flow-agents/issues/57)) ([13bf732](https://github.com/kontourai/flow-agents/commit/13bf732ff365efa84423e9ea46042e501d202db8))
+
 ## [1.0.0](https://github.com/kontourai/flow-agents/compare/v0.4.0...v1.0.0) (2026-06-12)
 
 

package/build/src/cli/console-learning-projection.js

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 import { flagBool, flagString, parseArgs } from "../lib/args.js";
 import { buildWorkflowLearningProjection, readWorkflowLearningSources } from "../lib/workflow-learning-projection.js";
@@ -119,5 +120,21 @@ export function main(argv = process.argv.slice(2)) {
         return 1;
     }
 }
-if (import.meta.url === `file://${process.argv[1]}`)
-    process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1RealPath = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfRealPath === _argv1RealPath) {
+    process.exitCode = main();
+}

package/build/src/cli/effective-backlog-settings.js

@@ -98,5 +98,21 @@ export function main(argv = process.argv.slice(2)) {
         return 1;
     }
 }
-if (import.meta.url === `file://${process.argv[1]}`)
-    process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1RealPath = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfRealPath === _argv1RealPath) {
+    process.exitCode = main();
+}

package/build/src/cli/fixture-retirement-audit.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 const root = path.resolve(".");
 const fixtureRoot = "evals/fixtures";
@@ -136,5 +137,21 @@ export function main(argv = process.argv.slice(2)) {
         return 1;
     }
 }
-if (import.meta.url === `file://${process.argv[1]}`)
-    process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1RealPath = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfRealPath === _argv1RealPath) {
+    process.exitCode = main();
+}

package/build/src/cli/flow-kit.js

@@ -1,6 +1,9 @@
+import * as child_process from "node:child_process";
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 import { parseArgs, flagBool, flagString } from "../lib/args.js";
 import { assertPathContained, copyDir, isoNow, readJson, walkFiles, writeJson } from "../lib/fs.js";
 import { assertKitRepository, deriveKitTargets } from "../flow-kit/validate.js";
@@ -27,6 +30,22 @@ function contentHash(root) {
     }
     return `sha256:${hash.digest("hex")}`;
 }
+/** Content hash that excludes .git and other VCS/cache directories (for install-git clones). */
+function kitContentHash(root) {
+    const EXCLUDE_DIRS = new Set([".git", "__pycache__", ".pytest_cache"]);
+    const hash = crypto.createHash("sha256");
+    for (const file of walkFiles(root)) {
+        const parts = path.relative(root, file).split(path.sep);
+        if (parts.some((p) => EXCLUDE_DIRS.has(p)))
+            continue;
+        const rel = parts.join("/");
+        hash.update(rel);
+        hash.update("\0");
+        hash.update(fs.readFileSync(file));
+        hash.update("\0");
+    }
+    return `sha256:${hash.digest("hex")}`;
+}
 function installLocal(argv) {
     const args = parseArgs(argv);
     const source = path.resolve(args.positionals[0] ?? "");
@@ -36,13 +55,11 @@ function installLocal(argv) {
         manifest = assertKitRepository(source);
     }
     catch (error) {
-        console.log("warning: Flow validation surface unavailable; local kit check uses the minimal Flow Definition fallback");
         console.log("Flow Kit repository validation failed:");
         for (const diagnostic of (error.diagnostics ?? [error.message]))
             console.log(` - ${diagnostic}`);
         return 1;
     }
-    console.log("warning: Flow validation surface unavailable; local kit check uses the minimal Flow Definition fallback");
     const kitId = String(manifest.id);
     const hash = contentHash(source);
     const registry = loadRegistry(dest);
@@ -163,10 +180,107 @@ function inspect(argv) {
     console.log(JSON.stringify(result, null, 2));
     return result.conformance.k0 ? 0 : 1;
 }
+/**
+ * install-git <repo-url>[#ref] [--ref <branch|tag|sha>] [--dest <path>] [--force] [--update]
+ *
+ * Shallow-clones a remote git repository to a temporary directory, validates the kit
+ * container with the same logic used by install-local, then delegates to the existing
+ * install path. Supports an optional #ref fragment in the URL or a separate --ref flag.
+ *
+ * Implements kontourai/flow-agents#56 (git-ref install surface).
+ */
+function installGit(argv) {
+    const args = parseArgs(argv);
+    const rawUrl = args.positionals[0] ?? "";
+    if (!rawUrl) {
+        console.error("install-git: missing <repo-url> argument");
+        console.error("usage: flow-kit install-git <repo-url>[#ref] [--ref <branch|tag|sha>] [--dest <path>]");
+        return 2;
+    }
+    // Parse ref: #fragment in URL takes precedence over --ref flag.
+    let repoUrl = rawUrl;
+    let ref = null;
+    const hashIdx = rawUrl.indexOf("#");
+    if (hashIdx !== -1) {
+        repoUrl = rawUrl.slice(0, hashIdx);
+        ref = rawUrl.slice(hashIdx + 1) || null;
+    }
+    if (!ref)
+        ref = flagString(args.flags, "ref") ?? null;
+    const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
+    const force = flagBool(args.flags, "force") ?? false;
+    const update = flagBool(args.flags, "update") ?? false;
+    // Shallow-clone into a temporary directory.
+    const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), "flow-kit-git-"));
+    try {
+        const cloneArgs = ["clone", "--depth", "1"];
+        if (ref)
+            cloneArgs.push("--branch", ref);
+        cloneArgs.push("--", repoUrl, tmpBase);
+        try {
+            child_process.execFileSync("git", cloneArgs, { stdio: ["ignore", "pipe", "pipe"] });
+        }
+        catch (err) {
+            const msg = err instanceof Error && err.stderr
+                ? err.stderr.toString().trim()
+                : String(err);
+            console.error(`install-git: git clone failed: ${msg}`);
+            return 1;
+        }
+        // Validate the cloned kit using the same logic as install-local.
+        let manifest;
+        try {
+            manifest = assertKitRepository(tmpBase);
+        }
+        catch (error) {
+            console.log("Flow Kit repository validation failed:");
+            for (const diagnostic of (error.diagnostics ?? [error.message])) {
+                console.log(` - ${diagnostic}`);
+            }
+            return 1;
+        }
+        // Delegate to the shared install logic (copy + registry update).
+        const kitId = String(manifest.id);
+        const hash = kitContentHash(tmpBase);
+        const registry = loadRegistry(dest);
+        const existing = registry.kits.find((entry) => entry.id === kitId);
+        const target = installedPath(dest, kitId);
+        assertPathContained(dest, target);
+        const sourceText = repoUrl + (ref ? `#${ref}` : "");
+        if (existing && existing.source !== sourceText && !update) {
+            console.log(`conflict: kit '${kitId}' is already installed from ${existing.source}; rerun with --update to replace it`);
+            return 2;
+        }
+        if (existing && existing.source === sourceText && existing.hash === hash && fs.existsSync(target) && !force) {
+            console.log(`kit '${kitId}' is already installed from ${sourceText}`);
+            return 0;
+        }
+        copyDir(tmpBase, target);
+        const entry = {
+            id: kitId,
+            source: sourceText,
+            hash,
+            installed_at: existing && existing.source === sourceText && !update ? existing.installed_at : isoNow(),
+            installed_path: target,
+            state: "installed",
+        };
+        if (typeof manifest.version === "string" && manifest.version)
+            entry.version = manifest.version;
+        registry.kits = existing ? registry.kits.map((item) => item.id === kitId ? entry : item) : [...registry.kits, entry];
+        writeJson(registryPath(dest), registry);
+        console.log(`${existing ? "updated" : "installed"} git kit '${kitId}' from ${sourceText} at ${target}`);
+        return 0;
+    }
+    finally {
+        fs.rmSync(tmpBase, { recursive: true, force: true });
+    }
+}
 export function main(argv = process.argv.slice(2)) {
     const [command, ...rest] = argv;
     if (command === "install-local")
         return installLocal(rest);
+    if (command === "install-git")
+        return installGit(rest);
     if (command === "list")
         return list(rest);
     if (command === "status")
@@ -175,8 +289,24 @@ export function main(argv = process.argv.slice(2)) {
         return activate(rest);
     if (command === "inspect")
         return inspect(rest);
-    console.error("usage: flow-kit <install-local|list|status|activate|inspect> ...");
+    console.error("usage: flow-kit <install-local|install-git|list|status|activate|inspect> ...");
     return 2;
 }
-if (import.meta.url === `file://${process.argv[1]}`)
-    process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1RealPath = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfRealPath === _argv1RealPath) {
+    process.exitCode = main();
+}

package/build/src/cli/init.js

@@ -1,5 +1,6 @@
 import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import * as os from "node:os";
 import * as path from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -445,5 +446,21 @@ export async function mainDogfood(argv = process.argv.slice(2)) {
         return 2;
     }
 }
-if (import.meta.url === `file://${process.argv[1]}`)
-    process.exit(await main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1RealPath = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfRealPath === _argv1RealPath) {
+    process.exitCode = await main();
+}

package/build/src/cli/promote-workflow-artifact.js

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 import { parseArgs, flagString } from "../lib/args.js";
 import { isoNow, relPath } from "../lib/fs.js";
@@ -59,5 +60,21 @@ export function main(argv = process.argv.slice(2)) {
     console.log(`archived_artifact=${archive}`);
     return 0;
 }
-if (import.meta.url === `file://${process.argv[1]}`)
-    process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1RealPath = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfRealPath === _argv1RealPath) {
+    process.exitCode = main();
+}

package/build/src/cli/publish-change-helper.js

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 import { parseArgs, flagString } from "../lib/args.js";
 import { readJson } from "../lib/fs.js";
@@ -150,5 +151,21 @@ export function main(argv = process.argv.slice(2)) {
         return 1;
     }
 }
-if (import.meta.url === `file://${process.argv[1]}`)
-    process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1RealPath = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfRealPath === _argv1RealPath) {
+    process.exitCode = main();
+}

package/build/src/cli/pull-work-provider.js

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import { parseArgs, flagList, flagString } from "../lib/args.js";
 const FLOW_ARTIFACT_PATTERN = /(?<path>\.flow-agents\/[^\s`'")]+)/g;
 const GITHUB_ISSUE_PATTERN = /(?:(?<owner>[A-Za-z0-9_.-]+)\/(?<repo>[A-Za-z0-9_.-]+))?#(?<number>\d+)/g;
@@ -465,5 +466,21 @@ export function main(argv = process.argv.slice(2)) {
     console.log(JSON.stringify({ items }, null, 2));
     return 0;
 }
-if (import.meta.url === `file://${process.argv[1]}`)
-    process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1RealPath = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfRealPath === _argv1RealPath) {
+    process.exitCode = main();
+}

package/build/src/cli/runtime-adapter.js

@@ -1,3 +1,5 @@
+import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 import { parseArgs, flagString } from "../lib/args.js";
 import { activateCodexLocal, activateStrandsLocal } from "../runtime-adapters.js";
@@ -23,5 +25,21 @@ export function main(argv = process.argv.slice(2)) {
     console.log(JSON.stringify(result, null, 2));
     return Array.isArray(result.errors) && result.errors.length ? 1 : 0;
 }
-if (import.meta.url === `file://${process.argv[1]}`)
-    process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1RealPath = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfRealPath === _argv1RealPath) {
+    process.exitCode = main();
+}

package/build/src/cli/usage-feedback.js

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import * as os from "node:os";
 import * as path from "node:path";
 import { parseArgs, flagBool, flagList, flagString } from "../lib/args.js";
@@ -439,5 +440,21 @@ export function main(argv = process.argv.slice(2)) {
         return 1;
     }
 }
-if (import.meta.url === `file://${process.argv[1]}`)
-    process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1RealPath = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfRealPath === _argv1RealPath) {
+    process.exitCode = main();
+}

package/build/src/cli/utterance-check.js

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 import { flagBool, flagString, parseArgs } from "../lib/args.js";
 // ---------------------------------------------------------------------------
@@ -232,5 +233,21 @@ export async function main(argv = process.argv.slice(2)) {
     }
     return runCheck(rest);
 }
-if (import.meta.url === `file://${process.argv[1]}`)
-    process.exit(await main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1RealPath = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfRealPath === _argv1RealPath) {
+    process.exitCode = await main();
+}

package/build/src/cli/validate-hook-influence.js

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { fileURLToPath } from "node:url";
 const validTiers = new Set(["adapter", "design-target", "installed-command", "live-acceptance", "documented-runtime-gap"]);
 const validRuntimes = new Set(["codex", "claude-code", "kiro-cli"]);
 const validHooks = new Set(["workflow-steering", "stop-goal-fit"]);
@@ -148,5 +149,21 @@ export function main(argv = process.argv.slice(2)) {
         return 1;
     }
 }
-if (import.meta.url === `file://${process.argv[1]}`)
-    process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1RealPath = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfRealPath === _argv1RealPath) {
+    process.exitCode = main();
+}