opencode2-direnv 2026.904.0

package/README.md

@@ -0,0 +1,126 @@
+<div align="center">
+
+# opencode2-direnv
+
+**Seamless direnv integration for OpenCode 2**
+
+[![npm version](https://img.shields.io/npm/v/opencode2-direnv?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/opencode2-direnv)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![direnv](https://img.shields.io/badge/direnv-compatible-FFC107?style=flat-square&logo=gnubash&logoColor=white)](https://direnv.net/)
+
+---
+
+*Automatically load [direnv](https://direnv.net/) environment variables into OpenCode 2 sessions — and keep them in sync while you work.*
+
+Fork of [`@simonwjackson/opencode-direnv`](https://github.com/simonwjackson/opencode-direnv), ported to the OpenCode 2 plugin API. OpenCode 1 users should use the original package.
+
+</div>
+
+---
+
+## Overview
+
+The plugin detects `.envrc` files and keeps the OpenCode server environment in sync with your devshell:
+
+- **Automatic Detection** — Searches for `.envrc` from the project directory up to the git root
+- **Shell Injection** — Injects the current direnv export into every shell OpenCode spawns (via the `shell.create.before` hook), so agent commands always see the devshell
+- **Live Reloading** — Re-applies the devshell when `.envrc`/`flake.nix`/`flake.lock` change (debounced) or a new session starts, and *removes* variables that are dropped
+- **Fallback Sync** — Also reconciles `process.env` so other subprocesses (LSP, MCP) inherit the devshell
+- **Graceful Degradation** — Silently skips if direnv is not installed or no `.envrc` exists; warns in the logs when a `.envrc` is blocked
+
+## Requirements
+
+- [OpenCode 2](https://opencode.ai/) (`opencode2`, beta)
+- [direnv](https://direnv.net/) >= 2.0 in PATH
+
+## Installation
+
+Add the plugin to your OpenCode 2 configuration (`plugins`, not the v1 `plugin` key):
+
+**Project-level** (`./opencode.json`):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["opencode2-direnv"]
+}
+```
+
+**Global** (`~/.config/opencode/opencode.json`):
+
+```json
+{
+  "plugins": ["opencode2-direnv"]
+}
+```
+
+Then allow your `.envrc` once:
+
+```bash
+direnv allow
+```
+
+## Usage
+
+Start `opencode2` in a project with an `.envrc`. Environment variables are loaded at startup, re-synced per session, and reloaded (debounced ~1.5s) when devshell files change. Outcomes are logged with a `direnv:` prefix:
+
+```
+direnv: environment loaded
+direnv: reloaded (+2 ~1)
+direnv: .envrc is blocked. Run `direnv allow` to enable.
+```
+
+### Local development
+
+Local plugins load from a directory containing an `index.ts` entrypoint:
+
+```json
+{
+  "plugins": ["/path/to/opencode-direnv"]
+}
+```
+
+The root `index.ts` re-exports `src/index.ts`, so edits are picked up on restart. Typecheck and build with:
+
+```bash
+npm ci
+npx tsc --noEmit
+npm run build
+```
+
+## How It Works
+
+```
+plugin setup ────▶ direnv export json ──▶ process.env reconcile
+      │                                        │
+      ├── shell.create.before hook ────────────┴─▶ every spawned shell gets the devshell
+      ├── session.created event ──▶ re-sync per session (e.g. after `direnv allow`)
+      └── filesystem.changed event (.envrc/flake.nix/flake.lock) ──▶ debounced reload
+```
+
+1. **Discovery** — Searches upward from the plugin's location directory, stopping at the git root
+2. **Export** — Runs `direnv export json` (fast when nothing changed; direnv's own watch caches it)
+3. **Reconcile** — Applies additions/changes and *removes* dropped keys; explicit direnv unsets (`null` values) are honored
+4. **Inject** — The `shell.create.before` hook copies the cached export into the environment of every shell spawned below the devshell directory
+
+## Troubleshooting
+
+```bash
+# Verify direnv is installed and .envrc is allowed
+which direnv && direnv status
+
+# Verify the export works in the project directory
+direnv export json
+```
+
+If the plugin does not activate, check the server logs (`opencode2 run --standalone --print-logs --log-level debug ...`) for `direnv:` lines or plugin load errors.
+
+## Limitations
+
+- Reloads are debounced (~1.5s); run `direnv reload` for an immediate refresh
+- `.envrc` must be explicitly allowed (`direnv allow`) — a blocked file is reported in the logs
+- A changed `use flake` re-evaluates in the background; the session is never blocked
+
+## License
+
+[MIT](LICENSE) — originally by [@simonwjackson](https://github.com/simonwjackson), ported to the OpenCode 2 plugin API by [@ankarhem](https://github.com/ankarhem).

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { Plugin } from "@opencode-ai/plugin";
+declare const _default: Plugin.Plugin;
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;;AAmE5C,wBAkRE"}

package/dist/index.js

@@ -0,0 +1,293 @@
+import { Plugin } from "@opencode-ai/plugin";
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+/**
+ * Direnv Auto-Loader Plugin for OpenCode 2
+ *
+ * Automatically loads AND keeps in sync environment variables from direnv.
+ * Shell commands run by the agent always see the current devshell state, even
+ * after the user edits .envrc/flake.nix or runs `direnv reload` mid-session.
+ *
+ * Behavior:
+ * - On plugin setup: load env once (awaited, so the first command is ready)
+ * - On session.created: re-sync per new session (e.g. after `direnv allow`)
+ * - On filesystem.changed for .envrc/flake.nix/flake.lock: debounced reload
+ * - Injects the latest direnv export into every spawned shell via the
+ *   `shell.create.before` hook (primary mechanism)
+ * - Reconciles process.env as a fallback for other subprocesses (LSP, MCP) and
+ *   *removes* dropped keys so removed variables don't linger
+ * - Logs outcomes with a `direnv:` prefix (blocked .envrc is always reported)
+ * - Silently skips if direnv is not installed or .envrc is missing
+ */
+const run = promisify(execFile);
+/** devshell files whose modification should trigger a reload */
+const RELEVANT_FILES = new Set([".envrc", "flake.nix", "flake.lock"]);
+/** debounce window for background reloads (ms) */
+const RELOAD_DEBOUNCE_MS = 1500;
+const runText = async (file, args, cwd) => {
+    const { stdout } = await run(file, args, {
+        cwd,
+        encoding: "utf8",
+        maxBuffer: 10 * 1024 * 1024,
+    });
+    return stdout;
+};
+export default Plugin.define({
+    id: "opencode2-direnv",
+    async setup(ctx) {
+        const directory = ctx.location.directory;
+        /**
+         * Sessions already synced by this plugin instance. Events arrive for every
+         * location, so also filter by event location where one is present.
+         */
+        const loadedSessions = new Set();
+        /**
+         * Keys we have written into process.env. Tracked globally (process.env is
+         * shared across locations in the server process) so reloads can remove vars
+         * that the devshell no longer exports without touching anything we didn't set.
+         */
+        const appliedKeys = new Set();
+        /** latest successful `direnv export json` payload, injected into spawned shells */
+        let currentVars = {};
+        /** cached .envrc location (only cached once successfully found) */
+        let envrcDir = null;
+        let discovered = false;
+        /** prevents overlapping `direnv export json` invocations */
+        let reloading = false;
+        let reloadTimer = null;
+        let firstLoadComplete = false;
+        const findGitRoot = async () => {
+            try {
+                const result = await runText("git", ["rev-parse", "--show-toplevel"], directory);
+                return result.trim() || null;
+            }
+            catch {
+                return null;
+            }
+        };
+        /**
+         * Find .envrc file searching from directory up to stopAt (git root or filesystem root)
+         */
+        const findEnvrc = async (startDir, stopAt) => {
+            let current = startDir;
+            const boundary = stopAt || "/";
+            while (true) {
+                if (existsSync(join(current, ".envrc"))) {
+                    return join(current, ".envrc");
+                }
+                if (current === boundary || current === "/") {
+                    break;
+                }
+                const parent = dirname(current);
+                if (parent === current) {
+                    break;
+                }
+                current = parent;
+            }
+            return null;
+        };
+        /**
+         * Resolve (and cache) the directory containing .envrc.
+         * Caches only on success; a missing .envrc is re-checked on later triggers
+         * so one created mid-session is eventually picked up.
+         */
+        const resolveEnvrcDir = async () => {
+            if (discovered)
+                return envrcDir;
+            const gitRoot = await findGitRoot();
+            const envrcPath = await findEnvrc(directory, gitRoot);
+            if (envrcPath) {
+                envrcDir = dirname(envrcPath);
+            }
+            discovered = envrcDir !== null;
+            return envrcDir;
+        };
+        const newOutcome = () => ({
+            blocked: false,
+            unavailable: false,
+            error: false,
+            added: 0,
+            changed: 0,
+            removed: 0,
+        });
+        /**
+         * Re-run `direnv export json` and reconcile process.env.
+         *
+         * Idempotent and mutex-guarded: safe to call from any trigger. Cheap when
+         * nothing changed (direnv's own watch cache makes the export ~milliseconds).
+         * Returns a summary describing what (if anything) changed.
+         */
+        const reloadEnv = async () => {
+            const outcome = newOutcome();
+            if (reloading)
+                return outcome;
+            reloading = true;
+            try {
+                const dir = await resolveEnvrcDir();
+                if (!dir) {
+                    outcome.unavailable = true;
+                    return outcome;
+                }
+                let jsonText;
+                try {
+                    jsonText = await runText("direnv", ["export", "json"], dir);
+                }
+                catch (error) {
+                    const stderr = error && typeof error === "object" && "stderr" in error
+                        ? String(error.stderr ?? "")
+                        : "";
+                    if (stderr.includes("is blocked")) {
+                        outcome.blocked = true;
+                    }
+                    else {
+                        outcome.error = true;
+                    }
+                    return outcome;
+                }
+                const parsed = jsonText.trim() ? JSON.parse(jsonText) : {};
+                const newVars = parsed && typeof parsed === "object" ? parsed : {};
+                // 1. Remove vars we previously applied that the devshell no longer exports.
+                //    direnv may also emit explicit `null` values to signal unsets.
+                for (const key of appliedKeys) {
+                    const keep = key in newVars && newVars[key] != null;
+                    if (!keep && key in process.env) {
+                        delete process.env[key];
+                        outcome.removed++;
+                    }
+                }
+                // 2. Apply current vars, counting additions and value changes.
+                const nextApplied = new Set();
+                for (const [key, value] of Object.entries(newVars)) {
+                    if (value == null)
+                        continue;
+                    const current = process.env[key];
+                    if (current === undefined)
+                        outcome.added++;
+                    else if (current !== value)
+                        outcome.changed++;
+                    process.env[key] = value;
+                    nextApplied.add(key);
+                }
+                appliedKeys.clear();
+                for (const key of nextApplied)
+                    appliedKeys.add(key);
+                currentVars = newVars;
+                return outcome;
+            }
+            catch {
+                outcome.error = true;
+                return outcome;
+            }
+            finally {
+                reloading = false;
+            }
+        };
+        /**
+         * Surface a reload result via logs.
+         *
+         * - blocked: always warn (action required by the user)
+         * - first load: confirm the environment was applied
+         * - subsequent: only log when something actually changed
+         * - no-op / unavailable / transient error: silent
+         */
+        const logOutcome = (outcome, opts) => {
+            if (outcome.blocked) {
+                console.warn("direnv: .envrc is blocked. Run `direnv allow` to enable.");
+                return;
+            }
+            if (outcome.unavailable || outcome.error)
+                return;
+            const total = outcome.added + outcome.changed + outcome.removed;
+            if (opts.initial && !firstLoadComplete) {
+                firstLoadComplete = true;
+                if (total > 0 || appliedKeys.size > 0) {
+                    console.log("direnv: environment loaded");
+                }
+                return;
+            }
+            if (total > 0) {
+                const parts = [];
+                if (outcome.added)
+                    parts.push(`+${outcome.added}`);
+                if (outcome.changed)
+                    parts.push(`~${outcome.changed}`);
+                if (outcome.removed)
+                    parts.push(`-${outcome.removed}`);
+                console.log(`direnv: reloaded (${parts.join(" ")})`);
+            }
+        };
+        /**
+         * Debounced background reload. Collapses rapid triggers (e.g. many file
+         * writes from an editor save) into a single reload.
+         */
+        const scheduleReload = (delayMs) => {
+            if (reloadTimer)
+                clearTimeout(reloadTimer);
+            reloadTimer = setTimeout(() => {
+                reloadTimer = null;
+                void reloadEnv().then((outcome) => logOutcome(outcome, { initial: false }));
+            }, delayMs);
+        };
+        // Initial load: awaited so the first command of any session sees the env.
+        logOutcome(await reloadEnv(), { initial: true });
+        // Primary mechanism: inject the latest direnv export into every shell the
+        // server spawns for a working copy inside the devshell. The cached payload
+        // keeps the hook synchronous and non-blocking.
+        const shellRegistration = await ctx.shell.hook("create.before", (event) => {
+            if (!envrcDir)
+                return;
+            if (event.cwd !== envrcDir && !event.cwd.startsWith(`${envrcDir}/`))
+                return;
+            for (const [key, value] of Object.entries(currentVars)) {
+                event.env[key] = value;
+            }
+        });
+        const isRelevantLocation = (location) => !location?.directory || location.directory === directory;
+        // Event stream: per-session sync and devshell-file watch. Runs detached so
+        // plugin setup is never blocked; aborted on cleanup.
+        const controller = new AbortController();
+        void (async () => {
+            try {
+                for await (const raw of ctx.event.subscribe({ signal: controller.signal })) {
+                    const event = raw;
+                    // Re-sync on new sessions (catches `direnv allow` and other state
+                    // changes that don't touch watched files).
+                    if (event.type === "session.created") {
+                        const data = event.data;
+                        const sessionID = data?.sessionID;
+                        if (!sessionID || !isRelevantLocation(event.location))
+                            continue;
+                        if (loadedSessions.has(sessionID))
+                            continue;
+                        loadedSessions.add(sessionID);
+                        const outcome = await reloadEnv();
+                        logOutcome(outcome, { initial: false });
+                        continue;
+                    }
+                    // Devshell file edited/created/deleted -> reload (debounced).
+                    if (event.type === "filesystem.changed") {
+                        const data = event.data;
+                        const filename = (data?.file ?? "").split("/").pop() ?? "";
+                        if (!isRelevantLocation(event.location))
+                            continue;
+                        if (RELEVANT_FILES.has(filename)) {
+                            scheduleReload(RELOAD_DEBOUNCE_MS);
+                        }
+                    }
+                }
+            }
+            catch {
+                // stream aborted on cleanup or failed; nothing to do
+            }
+        })();
+        return () => {
+            controller.abort();
+            if (reloadTimer)
+                clearTimeout(reloadTimer);
+            void shellRegistration.dispose();
+        };
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.js"

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "opencode2-direnv",
+  "version": "2026.0904.0",
+  "description": "OpenCode 2 plugin that automatically loads direnv environment variables",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "index.ts"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": [
+    "opencode",
+    "opencode2",
+    "direnv",
+    "plugin",
+    "nix",
+    "environment",
+    "env"
+  ],
+  "author": "ankarhem",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ankarhem/opencode-direnv.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ankarhem/opencode-direnv/issues"
+  },
+  "homepage": "https://github.com/ankarhem/opencode-direnv#readme",
+  "peerDependencies": {
+    "@opencode-ai/plugin": "beta"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^0.0.0-beta-19086",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,342 @@
+import { Plugin } from "@opencode-ai/plugin"
+import { execFile } from "node:child_process"
+import { existsSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { promisify } from "node:util"
+
+/**
+ * Direnv Auto-Loader Plugin for OpenCode 2
+ *
+ * Automatically loads AND keeps in sync environment variables from direnv.
+ * Shell commands run by the agent always see the current devshell state, even
+ * after the user edits .envrc/flake.nix or runs `direnv reload` mid-session.
+ *
+ * Behavior:
+ * - On plugin setup: load env once (awaited, so the first command is ready)
+ * - On session.created: re-sync per new session (e.g. after `direnv allow`)
+ * - On filesystem.changed for .envrc/flake.nix/flake.lock: debounced reload
+ * - Injects the latest direnv export into every spawned shell via the
+ *   `shell.create.before` hook (primary mechanism)
+ * - Reconciles process.env as a fallback for other subprocesses (LSP, MCP) and
+ *   *removes* dropped keys so removed variables don't linger
+ * - Logs outcomes with a `direnv:` prefix (blocked .envrc is always reported)
+ * - Silently skips if direnv is not installed or .envrc is missing
+ */
+
+const run = promisify(execFile)
+
+type ReloadOutcome = {
+  /** .envrc exists but is blocked (`direnv allow` needed) */
+  blocked: boolean
+  /** direnv not installed / no .envrc / discovery failed */
+  unavailable: boolean
+  /** a transient error occurred talking to direnv */
+  error: boolean
+  /** number of brand-new variables added to process.env */
+  added: number
+  /** number of existing variables whose value changed */
+  changed: number
+  /** number of previously-applied variables that were removed */
+  removed: number
+}
+
+/** Minimal shapes of the v2 server events this plugin reacts to */
+type EncodedEvent = {
+  readonly type: string
+  readonly data?: unknown
+  readonly location?: { readonly directory?: string } | undefined
+}
+
+type SessionCreatedData = { readonly sessionID?: string }
+type FilesystemChangedData = { readonly file?: string }
+
+/** devshell files whose modification should trigger a reload */
+const RELEVANT_FILES = new Set([".envrc", "flake.nix", "flake.lock"])
+
+/** debounce window for background reloads (ms) */
+const RELOAD_DEBOUNCE_MS = 1500
+
+const runText = async (file: string, args: string[], cwd: string) => {
+  const { stdout } = await run(file, args, {
+    cwd,
+    encoding: "utf8",
+    maxBuffer: 10 * 1024 * 1024,
+  })
+  return stdout
+}
+
+export default Plugin.define({
+  id: "opencode2-direnv",
+
+  async setup(ctx) {
+    const directory = ctx.location.directory
+
+    /**
+     * Sessions already synced by this plugin instance. Events arrive for every
+     * location, so also filter by event location where one is present.
+     */
+    const loadedSessions = new Set<string>()
+
+    /**
+     * Keys we have written into process.env. Tracked globally (process.env is
+     * shared across locations in the server process) so reloads can remove vars
+     * that the devshell no longer exports without touching anything we didn't set.
+     */
+    const appliedKeys = new Set<string>()
+
+    /** latest successful `direnv export json` payload, injected into spawned shells */
+    let currentVars: Record<string, string> = {}
+
+    /** cached .envrc location (only cached once successfully found) */
+    let envrcDir: string | null = null
+    let discovered = false
+
+    /** prevents overlapping `direnv export json` invocations */
+    let reloading = false
+
+    let reloadTimer: ReturnType<typeof setTimeout> | null = null
+    let firstLoadComplete = false
+
+    const findGitRoot = async (): Promise<string | null> => {
+      try {
+        const result = await runText("git", ["rev-parse", "--show-toplevel"], directory)
+        return result.trim() || null
+      } catch {
+        return null
+      }
+    }
+
+    /**
+     * Find .envrc file searching from directory up to stopAt (git root or filesystem root)
+     */
+    const findEnvrc = async (
+      startDir: string,
+      stopAt: string | null
+    ): Promise<string | null> => {
+      let current = startDir
+      const boundary = stopAt || "/"
+
+      while (true) {
+        if (existsSync(join(current, ".envrc"))) {
+          return join(current, ".envrc")
+        }
+
+        if (current === boundary || current === "/") {
+          break
+        }
+
+        const parent = dirname(current)
+        if (parent === current) {
+          break
+        }
+
+        current = parent
+      }
+
+      return null
+    }
+
+    /**
+     * Resolve (and cache) the directory containing .envrc.
+     * Caches only on success; a missing .envrc is re-checked on later triggers
+     * so one created mid-session is eventually picked up.
+     */
+    const resolveEnvrcDir = async (): Promise<string | null> => {
+      if (discovered) return envrcDir
+      const gitRoot = await findGitRoot()
+      const envrcPath = await findEnvrc(directory, gitRoot)
+      if (envrcPath) {
+        envrcDir = dirname(envrcPath)
+      }
+      discovered = envrcDir !== null
+      return envrcDir
+    }
+
+    const newOutcome = (): ReloadOutcome => ({
+      blocked: false,
+      unavailable: false,
+      error: false,
+      added: 0,
+      changed: 0,
+      removed: 0,
+    })
+
+    /**
+     * Re-run `direnv export json` and reconcile process.env.
+     *
+     * Idempotent and mutex-guarded: safe to call from any trigger. Cheap when
+     * nothing changed (direnv's own watch cache makes the export ~milliseconds).
+     * Returns a summary describing what (if anything) changed.
+     */
+    const reloadEnv = async (): Promise<ReloadOutcome> => {
+      const outcome = newOutcome()
+      if (reloading) return outcome
+      reloading = true
+
+      try {
+        const dir = await resolveEnvrcDir()
+        if (!dir) {
+          outcome.unavailable = true
+          return outcome
+        }
+
+        let jsonText: string
+        try {
+          jsonText = await runText("direnv", ["export", "json"], dir)
+        } catch (error: unknown) {
+          const stderr =
+            error && typeof error === "object" && "stderr" in error
+              ? String((error as { stderr?: string }).stderr ?? "")
+              : ""
+          if (stderr.includes("is blocked")) {
+            outcome.blocked = true
+          } else {
+            outcome.error = true
+          }
+          return outcome
+        }
+
+        const parsed = jsonText.trim() ? JSON.parse(jsonText) : {}
+        const newVars: Record<string, string> =
+          parsed && typeof parsed === "object" ? parsed : {}
+
+        // 1. Remove vars we previously applied that the devshell no longer exports.
+        //    direnv may also emit explicit `null` values to signal unsets.
+        for (const key of appliedKeys) {
+          const keep = key in newVars && newVars[key] != null
+          if (!keep && key in process.env) {
+            delete process.env[key]
+            outcome.removed++
+          }
+        }
+
+        // 2. Apply current vars, counting additions and value changes.
+        const nextApplied = new Set<string>()
+        for (const [key, value] of Object.entries(newVars)) {
+          if (value == null) continue
+          const current = process.env[key]
+          if (current === undefined) outcome.added++
+          else if (current !== value) outcome.changed++
+          process.env[key] = value
+          nextApplied.add(key)
+        }
+
+        appliedKeys.clear()
+        for (const key of nextApplied) appliedKeys.add(key)
+        currentVars = newVars
+
+        return outcome
+      } catch {
+        outcome.error = true
+        return outcome
+      } finally {
+        reloading = false
+      }
+    }
+
+    /**
+     * Surface a reload result via logs.
+     *
+     * - blocked: always warn (action required by the user)
+     * - first load: confirm the environment was applied
+     * - subsequent: only log when something actually changed
+     * - no-op / unavailable / transient error: silent
+     */
+    const logOutcome = (outcome: ReloadOutcome, opts: { initial: boolean }) => {
+      if (outcome.blocked) {
+        console.warn("direnv: .envrc is blocked. Run `direnv allow` to enable.")
+        return
+      }
+      if (outcome.unavailable || outcome.error) return
+
+      const total = outcome.added + outcome.changed + outcome.removed
+
+      if (opts.initial && !firstLoadComplete) {
+        firstLoadComplete = true
+        if (total > 0 || appliedKeys.size > 0) {
+          console.log("direnv: environment loaded")
+        }
+        return
+      }
+
+      if (total > 0) {
+        const parts: string[] = []
+        if (outcome.added) parts.push(`+${outcome.added}`)
+        if (outcome.changed) parts.push(`~${outcome.changed}`)
+        if (outcome.removed) parts.push(`-${outcome.removed}`)
+        console.log(`direnv: reloaded (${parts.join(" ")})`)
+      }
+    }
+
+    /**
+     * Debounced background reload. Collapses rapid triggers (e.g. many file
+     * writes from an editor save) into a single reload.
+     */
+    const scheduleReload = (delayMs: number) => {
+      if (reloadTimer) clearTimeout(reloadTimer)
+      reloadTimer = setTimeout(() => {
+        reloadTimer = null
+        void reloadEnv().then((outcome) => logOutcome(outcome, { initial: false }))
+      }, delayMs)
+    }
+
+    // Initial load: awaited so the first command of any session sees the env.
+    logOutcome(await reloadEnv(), { initial: true })
+
+    // Primary mechanism: inject the latest direnv export into every shell the
+    // server spawns for a working copy inside the devshell. The cached payload
+    // keeps the hook synchronous and non-blocking.
+    const shellRegistration = await ctx.shell.hook("create.before", (event) => {
+      if (!envrcDir) return
+      if (event.cwd !== envrcDir && !event.cwd.startsWith(`${envrcDir}/`)) return
+      for (const [key, value] of Object.entries(currentVars)) {
+        event.env[key] = value
+      }
+    })
+
+    const isRelevantLocation = (location: EncodedEvent["location"]) =>
+      !location?.directory || location.directory === directory
+
+    // Event stream: per-session sync and devshell-file watch. Runs detached so
+    // plugin setup is never blocked; aborted on cleanup.
+    const controller = new AbortController()
+    void (async () => {
+      try {
+        for await (const raw of ctx.event.subscribe({ signal: controller.signal })) {
+          const event = raw as unknown as EncodedEvent
+
+          // Re-sync on new sessions (catches `direnv allow` and other state
+          // changes that don't touch watched files).
+          if (event.type === "session.created") {
+            const data = event.data as SessionCreatedData | undefined
+            const sessionID = data?.sessionID
+            if (!sessionID || !isRelevantLocation(event.location)) continue
+            if (loadedSessions.has(sessionID)) continue
+            loadedSessions.add(sessionID)
+            const outcome = await reloadEnv()
+            logOutcome(outcome, { initial: false })
+            continue
+          }
+
+          // Devshell file edited/created/deleted -> reload (debounced).
+          if (event.type === "filesystem.changed") {
+            const data = event.data as FilesystemChangedData | undefined
+            const filename = (data?.file ?? "").split("/").pop() ?? ""
+            if (!isRelevantLocation(event.location)) continue
+            if (RELEVANT_FILES.has(filename)) {
+              scheduleReload(RELOAD_DEBOUNCE_MS)
+            }
+          }
+        }
+      } catch {
+        // stream aborted on cleanup or failed; nothing to do
+      }
+    })()
+
+    return () => {
+      controller.abort()
+      if (reloadTimer) clearTimeout(reloadTimer)
+      void shellRegistration.dispose()
+    }
+  },
+})