@code-yeongyu/senpi 2026.9.26 → 2026.9.27-2

package/dist/modes/interactive/runtime-notice-presenter.d.ts

@@ -0,0 +1,8 @@
+import { type BunRuntimeOptions } from "../../bun-runtime.ts";
+import type { NoticeSpec } from "../../core/extensions/notice/index.ts";
+import { type BunAvailability } from "./runtime-notice.ts";
+export declare const RUNTIME_NOTICE_STATE_FILE = "runtime-notice.json";
+export declare function readShownVersion(agentDir: string): string | undefined;
+export declare function detectBunAvailability(options: BunRuntimeOptions): BunAvailability;
+export declare function maybeShowRuntimeNotice(show: (spec: NoticeSpec) => void): void;
+//# sourceMappingURL=runtime-notice-presenter.d.ts.map

package/dist/modes/interactive/runtime-notice-presenter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-notice-presenter.d.ts","sourceRoot":"","sources":["../../../src/modes/interactive/runtime-notice-presenter.ts"],"names":[],"mappings":"AAEA,OAAO,EACN,KAAK,iBAAiB,EAItB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uCAAuC,CAAC;AAExE,OAAO,EACN,KAAK,eAAe,EAMpB,MAAM,qBAAqB,CAAC;AAE7B,eAAO,MAAM,yBAAyB,wBAAwB,CAAC;AAE/D,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUrE;AAYD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,iBAAiB,GAAG,eAAe,CAOjF;AAOD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,GAAG,IAAI,CAwB7E"}

package/dist/modes/interactive/runtime-notice-presenter.js

@@ -0,0 +1,69 @@
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { bunVersionSatisfies, findBunBinary, processBunRuntimeOptions, } from "../../bun-runtime.js";
+import { APP_COMMAND, APP_NAME, BRAND, detectInstallMethod, getAgentDir, PACKAGE_NAME, VERSION } from "../../config.js";
+import { envValue } from "../../core/brand.js";
+import { hasInheritedInspectorOption } from "../../inspector-policy.js";
+import { buildRuntimeNotice, reinstallTarget, runtimeNoticeSkipReason, runtimePinEnvName, SKIP_RUNTIME_NOTICE_ENV_SUFFIX, } from "./runtime-notice.js";
+export const RUNTIME_NOTICE_STATE_FILE = "runtime-notice.json";
+export function readShownVersion(agentDir) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(join(agentDir, RUNTIME_NOTICE_STATE_FILE), "utf8"));
+    }
+    catch {
+        // Missing or unreadable state means the notice was never recorded as shown.
+        return undefined;
+    }
+    if (typeof parsed !== "object" || parsed === null || !("shownVersion" in parsed))
+        return undefined;
+    return typeof parsed.shownVersion === "string" ? parsed.shownVersion : undefined;
+}
+function recordShownVersion(agentDir, version) {
+    try {
+        mkdirSync(agentDir, { recursive: true });
+        writeFileSync(join(agentDir, RUNTIME_NOTICE_STATE_FILE), `${JSON.stringify({ shownVersion: version })}\n`);
+    }
+    catch {
+        // Best effort: a read-only agent dir only means the notice shows again next launch,
+        // which must never fail the interactive startup that is already underway.
+    }
+}
+export function detectBunAvailability(options) {
+    const bunPath = findBunBinary(options);
+    if (bunPath === undefined)
+        return { kind: "missing" };
+    const version = options.bunVersion(bunPath);
+    return version !== undefined && bunVersionSatisfies(version)
+        ? { kind: "ready", version }
+        : { kind: "outdated", version };
+}
+function skipRequested() {
+    const value = envValue(SKIP_RUNTIME_NOTICE_ENV_SUFFIX);
+    return value !== undefined && value !== "" && value !== "0";
+}
+export function maybeShowRuntimeNotice(show) {
+    const agentDir = getAgentDir();
+    const skip = runtimeNoticeSkipReason({
+        versions: process.versions,
+        env: process.env,
+        hasInheritedInspectorOption: hasInheritedInspectorOption(),
+        skipRequested: skipRequested(),
+        engineVersion: VERSION,
+        shownVersion: readShownVersion(agentDir),
+    });
+    if (skip !== undefined)
+        return;
+    show(buildRuntimeNotice({
+        appName: APP_NAME,
+        appCommand: APP_COMMAND,
+        nodeVersion: process.version,
+        platform: process.platform,
+        installMethod: detectInstallMethod(),
+        target: reinstallTarget(BRAND, PACKAGE_NAME),
+        bun: detectBunAvailability(processBunRuntimeOptions(existsSync, realpathSync)),
+        pinEnvName: runtimePinEnvName(process.env),
+    }));
+    recordShownVersion(agentDir, VERSION);
+}
+//# sourceMappingURL=runtime-notice-presenter.js.map

package/dist/modes/interactive/runtime-notice-presenter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-notice-presenter.js","sourceRoot":"","sources":["../../../src/modes/interactive/runtime-notice-presenter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC3F,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAEN,mBAAmB,EACnB,aAAa,EACb,wBAAwB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AACxH,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C,OAAO,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,EAEN,kBAAkB,EAClB,eAAe,EACf,uBAAuB,EACvB,iBAAiB,EACjB,8BAA8B,GAC9B,MAAM,qBAAqB,CAAC;AAE7B,MAAM,CAAC,MAAM,yBAAyB,GAAG,qBAAqB,CAAC;AAE/D,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAChD,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACJ,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,yBAAyB,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IACtF,CAAC;IAAC,MAAM,CAAC;QACR,4EAA4E;QAC5E,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,CAAC,cAAc,IAAI,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IACnG,OAAO,OAAO,MAAM,CAAC,YAAY,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC;AAClF,CAAC;AAED,SAAS,kBAAkB,CAAC,QAAgB,EAAE,OAAe;IAC5D,IAAI,CAAC;QACJ,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzC,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,yBAAyB,CAAC,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;IAC5G,CAAC;IAAC,MAAM,CAAC;QACR,oFAAoF;QACpF,0EAA0E;IAC3E,CAAC;AACF,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,OAA0B;IAC/D,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACvC,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IACtD,MAAM,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAC5C,OAAO,OAAO,KAAK,SAAS,IAAI,mBAAmB,CAAC,OAAO,CAAC;QAC3D,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE;QAC5B,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;AAClC,CAAC;AAED,SAAS,aAAa;IACrB,MAAM,KAAK,GAAG,QAAQ,CAAC,8BAA8B,CAAC,CAAC;IACvD,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,IAAI,KAAK,KAAK,GAAG,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,IAAgC;IACtE,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;IAC/B,MAAM,IAAI,GAAG,uBAAuB,CAAC;QACpC,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,2BAA2B,EAAE,2BAA2B,EAAE;QAC1D,aAAa,EAAE,aAAa,EAAE;QAC9B,aAAa,EAAE,OAAO;QACtB,YAAY,EAAE,gBAAgB,CAAC,QAAQ,CAAC;KACxC,CAAC,CAAC;IACH,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO;IAC/B,IAAI,CACH,kBAAkB,CAAC;QAClB,OAAO,EAAE,QAAQ;QACjB,UAAU,EAAE,WAAW;QACvB,WAAW,EAAE,OAAO,CAAC,OAAO;QAC5B,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,aAAa,EAAE,mBAAmB,EAAE;QACpC,MAAM,EAAE,eAAe,CAAC,KAAK,EAAE,YAAY,CAAC;QAC5C,GAAG,EAAE,qBAAqB,CAAC,wBAAwB,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;QAC9E,UAAU,EAAE,iBAAiB,CAAC,OAAO,CAAC,GAAG,CAAC;KAC1C,CAAC,CACF,CAAC;IACF,kBAAkB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AACvC,CAAC","sourcesContent":["import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport {\n\ttype BunRuntimeOptions,\n\tbunVersionSatisfies,\n\tfindBunBinary,\n\tprocessBunRuntimeOptions,\n} from \"../../bun-runtime.ts\";\nimport { APP_COMMAND, APP_NAME, BRAND, detectInstallMethod, getAgentDir, PACKAGE_NAME, VERSION } from \"../../config.ts\";\nimport { envValue } from \"../../core/brand.ts\";\nimport type { NoticeSpec } from \"../../core/extensions/notice/index.ts\";\nimport { hasInheritedInspectorOption } from \"../../inspector-policy.ts\";\nimport {\n\ttype BunAvailability,\n\tbuildRuntimeNotice,\n\treinstallTarget,\n\truntimeNoticeSkipReason,\n\truntimePinEnvName,\n\tSKIP_RUNTIME_NOTICE_ENV_SUFFIX,\n} from \"./runtime-notice.ts\";\n\nexport const RUNTIME_NOTICE_STATE_FILE = \"runtime-notice.json\";\n\nexport function readShownVersion(agentDir: string): string | undefined {\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(readFileSync(join(agentDir, RUNTIME_NOTICE_STATE_FILE), \"utf8\"));\n\t} catch {\n\t\t// Missing or unreadable state means the notice was never recorded as shown.\n\t\treturn undefined;\n\t}\n\tif (typeof parsed !== \"object\" || parsed === null || !(\"shownVersion\" in parsed)) return undefined;\n\treturn typeof parsed.shownVersion === \"string\" ? parsed.shownVersion : undefined;\n}\n\nfunction recordShownVersion(agentDir: string, version: string): void {\n\ttry {\n\t\tmkdirSync(agentDir, { recursive: true });\n\t\twriteFileSync(join(agentDir, RUNTIME_NOTICE_STATE_FILE), `${JSON.stringify({ shownVersion: version })}\\n`);\n\t} catch {\n\t\t// Best effort: a read-only agent dir only means the notice shows again next launch,\n\t\t// which must never fail the interactive startup that is already underway.\n\t}\n}\n\nexport function detectBunAvailability(options: BunRuntimeOptions): BunAvailability {\n\tconst bunPath = findBunBinary(options);\n\tif (bunPath === undefined) return { kind: \"missing\" };\n\tconst version = options.bunVersion(bunPath);\n\treturn version !== undefined && bunVersionSatisfies(version)\n\t\t? { kind: \"ready\", version }\n\t\t: { kind: \"outdated\", version };\n}\n\nfunction skipRequested(): boolean {\n\tconst value = envValue(SKIP_RUNTIME_NOTICE_ENV_SUFFIX);\n\treturn value !== undefined && value !== \"\" && value !== \"0\";\n}\n\nexport function maybeShowRuntimeNotice(show: (spec: NoticeSpec) => void): void {\n\tconst agentDir = getAgentDir();\n\tconst skip = runtimeNoticeSkipReason({\n\t\tversions: process.versions,\n\t\tenv: process.env,\n\t\thasInheritedInspectorOption: hasInheritedInspectorOption(),\n\t\tskipRequested: skipRequested(),\n\t\tengineVersion: VERSION,\n\t\tshownVersion: readShownVersion(agentDir),\n\t});\n\tif (skip !== undefined) return;\n\tshow(\n\t\tbuildRuntimeNotice({\n\t\t\tappName: APP_NAME,\n\t\t\tappCommand: APP_COMMAND,\n\t\t\tnodeVersion: process.version,\n\t\t\tplatform: process.platform,\n\t\t\tinstallMethod: detectInstallMethod(),\n\t\t\ttarget: reinstallTarget(BRAND, PACKAGE_NAME),\n\t\t\tbun: detectBunAvailability(processBunRuntimeOptions(existsSync, realpathSync)),\n\t\t\tpinEnvName: runtimePinEnvName(process.env),\n\t\t}),\n\t);\n\trecordShownVersion(agentDir, VERSION);\n}\n"]}

package/dist/modes/interactive/runtime-notice.d.ts

@@ -0,0 +1,50 @@
+import type { InstallMethod } from "../../config.ts";
+import type { BrandProfile } from "../../core/brand.ts";
+import type { NoticeSpec } from "../../core/extensions/notice/index.ts";
+export declare const SKIP_RUNTIME_NOTICE_ENV_SUFFIX = "SKIP_RUNTIME_NOTICE";
+export type RuntimeNoticeSkip = "bun-runtime" | "node-pinned" | "inspector" | "skip-requested" | "already-shown";
+export interface RuntimeNoticeGate {
+    readonly versions: Readonly<Record<string, string | undefined>>;
+    readonly env: NodeJS.ProcessEnv;
+    readonly hasInheritedInspectorOption: boolean;
+    readonly skipRequested: boolean;
+    readonly engineVersion: string;
+    readonly shownVersion: string | undefined;
+}
+/**
+ * The variable that pins the runtime from the user's side. The OmO Native launcher always
+ * forwards its own runtime as `SENPI_RUNTIME`, so under OmO Native only `OMO_RUNTIME` is the
+ * user's choice; a forwarded `SENPI_RUNTIME=node` just means the launcher could not use Bun.
+ */
+export declare function runtimePinEnvName(env: NodeJS.ProcessEnv): string;
+export declare function runtimeNoticeSkipReason(gate: RuntimeNoticeGate): RuntimeNoticeSkip | undefined;
+export type BunAvailability = {
+    readonly kind: "missing";
+} | {
+    readonly kind: "outdated";
+    readonly version: string | undefined;
+} | {
+    readonly kind: "ready";
+    readonly version: string;
+};
+export interface ReinstallTarget {
+    readonly packageName: string;
+    readonly installSpec: string;
+    readonly ignoreScripts: boolean;
+}
+export declare function reinstallTarget(brand: BrandProfile | undefined, packageName: string): ReinstallTarget | undefined;
+/** Clean reinstall: remove the Node-managed copy so PATH cannot keep resolving it, then add it with Bun. */
+export declare function bunReinstallCommand(method: InstallMethod, target: ReinstallTarget): string;
+export declare function installBunCommand(platform: NodeJS.Platform): string;
+export interface RuntimeNoticeInput {
+    readonly appName: string;
+    readonly appCommand: string;
+    readonly nodeVersion: string;
+    readonly platform: NodeJS.Platform;
+    readonly installMethod: InstallMethod;
+    readonly target: ReinstallTarget | undefined;
+    readonly bun: BunAvailability;
+    readonly pinEnvName: string;
+}
+export declare function buildRuntimeNotice(input: RuntimeNoticeInput): NoticeSpec;
+//# sourceMappingURL=runtime-notice.d.ts.map

package/dist/modes/interactive/runtime-notice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-notice.d.ts","sourceRoot":"","sources":["../../../src/modes/interactive/runtime-notice.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAc,UAAU,EAAE,MAAM,uCAAuC,CAAC;AAEpF,eAAO,MAAM,8BAA8B,wBAAwB,CAAC;AAEpE,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,aAAa,GAAG,WAAW,GAAG,gBAAgB,GAAG,eAAe,CAAC;AAEjH,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAChE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,2BAA2B,EAAE,OAAO,CAAC;IAC9C,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAEhE;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,iBAAiB,GAAG,iBAAiB,GAAG,SAAS,CAO9F;AAED,MAAM,MAAM,eAAe,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GACnE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAExD,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CAChC;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,EAAE,WAAW,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAQjH;AAiBD,4GAA4G;AAC5G,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,eAAe,GAAG,MAAM,CAI1F;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,GAAG,MAAM,CAInE;AAED,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC5B;AAyBD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,GAAG,UAAU,CAaxE"}

package/dist/modes/interactive/runtime-notice.js

@@ -0,0 +1,104 @@
+/**
+ * The "running on Node.js" startup notice: when to show it and what it says.
+ *
+ * The only trigger is the runtime itself. Every install path that can run on Bun already
+ * re-execs there (`bun-runtime.ts` for senpi, the OmO Native launcher for omo), so a process
+ * still on Node here is one the user can fix: Bun is missing or too old, or the package was
+ * installed by a manager that keeps it on Node. Everything in this file is pure; the
+ * interactive mode supplies the facts through `runtime-notice-presenter.ts`.
+ */
+import { MIN_BUN_VERSION, RUNTIME_ENV_VAR } from "../../bun-runtime.js";
+export const SKIP_RUNTIME_NOTICE_ENV_SUFFIX = "SKIP_RUNTIME_NOTICE";
+/**
+ * The variable that pins the runtime from the user's side. The OmO Native launcher always
+ * forwards its own runtime as `SENPI_RUNTIME`, so under OmO Native only `OMO_RUNTIME` is the
+ * user's choice; a forwarded `SENPI_RUNTIME=node` just means the launcher could not use Bun.
+ */
+export function runtimePinEnvName(env) {
+    return env.OMO_NATIVE === "1" ? "OMO_RUNTIME" : RUNTIME_ENV_VAR;
+}
+export function runtimeNoticeSkipReason(gate) {
+    if (gate.versions.bun !== undefined)
+        return "bun-runtime";
+    if (gate.env[runtimePinEnvName(gate.env)] === "node")
+        return "node-pinned";
+    if (gate.hasInheritedInspectorOption)
+        return "inspector";
+    if (gate.skipRequested)
+        return "skip-requested";
+    if (gate.shownVersion === gate.engineVersion)
+        return "already-shown";
+    return undefined;
+}
+export function reinstallTarget(brand, packageName) {
+    if (brand === undefined)
+        return { packageName, installSpec: packageName, ignoreScripts: true };
+    const update = brand.update;
+    // A brand without an update channel manages its own installs; there is no command to offer.
+    if (update === undefined)
+        return undefined;
+    const installSpec = update.distTag === "latest" ? update.packageName : `${update.packageName}@${update.distTag}`;
+    // Branded products may rely on their install script; senpi documents --ignore-scripts.
+    return { packageName: update.packageName, installSpec, ignoreScripts: false };
+}
+function uninstallCommand(method, packageName) {
+    switch (method) {
+        case "npm":
+            return `npm uninstall -g ${packageName}`;
+        case "pnpm":
+            return `pnpm remove -g ${packageName}`;
+        case "yarn":
+            return `yarn global remove ${packageName}`;
+        case "bun":
+        case "bun-binary":
+        case "unknown":
+            return undefined;
+    }
+}
+/** Clean reinstall: remove the Node-managed copy so PATH cannot keep resolving it, then add it with Bun. */
+export function bunReinstallCommand(method, target) {
+    const install = `bun add -g ${target.ignoreScripts ? "--ignore-scripts " : ""}${target.installSpec}`;
+    const uninstall = uninstallCommand(method, target.packageName);
+    return uninstall === undefined ? install : `${uninstall} && ${install}`;
+}
+export function installBunCommand(platform) {
+    return platform === "win32"
+        ? `powershell -c "irm bun.sh/install.ps1 | iex"`
+        : "curl -fsSL https://bun.sh/install | bash";
+}
+function bunStep(input) {
+    switch (input.bun.kind) {
+        case "missing":
+            return { text: `Install Bun: ${installBunCommand(input.platform)}`, tone: "accent" };
+        case "outdated":
+            return {
+                text: `Upgrade Bun (found ${input.bun.version ?? "an unreadable version"}, needs ${MIN_BUN_VERSION}+): bun upgrade`,
+                tone: "accent",
+            };
+        case "ready":
+            return undefined;
+    }
+}
+function reinstallStep(input, afterBunStep) {
+    const lead = afterBunStep ? "Then reinstall" : "Reinstall";
+    // A Bun-global install needs no reinstall: a current Bun takes it over on the next launch.
+    if (input.installMethod === "bun" || input.target === undefined) {
+        return { text: `${afterBunStep ? "Then restart" : "Restart"} ${input.appCommand}.`, tone: "accent" };
+    }
+    return { text: `${lead} with Bun: ${bunReinstallCommand(input.installMethod, input.target)}`, tone: "accent" };
+}
+export function buildRuntimeNotice(input) {
+    const first = bunStep(input);
+    const extra = [
+        ...(first === undefined ? [] : [first]),
+        reinstallStep(input, first !== undefined),
+        { text: `To stay on Node.js and hide this notice, set ${input.pinEnvName}=node.` },
+    ];
+    return {
+        title: "Running on Node.js",
+        tone: "warning",
+        why: `${input.appName} is running on Node.js ${input.nodeVersion}. It starts faster and every feature works on Bun ${MIN_BUN_VERSION}+.`,
+        extra,
+    };
+}
+//# sourceMappingURL=runtime-notice.js.map

package/dist/modes/interactive/runtime-notice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-notice.js","sourceRoot":"","sources":["../../../src/modes/interactive/runtime-notice.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The \"running on Node.js\" startup notice: when to show it and what it says.\n *\n * The only trigger is the runtime itself. Every install path that can run on Bun already\n * re-execs there (`bun-runtime.ts` for senpi, the OmO Native launcher for omo), so a process\n * still on Node here is one the user can fix: Bun is missing or too old, or the package was\n * installed by a manager that keeps it on Node. Everything in this file is pure; the\n * interactive mode supplies the facts through `runtime-notice-presenter.ts`.\n */\nimport { MIN_BUN_VERSION, RUNTIME_ENV_VAR } from \"../../bun-runtime.ts\";\nimport type { InstallMethod } from \"../../config.ts\";\nimport type { BrandProfile } from \"../../core/brand.ts\";\nimport type { NoticeLine, NoticeSpec } from \"../../core/extensions/notice/index.ts\";\n\nexport const SKIP_RUNTIME_NOTICE_ENV_SUFFIX = \"SKIP_RUNTIME_NOTICE\";\n\nexport type RuntimeNoticeSkip = \"bun-runtime\" | \"node-pinned\" | \"inspector\" | \"skip-requested\" | \"already-shown\";\n\nexport interface RuntimeNoticeGate {\n\treadonly versions: Readonly<Record<string, string | undefined>>;\n\treadonly env: NodeJS.ProcessEnv;\n\treadonly hasInheritedInspectorOption: boolean;\n\treadonly skipRequested: boolean;\n\treadonly engineVersion: string;\n\treadonly shownVersion: string | undefined;\n}\n\n/**\n * The variable that pins the runtime from the user's side. The OmO Native launcher always\n * forwards its own runtime as `SENPI_RUNTIME`, so under OmO Native only `OMO_RUNTIME` is the\n * user's choice; a forwarded `SENPI_RUNTIME=node` just means the launcher could not use Bun.\n */\nexport function runtimePinEnvName(env: NodeJS.ProcessEnv): string {\n\treturn env.OMO_NATIVE === \"1\" ? \"OMO_RUNTIME\" : RUNTIME_ENV_VAR;\n}\n\nexport function runtimeNoticeSkipReason(gate: RuntimeNoticeGate): RuntimeNoticeSkip | undefined {\n\tif (gate.versions.bun !== undefined) return \"bun-runtime\";\n\tif (gate.env[runtimePinEnvName(gate.env)] === \"node\") return \"node-pinned\";\n\tif (gate.hasInheritedInspectorOption) return \"inspector\";\n\tif (gate.skipRequested) return \"skip-requested\";\n\tif (gate.shownVersion === gate.engineVersion) return \"already-shown\";\n\treturn undefined;\n}\n\nexport type BunAvailability =\n\t| { readonly kind: \"missing\" }\n\t| { readonly kind: \"outdated\"; readonly version: string | undefined }\n\t| { readonly kind: \"ready\"; readonly version: string };\n\nexport interface ReinstallTarget {\n\treadonly packageName: string;\n\treadonly installSpec: string;\n\treadonly ignoreScripts: boolean;\n}\n\nexport function reinstallTarget(brand: BrandProfile | undefined, packageName: string): ReinstallTarget | undefined {\n\tif (brand === undefined) return { packageName, installSpec: packageName, ignoreScripts: true };\n\tconst update = brand.update;\n\t// A brand without an update channel manages its own installs; there is no command to offer.\n\tif (update === undefined) return undefined;\n\tconst installSpec = update.distTag === \"latest\" ? update.packageName : `${update.packageName}@${update.distTag}`;\n\t// Branded products may rely on their install script; senpi documents --ignore-scripts.\n\treturn { packageName: update.packageName, installSpec, ignoreScripts: false };\n}\n\nfunction uninstallCommand(method: InstallMethod, packageName: string): string | undefined {\n\tswitch (method) {\n\t\tcase \"npm\":\n\t\t\treturn `npm uninstall -g ${packageName}`;\n\t\tcase \"pnpm\":\n\t\t\treturn `pnpm remove -g ${packageName}`;\n\t\tcase \"yarn\":\n\t\t\treturn `yarn global remove ${packageName}`;\n\t\tcase \"bun\":\n\t\tcase \"bun-binary\":\n\t\tcase \"unknown\":\n\t\t\treturn undefined;\n\t}\n}\n\n/** Clean reinstall: remove the Node-managed copy so PATH cannot keep resolving it, then add it with Bun. */\nexport function bunReinstallCommand(method: InstallMethod, target: ReinstallTarget): string {\n\tconst install = `bun add -g ${target.ignoreScripts ? \"--ignore-scripts \" : \"\"}${target.installSpec}`;\n\tconst uninstall = uninstallCommand(method, target.packageName);\n\treturn uninstall === undefined ? install : `${uninstall} && ${install}`;\n}\n\nexport function installBunCommand(platform: NodeJS.Platform): string {\n\treturn platform === \"win32\"\n\t\t? `powershell -c \"irm bun.sh/install.ps1 | iex\"`\n\t\t: \"curl -fsSL https://bun.sh/install | bash\";\n}\n\nexport interface RuntimeNoticeInput {\n\treadonly appName: string;\n\treadonly appCommand: string;\n\treadonly nodeVersion: string;\n\treadonly platform: NodeJS.Platform;\n\treadonly installMethod: InstallMethod;\n\treadonly target: ReinstallTarget | undefined;\n\treadonly bun: BunAvailability;\n\treadonly pinEnvName: string;\n}\n\nfunction bunStep(input: RuntimeNoticeInput): NoticeLine | undefined {\n\tswitch (input.bun.kind) {\n\t\tcase \"missing\":\n\t\t\treturn { text: `Install Bun: ${installBunCommand(input.platform)}`, tone: \"accent\" };\n\t\tcase \"outdated\":\n\t\t\treturn {\n\t\t\t\ttext: `Upgrade Bun (found ${input.bun.version ?? \"an unreadable version\"}, needs ${MIN_BUN_VERSION}+): bun upgrade`,\n\t\t\t\ttone: \"accent\",\n\t\t\t};\n\t\tcase \"ready\":\n\t\t\treturn undefined;\n\t}\n}\n\nfunction reinstallStep(input: RuntimeNoticeInput, afterBunStep: boolean): NoticeLine {\n\tconst lead = afterBunStep ? \"Then reinstall\" : \"Reinstall\";\n\t// A Bun-global install needs no reinstall: a current Bun takes it over on the next launch.\n\tif (input.installMethod === \"bun\" || input.target === undefined) {\n\t\treturn { text: `${afterBunStep ? \"Then restart\" : \"Restart\"} ${input.appCommand}.`, tone: \"accent\" };\n\t}\n\treturn { text: `${lead} with Bun: ${bunReinstallCommand(input.installMethod, input.target)}`, tone: \"accent\" };\n}\n\nexport function buildRuntimeNotice(input: RuntimeNoticeInput): NoticeSpec {\n\tconst first = bunStep(input);\n\tconst extra: NoticeLine[] = [\n\t\t...(first === undefined ? [] : [first]),\n\t\treinstallStep(input, first !== undefined),\n\t\t{ text: `To stay on Node.js and hide this notice, set ${input.pinEnvName}=node.` },\n\t];\n\treturn {\n\t\ttitle: \"Running on Node.js\",\n\t\ttone: \"warning\",\n\t\twhy: `${input.appName} is running on Node.js ${input.nodeVersion}. It starts faster and every feature works on Bun ${MIN_BUN_VERSION}+.`,\n\t\textra,\n\t};\n}\n"]}

package/docs/environment-variables.md

@@ -87,6 +87,8 @@ These variables are read by Pi itself:
 | `PI_PACKAGE_DIR` | Override the package directory, useful for Nix/Guix store paths |
 | `PI_OFFLINE` | Disable startup network operations, including update checks, package updates, and install/update telemetry |
 | `PI_SKIP_VERSION_CHECK` | Disable the `pi.dev` latest-version request |
+| `SENPI_RUNTIME` | `node` keeps senpi on Node.js and hides the Node.js runtime notice; `bun` re-execs under any installed Bun. Without it, a Bun-global install runs on its Bun and any other installed package runs on a discovered Bun 1.4.0 or newer |
+| `PI_SKIP_RUNTIME_NOTICE` | Hide the one-time "Running on Node.js" notice without changing the runtime |
 | `PI_TELEMETRY` | Override install/update telemetry and provider attribution headers: `1`/`true`/`yes` or `0`/`false`/`no` |
 | `PI_CACHE_RETENTION` | Set to `long` to opt into extended provider prompt caching where supported; direct Anthropic defaults to 5 minutes |
 | `PI_SHARE_VIEWER_URL` | Override the base URL used by `/share` |

package/docs/extensions.md

@@ -936,6 +936,17 @@ pi.on("thinking_level_select", async (event, ctx) => {
 
 Use this to update extension UI when `pi.setThinkingLevel()`, model changes, or built-in thinking-level controls change the active thinking level.
 
+#### tool_activated
+
+Fired after the active tool set gains tools. This covers `pi.setActiveTools()`, a `tool_search` promotion, and a by-name call that activates a deferred tool. The event is notification-only: handler return values are ignored.
+
+```typescript
+pi.on("tool_activated", async (event, ctx) => {
+  // event.toolNames - only the tools that just became active
+  if (event.toolNames.includes("my_tool")) await warmUp(ctx);
+});
+```
+
 ### Tool Events
 
 #### tool_call
@@ -1676,6 +1687,21 @@ Use `promptSnippet` to opt a custom tool into a one-line entry in `Available too
 
 **Important:** `promptGuidelines` bullets are appended flat to the `Guidelines` section with no tool name prefix. Each guideline must name the tool it refers to — avoid "Use this tool when..." because the LLM cannot tell which tool "this" means. Write "Use my_tool when..." instead.
 
+Use `kernelPrelude` to give the `eval` kernels globals that call your tool while it is active. It takes `javascript` and `python` statements, one `documentation` line for the eval prompt's helper list, and the `exports` those statements define. Each snippet runs before a cell only when one of its exports is missing, and a deactivated tool's exports are removed before the next cell. Exports must not shadow built-in kernel helpers such as `display` or `tool`.
+
+Use `permissionParser` to classify your tool's calls for the permission system. It receives the call input and the working directory and returns requests (`permission`, `patterns`, `always`), so a rule like `my_tool:read=allow` can grant one tier while another stays gated. Without it, every call is one request named after the tool. A built-in parser for the same tool name always wins.
+
+```typescript
+pi.registerTool({
+  name: "my_tool",
+  // ...
+  permissionParser: (input) => {
+    const tier = input.action === "add" ? "exec" : "read";
+    return [{ permission: "my_tool", patterns: [tier], always: [tier] }];
+  },
+});
+```
+
 See [dynamic-tools.ts](../examples/extensions/dynamic-tools.ts) for a full example.
 
 ```typescript
@@ -2126,7 +2152,7 @@ pi.setActiveTools([...new Set([...active, "my_custom_tool"])]); // Keep current
 pi.setActiveTools(["read", "bash"]); // Switch to read-only
 ```
 
-`pi.getAllTools()` returns `name`, `description`, `parameters`, `promptGuidelines`, and `sourceInfo`.
+`pi.getAllTools()` returns `name`, `description`, `parameters`, `promptGuidelines`, `kernelPrelude`, `permissionParser`, and `sourceInfo`.
 
 Typical `sourceInfo.source` values:
 - `builtin` for built-in tools

package/docs/quickstart.md

@@ -13,12 +13,18 @@ Senpi is distributed as an npm package:
 bun add -g @code-yeongyu/senpi
 ```
 
+Senpi runs on Bun whenever it can: a `bun add -g` install always does, and an npm, pnpm, or Yarn
+install hands itself to Bun 1.4.0 or newer when one is installed. If senpi still starts on Node.js
+(no Bun, or an older one), the interactive UI shows a "Running on Node.js" notice once per version
+with the commands to install or upgrade Bun and reinstall senpi with it. Set `SENPI_RUNTIME=node`
+to stay on Node.js without the notice.
+
 ### Uninstall
 
 Use the package manager that installed senpi:
 
 ```bash
-# bun add -g
+# npm
 npm uninstall -g @code-yeongyu/senpi
 
 # pnpm

package/docs/sessions.md

@@ -13,10 +13,19 @@ senpi --no-session        # Ephemeral mode; do not save
 senpi --name "my task"    # Set session display name at startup
 senpi --session <path|id> # Use a specific session file or partial session ID
 senpi --fork <path|id>    # Fork a session file or partial session ID into a new session
+senpi --rebind <path|id>  # Move a session of this repository, recorded at another path, here
 ```
 
 Use `/session` in interactive mode to see the current session file, session ID, message count, tokens, and cost.
 
+### Moved or re-cloned repositories
+
+Sessions are filed by the directory they started in. Each session also records which git repository that directory belonged to (its root commit and `origin` remote), so it can still be recognised after the repository moves.
+
+When `--session <id>` (or a pick in `--resume`) finds a session filed under another path and the current directory is the same git repository, senpi shows both paths and offers to move the session here. Answering `y` rebinds it: the session file moves to the current project, its recorded working directory is updated, and it keeps its id, history, goal, loops, and monitors. The old path no longer lists it. Use `--fork <id>` to copy it into a new session instead. A session from a different repository gets the fork prompt as before.
+
+`--rebind <path|id>` does the same without asking, for scripts. It refuses when the two directories are provably different repositories. Without an interactive terminal, `--session` never prompts: it prints the exact `--rebind` and `--fork` commands and exits with a non-zero status.
+
 For the JSONL file format and SessionManager API, see [Session Format](session-format.md).
 
 ## Session Commands

package/docs/usage.md

@@ -226,6 +226,7 @@ cat README.md | senpi -p "Summarize this text"
 | `-r`, `--resume` | Browse and select a session |
 | `--session <path\|id>` | Use a specific session file or partial UUID |
 | `--fork <path\|id>` | Fork a session file or partial UUID into a new session |
+| `--rebind <path\|id>` | Move a session of this repository, recorded at another path (moved or re-cloned), into this directory and continue it |
 | `--session-dir <dir>` | Custom session storage directory |
 | `--no-session` | Ephemeral mode; do not save |
 | `--name <name>`, `-n <name>` | Set session display name at startup |

package/node_modules/@code-yeongyu/senpi-codemode/CHANGELOG.md

@@ -12,6 +12,32 @@
 
 ### Removed
 
+## [2026.9.27-2] - 2026-09-27
+
+### Breaking Changes
+
+### Added
+
+- The eval kernels install each active tool's `kernelPrelude`: its JavaScript or Python statements run before a cell whenever one of the prelude's exports is missing, a deactivated tool's exports are removed before the next cell, and each prelude's documentation line joins the eval prompt's helper list. Exports that would shadow a built-in helper are rejected. ([#2178](https://github.com/code-yeongyu/senpi/pull/2178))
+
+### Changed
+
+### Fixed
+
+### Removed
+
+## [2026.9.27] - 2026-09-27
+
+### Breaking Changes
+
+### Added
+
+### Changed
+
+### Fixed
+
+### Removed
+
 ## [2026.9.26] - 2026-09-26
 
 ### Breaking Changes

package/node_modules/@code-yeongyu/senpi-codemode/README.md

@@ -162,6 +162,13 @@ into the cell carries the tool's expected parameters, so the cell can correct th
 arguments and retry instead of falling back to one-at-a-time tool calls.
 `tool_schema()` exposes the same catalog up front.
 
+A tool may also contribute globals of its own through `ToolDefinition.kernelPrelude`
+(JavaScript and Python snippets that call the ordinary `tool.<name>()`, one
+documentation line, and the exported names). While the tool is active, each
+JavaScript and Python cell installs any missing export first and the eval prompt
+lists the documentation line; once the tool is deactivated, the next cell deletes
+those names. Exports that shadow a built-in helper are rejected by the host.
+
 `agent()` is available only when the configured task tool is active in the
 session. `output()` similarly requires the configured task-output tool and
 returns immediately: a running task reports its current status, while completed

package/node_modules/@code-yeongyu/senpi-codemode/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/senpi-codemode",
-	"version": "2026.9.26",
+	"version": "2026.9.27-2",
 	"private": true,
 	"description": "Source-only senpi extension package for codemode evaluation tools",
 	"type": "module",
@@ -31,14 +31,14 @@
 	},
 	"dependencies": {
 		"@babel/parser": "8.0.4",
-		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.9.26",
+		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.9.27-2",
 		"typebox": "1.3.34"
 	},
 	"peerDependencies": {
-		"@code-yeongyu/senpi": "2026.9.26"
+		"@code-yeongyu/senpi": "2026.9.27-2"
 	},
 	"devDependencies": {
-		"@code-yeongyu/senpi": "2026.9.26"
+		"@code-yeongyu/senpi": "2026.9.27-2"
 	},
 	"keywords": [
 		"senpi",

package/node_modules/@code-yeongyu/senpi-codemode/src/bridge/protocol.ts

@@ -37,6 +37,15 @@ const hostToKernelMessageSchema = Type.Union([
 		cellId: Type.String({ minLength: 1 }),
 		code: Type.String(),
 		timeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
+		/** Python only: active tool globals to install before the cell and deactivated ones to remove. */
+		preludes: Type.Optional(
+			Type.Object({
+				install: Type.Array(
+					Type.Object({ exports: Type.Array(Type.String({ minLength: 1 })), python: Type.String() }),
+				),
+				remove: Type.Array(Type.String({ minLength: 1 })),
+			}),
+		),
 	}),
 	Type.Object({
 		type: Type.Literal("tool-reply"),

package/node_modules/@code-yeongyu/senpi-codemode/src/bridges/schema-bridge.ts

@@ -1,3 +1,4 @@
+import type { KernelPreludeContribution } from "@code-yeongyu/senpi";
 import { type Static, Type } from "typebox";
 import { Check, Errors } from "typebox/value";
 
@@ -12,6 +13,7 @@ export interface EvalSchemaToolInfo {
 	readonly name: string;
 	readonly description?: string | undefined;
 	readonly parameters?: unknown;
+	readonly kernelPrelude?: KernelPreludeContribution | undefined;
 }
 
 export interface RunEvalSchemaOptions {

package/node_modules/@code-yeongyu/senpi-codemode/src/extension/kernel-preludes.ts

@@ -0,0 +1,30 @@
+import type { KernelPreludeContribution } from "@code-yeongyu/senpi";
+import type { CodemodeRuntimeAPI } from "./runtime-factory.ts";
+
+type ToolRegistry = Pick<CodemodeRuntimeAPI, "getActiveTools" | "getAllTools">;
+
+/**
+ * Kernel globals of the tools active right now. Read per cell, so a tool activated by `tool_search`, a by-name
+ * call, or a command shows up in the next cell and a deactivated one disappears, whatever the registration order.
+ */
+export function activeKernelPreludes(pi: ToolRegistry): readonly KernelPreludeContribution[] {
+	const active = new Set(pi.getActiveTools());
+	return pi.getAllTools().flatMap((tool) => (tool.kernelPrelude && active.has(tool.name) ? [tool.kernelPrelude] : []));
+}
+
+/** Identity of the prompt's contribution doc lines; the eval tool re-registers only when it changes. */
+export function kernelPreludeDocsKey(preludes: readonly KernelPreludeContribution[]): string {
+	return preludes.map((prelude) => prelude.documentation).join("\n");
+}
+
+/**
+ * The contributions the eval description documents. Like the monitor probe, an unreadable registry (the loader's
+ * action methods throw until the runtime binds) teaches nothing; the per-cell read still surfaces any error.
+ */
+export function promptKernelPreludes(pi: ToolRegistry): readonly KernelPreludeContribution[] {
+	try {
+		return activeKernelPreludes(pi);
+	} catch {
+		return [];
+	}
+}

package/node_modules/@code-yeongyu/senpi-codemode/src/index.ts

@@ -13,6 +13,7 @@ import {
 import { EvalNotifier } from "./extension/eval-notifier.ts";
 import { EVAL_CELLS_STATUS_KEY } from "./extension/eval-status.ts";
 import { EvalStatusTicker } from "./extension/eval-status-ticker.ts";
+import { activeKernelPreludes, kernelPreludeDocsKey, promptKernelPreludes } from "./extension/kernel-preludes.ts";
 import {
 	createExecuteTool,
 	createRuntime,
@@ -43,7 +44,7 @@ const SESSION_LIFECYCLE_EVENTS = [
 
 type SessionLifecycleEvent = (typeof SESSION_LIFECYCLE_EVENTS)[number];
 
-type CodemodeEvent = SessionLifecycleEvent | "model_select";
+type CodemodeEvent = SessionLifecycleEvent | "model_select" | "turn_start";
 
 export interface CodemodeExtensionAPI {
 	registerTool(tool: ReturnType<typeof createEvalTool>): void;
@@ -91,6 +92,7 @@ export default function senpiCodemode(pi: CodemodeExtensionAPI, options: SenpiCo
 	let activeModelId: string | undefined;
 	let activeContext: ExtensionContext | undefined;
 	let activeCells: EvalDetachedCellManager | undefined;
+	let promptPreludeDocs = "";
 	const notifier = new EvalNotifier({
 		sendMessage: (message, notifyOptions) => pi.sendMessage(message, notifyOptions),
 		getContext: () => activeContext,
@@ -134,6 +136,8 @@ export default function senpiCodemode(pi: CodemodeExtensionAPI, options: SenpiCo
 		// reaches this before the runtime is bound). An unreadable registry means "do not teach
 		// a tool we cannot confirm"; session_start / model_select re-register once it is live.
 		const monitor = monitorIsRegistered(pi);
+		const preludes = promptKernelPreludes(pi);
+		promptPreludeDocs = kernelPreludeDocsKey(preludes);
 		pi.registerTool(
 			createEvalTool({
 				enabledLanguages: runtime.enabledLanguages,
@@ -156,6 +160,8 @@ export default function senpiCodemode(pi: CodemodeExtensionAPI, options: SenpiCo
 				spawnDefaultAgent: runtime.settings.taskTools.task,
 				hostLine: hostLine(),
 				runtimes: runtime.runtimes,
+				kernelPreludes: () => activeKernelPreludes(pi),
+				promptKernelPreludes: preludes,
 				...(bunSkillPath === undefined ? {} : { bunSkillPath }),
 				...(modelId === undefined ? {} : { modelId }),
 			}),
@@ -252,6 +258,14 @@ export default function senpiCodemode(pi: CodemodeExtensionAPI, options: SenpiCo
 		if (cellManager === undefined) return;
 		registerEvalForRuntime(runtime, modelId, cellManager);
 	});
+	// Tool activation has no event of its own; the next turn re-documents a changed contribution set.
+	pi.on("turn_start", async () => {
+		const runtime = activeRuntime;
+		const cellManager = activeCells;
+		if (runtime === undefined || cellManager === undefined) return;
+		if (kernelPreludeDocsKey(promptKernelPreludes(pi)) === promptPreludeDocs) return;
+		registerEvalForRuntime(runtime, activeModelId, cellManager);
+	});
 }
 
 function hostLine(): string {

package/node_modules/@code-yeongyu/senpi-codemode/src/kernels/js/context-manager.ts

@@ -195,7 +195,7 @@ export class JavaScriptKernel {
 		this.#slot.postMessage({
 			type: "run",
 			cellId: next.input.cellId,
-			code: this.#moduleLoader.prepareCell(next.input.code),
+			code: this.#moduleLoader.prepareCell(next.input.code, next.input.kernelPreludes),
 			timeoutMs: next.input.timeoutMs,
 		});
 	}

package/node_modules/@code-yeongyu/senpi-codemode/src/kernels/js/local-module-loader.ts

@@ -1,5 +1,6 @@
 import { join, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
+import type { KernelPreludeContribution } from "@code-yeongyu/senpi";
 import type { BridgeConnectionConfig } from "../../bridge/protocol.ts";
 import {
 	RESERVED_AGENT_TOOL,
@@ -8,6 +9,7 @@ import {
 	TIMEOUT_PAUSE_OP,
 	TIMEOUT_RESUME_OP,
 } from "../../bridge/reserved.ts";
+import { type KernelPreludePlan, KernelPreludeTracker } from "../shared/kernel-prelude-plan.ts";
 import type { JavaScriptKernelOptions as BaseJavaScriptKernelOptions } from "./kernel-contract.ts";
 import { rewriteImports } from "./rewrite-imports.ts";
 
@@ -99,14 +101,26 @@ function loaderPrelude(context: RuntimeModuleContext): string {
 	].join("\n");
 }
 
+/** Removes deactivated exports, then installs each contribution only while one of its exports is missing. */
+function contributionPrelude(plan: KernelPreludePlan): string {
+	const removals = plan.remove.map((name) => `delete globalThis[${JSON.stringify(name)}];`);
+	const installs = plan.install.map((contribution) => {
+		const missing = contribution.exports.map((name) => `!globalThis[${JSON.stringify(name)}]`).join(" || ");
+		return `if (${missing}) {\n${contribution.javascript}\n}`;
+	});
+	return [...removals, ...installs].join("\n");
+}
+
 export class LocalModuleLoader {
 	readonly #prelude: string;
+	readonly #contributions = new KernelPreludeTracker();
 
 	constructor(options: LocalModuleLoaderOptions) {
 		this.#prelude = loaderPrelude(runtimeContext(options));
 	}
 
-	prepareCell(code: string): string {
-		return `${PREPARED_CELL_PREFIX}${JSON.stringify({ prelude: this.#prelude, code: rewriteImports(code) })}`;
+	prepareCell(code: string, contributions: readonly KernelPreludeContribution[] = []): string {
+		const prelude = `${this.#prelude}\n${contributionPrelude(this.#contributions.plan(contributions))}`;
+		return `${PREPARED_CELL_PREFIX}${JSON.stringify({ prelude, code: rewriteImports(code) })}`;
 	}
 }