@nanhara/hara 0.126.0 → 0.127.0

package/CHANGELOG.md

@@ -5,6 +5,43 @@ All notable changes to `@nanhara/hara`.
 > Versioning (pre-1.0, SemVer-style): the **minor** (middle) number bumps for a **new feature**; the
 > **patch** (last) number bumps for **optimizations/fixes of existing features**.
 
+## 0.127.0 — 2026-07-20 — structured context and typed task lifecycle
+
+- **Prompt assembly is now an explicit, ordered runtime layer.** Cache-stable policy, tool, project, and
+  session context are separated from turn-specific execution state and memory digests, deduplicated, and
+  assembled in a deterministic order. Anthropic requests preserve a stable cache prefix while other
+  providers continue to receive the same complete system contract.
+- **Conversation and execution state now travel on separate protocol planes.** Authenticated Serve clients
+  can negotiate the versioned `event.task_state` stream for running, waiting, paused, completed, and blocked
+  work, with stable task/turn identities, phases, accepted task briefs, checkpoints, approvals, outcomes,
+  restore snapshots, and explicit stop/finish transitions.
+- **Mid-turn input uses expected-turn steering.** `session.steer` durably accepts an update only for the
+  intended live turn, so Desktop and other clients can distinguish a real refinement from the next queued
+  task without parsing model prose or losing an end-of-turn race.
+- Ambient lifecycle events never include command or path previews, and resumed client history removes the
+  internal steering-triage wrapper before display. Detailed tool output remains confined to the explicit
+  conversation surface.
+- Upgrade with `npm i -g @nanhara/hara@0.127.0`.
+
+## 0.126.1 — 2026-07-19 — verified plugin packages and ownership-safe lifecycle
+
+- **Plugin packages now fail closed at staging.** Hara validates a bounded manifest schema, portable IDs and
+  relative paths, declared Skills/roles/binaries/panels, and MCP entry points before activation. Complete
+  package scans reject symbolic links, hard-linked or special files, protected credential-shaped files,
+  filesystem-boundary crossings, and excessive file/byte counts.
+- **Install, update, and removal have an ownership transaction.** A same-filesystem private staging directory
+  is atomically activated; command collisions never overwrite foreign entries; and a private receipt binds the
+  installed root device/inode, manifest digest, and exact command links. Update rollback preserves the previous
+  package and commands, while uninstall refuses a changed root, a foreign command replacement, or an older
+  unreceipted install. A legacy plugin remains usable; reinstalling it from the same reviewed source performs
+  the one-time receipt migration, after which later updates and removal use the verified ownership path.
+- **Plugin MCP processes are rooted in their installed package.** Relative executables and conventional
+  Node/Bun/Deno/Python entry scripts are verified and converted to absolute installed paths, and each server
+  receives the immutable plugin root as its working directory instead of the user's project.
+- Install warnings no longer echo manifest-provided MCP arguments or hook command bodies, which could contain
+  credentials. They still identify each executable surface so the package source can be reviewed before use.
+- Upgrade with `npm i -g @nanhara/hara@0.126.1`.
+
 ## 0.126.0 — 2026-07-19 — provider control plane, bounded tools, and honest execution time
 
 - **Desktop can configure providers through an authenticated, redacted Serve control plane.** The shared

package/README.md

@@ -238,7 +238,10 @@ and a near-duplicate is flagged so it updates instead of piling up. `assetCaptur
 **Plugins** — bundle skills + roles + MCP servers in one installable unit (Claude-Code-compatible
 `plugin.json` / `.claude-plugin/`). `hara plugin add file:<path> | github:<owner/repo> | git:<url>` installs it;
 `hara plugin` lists; `enable`/`disable`/`remove`. A plugin's skills/roles/MCP auto-contribute (your project &
-global override them). `.claude/agents/*.md` subagents load as roles too.
+global override them). Installation validates the full package in a private stage, activates it atomically,
+and records an owner-only receipt for the exact root and command links. Plugins installed before `0.126.1`
+remain usable; reinstall the same reviewed source once to create the receipt before removing them.
+`.claude/agents/*.md` subagents load as roles too.
 
 **Recall** — `hara recall --init` creates a personal `~/.hara/code-assets` library (snippets as `*.md`);
 `hara recall "<query>"` searches it **plus your skills** (one corpus), and `/recall <query>` pulls the best

package/SECURITY.md

@@ -74,9 +74,13 @@ local user (who already has your shell).
   permission and starts one named server only when a task needs it. Their inherited environment is still
   scrubbed, but the extension may use its own credentials or access anything its host process permits.
 - **Plugins are code you trust.** Installing a plugin (`hara plugin add`) grants its author code execution:
-  its MCP servers may run on first relevant use and its hooks may run around matching tool calls. `hara plugin
-  add` **prints the exact commands** a plugin can run so you can review them; disable with
-  `hara plugin disable <name>`.
+  its MCP servers may run on first relevant use and its hooks may run around matching tool calls. Installation
+  validates the complete package in a private same-filesystem stage, binds executable contributions to portable
+  package-relative paths, and records an owner-only root/manifest/command receipt before removal is allowed.
+  `hara plugin add` identifies each executable surface without echoing manifest-provided arguments or hook
+  bodies, which may contain credentials; review the package source itself, and disable it with
+  `hara plugin disable <name>`. Plugins installed before `0.126.1` remain usable; reinstalling one from the same
+  reviewed source creates the receipt required for later ownership-safe updates and removal.
 - **Coding-plan keys.** Provider keys you configure are used only to call the model endpoint you set.
 
 ## What is *not* a security boundary

package/dist/agent/loop.js

@@ -24,6 +24,7 @@ import { prepareHistoryForModel } from "./context-budget.js";
 import { rolesDigest } from "../org/roles.js";
 import { applyTaskBrief } from "../session/task.js";
 import { askUserTool } from "../tools/ask_user.js";
+import { PromptAssembler } from "./prompt.js";
 /** File tools whose `path` input marks the file as "recently worked with" (post-compaction restore). */
 const FILE_TOUCH_TOOLS = new Set(["read_file", "edit_file", "write_file"]);
 /** Engine-owned, non-authority helpers. Role filters still govern every deferred target activated by
@@ -61,8 +62,7 @@ export function needsConfirm(kind, mode) {
         return kind === "exec";
     return true; // suggest: confirm edits and exec
 }
-const HARA_SYSTEM = (cwd) => `You are hara, a coding agent running in the user's terminal.
-Working directory: ${cwd}
+const HARA_SYSTEM = () => `You are hara, a coding agent running in the user's terminal.
 Be concise and direct. Use the provided tools to read files, edit/write files, and run shell
 commands. Prefer small, verifiable steps; edit existing files with edit_file rather than rewriting
 them whole. Batch INDEPENDENT tool calls in a single response — especially reads (read_file / grep /
@@ -153,8 +153,9 @@ const CONTINUATION_SYSTEM = "# Existing-session continuity\n" +
     "re-inventory the workspace, or summarize files merely to understand what happened before. Follow the latest user request " +
     "and reuse prior conclusions and tool results. Inspect files only when the latest request requires it. If the working " +
     "directory is Home, ask the user to start Hara from a concrete project instead of enumerating Home or its children.";
-function composeSystem(cwd, projectContext, override, memory, continuationSession = false, executionContext, intake) {
-    const head = override ? `${override}\n\nWorking directory: ${cwd}` : HARA_SYSTEM(cwd);
+export function composeSystem(cwd, projectContext, override, memory, continuationSession = false, executionContext, intake) {
+    const assembler = new PromptAssembler();
+    assembler.add("core", "static", "core", override || HARA_SYSTEM());
     const skills = skillsDigest(cwd);
     const roles = override ? "" : rolesDigest(cwd);
     const intakeContext = !intake?.enabled
@@ -176,15 +177,17 @@ function composeSystem(cwd, projectContext, override, memory, continuationSessio
                 "the interpreted goal, intent, constraints, acceptance checks, and short steps. Use intent `answer` " +
                 "for a direct answer, `investigate` for evidence gathering/diagnosis, and `change` when the user asked " +
                 "you to modify or deliver something. Do not claim completion until the acceptance checks are verified.");
-    return (head +
-        gatewayNote() +
-        (continuationSession ? `\n\n${CONTINUATION_SYSTEM}` : "") +
-        (executionContext ? `\n\n${executionContext}` : "") +
-        intakeContext +
-        (projectContext ? `\n\n# Project context (AGENTS.md)\n${projectContext}` : "") +
-        (memory ? `\n\n# Memory (durable — facts/decisions/prefs you've saved; use memory_search/get for more)\n${memory}` : "") +
-        (roles ? `\n\n# Specialist roles (metadata only — use \`agent\` with a role id for bounded read-only expertise)\n${roles}` : "") +
-        (skills ? `\n\n# Skills (capabilities you can load — call the \`skill\` tool with the id for full instructions before using one)\n${skills}` : ""));
+    assembler
+        .add("working-directory", "session", "runtime", `Working directory: ${cwd}`)
+        .add("gateway-channel", "session", "channel", gatewayNote())
+        .add("continuation", "session", "task", continuationSession ? CONTINUATION_SYSTEM : "")
+        .add("execution", "session", "task", executionContext)
+        .add("project", "session", "project", projectContext ? `# Project context (AGENTS.md)\n${projectContext}` : "")
+        .add("memory", "session", "memory", memory ? `# Memory (durable — facts/decisions/prefs you've saved; use memory_search/get for more)\n${memory}` : "")
+        .add("roles", "session", "role", roles ? `# Specialist roles (metadata only — use \`agent\` with a role id for bounded read-only expertise)\n${roles}` : "")
+        .add("skills", "session", "skill", skills ? `# Skills (capabilities you can load — call the \`skill\` tool with the id for full instructions before using one)\n${skills}` : "")
+        .add("task-intake", "turn", "task", intakeContext);
+    return assembler.build();
 }
 const RUN_STOPPED = Symbol("agent-run-stopped");
 const REPEATED_FAILURE_LIMIT = 3;
@@ -618,7 +621,8 @@ async function runAgentInner(history, opts, life) {
             ? [...baseSpecs, ...runExtraTools.map((t) => ({ name: t.name, description: t.description, input_schema: t.input_schema }))]
             : baseSpecs;
         const sink = ctx.ui; // TUI mode: route output to ink instead of stdout
-        const system = composeSystem(ctx.cwd, opts.projectContext, opts.systemOverride, opts.memory, opts.continuationSession, opts.executionContext, { enabled: !!opts.taskIntake, brief: intakeTask?.brief });
+        const assembledSystem = composeSystem(ctx.cwd, opts.projectContext, opts.systemOverride, opts.memory, opts.continuationSession, opts.executionContext, { enabled: !!opts.taskIntake, brief: intakeTask?.brief });
+        const system = assembledSystem.text;
         const prepared = prepareHistoryForModel(history, {
             model: activeProvider.model,
             system,
@@ -714,6 +718,7 @@ async function runAgentInner(history, opts, life) {
                 }
                 return activeProvider.turn({
                     system,
+                    systemParts: assembledSystem.parts,
                     history: prepared.history,
                     tools: specs,
                     // Any stream chunk keeps the connection considered alive — even suppressed reasoning_content, so a

package/dist/agent/prompt.js

@@ -0,0 +1,48 @@
+import { createHash } from "node:crypto";
+const STABILITY_ORDER = {
+    static: 0,
+    session: 1,
+    turn: 2,
+};
+function promptDigest(content) {
+    return createHash("sha256").update(content).digest("hex").slice(0, 16);
+}
+/** Assemble the model's runtime context as a governed object instead of an ever-growing string.
+ *
+ * Ordering is intentionally monotonic. If a caller tries to place stable material after a dynamic task
+ * suffix, fail during assembly instead of silently destroying provider prefix-cache locality. */
+export class PromptAssembler {
+    parts = [];
+    ids = new Set();
+    lastStability = "static";
+    add(id, stability, source, content) {
+        const normalizedId = id.trim();
+        const normalizedContent = content?.trim();
+        if (!normalizedContent)
+            return this;
+        if (!normalizedId)
+            throw new Error("system prompt part id must not be empty");
+        if (this.ids.has(normalizedId))
+            throw new Error(`duplicate system prompt part id: ${normalizedId}`);
+        if (this.parts.length && STABILITY_ORDER[stability] < STABILITY_ORDER[this.lastStability]) {
+            throw new Error(`system prompt part '${normalizedId}' (${stability}) cannot follow ${this.lastStability} context`);
+        }
+        this.ids.add(normalizedId);
+        this.lastStability = stability;
+        this.parts.push({
+            id: normalizedId,
+            stability,
+            source,
+            content: normalizedContent,
+            digest: promptDigest(normalizedContent),
+        });
+        return this;
+    }
+    build() {
+        const parts = this.parts.map((part) => ({ ...part }));
+        return {
+            text: parts.map((part) => part.content).join("\n\n"),
+            parts,
+        };
+    }
+}

package/dist/index.js

@@ -2850,13 +2850,13 @@ pluginCmd
             if (!onPath)
                 out(c.yellow(`  add to PATH once:  echo 'export PATH="$HOME/.hara/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc\n`));
         }
-        // Surface the code-execution surface: a plugin's MCP servers + hooks run shell commands on every
-        // hara launch with no prompt. Installing a plugin = trusting its author to run code; show what.
+        // Surface the code-execution surface without echoing manifest-provided arguments or hook bodies:
+        // those fields may contain credentials. Installing a plugin means trusting code from its author.
         const execs = [];
         for (const [name, s] of Object.entries(m.mcpServers ?? {}))
-            execs.push(`mcp ${name}: ${[s.command, ...(s.args ?? [])].join(" ")}`);
-        for (const h of [...(m.hooks?.PreToolUse ?? []), ...(m.hooks?.PostToolUse ?? [])])
-            execs.push(`hook: ${h.command}`);
+            execs.push(`mcp ${name}: ${s.command}`);
+        for (const _hook of [...(m.hooks?.PreToolUse ?? []), ...(m.hooks?.PostToolUse ?? [])])
+            execs.push("hook configured (command hidden)");
         if (execs.length) {
             out(c.yellow(`⚠ ${p.name} will run these commands on every hara launch (a plugin is code you run — review them):\n`) +
                 execs.map((e) => c.dim(`    ${e}`)).join("\n") +
@@ -2871,7 +2871,14 @@ pluginCmd
     .command("remove <name>")
     .alias("uninstall")
     .description("uninstall a plugin")
-    .action((name) => out(uninstallPlugin(name) ? c.green(`Removed ${name}\n`) : c.dim(`(no plugin '${name}')\n`)));
+    .action((name) => {
+    try {
+        out(uninstallPlugin(name) ? c.green(`Removed ${name}\n`) : c.dim(`(no plugin '${name}')\n`));
+    }
+    catch (error) {
+        out(c.red(`Remove failed: ${error?.message ?? String(error)}\n`));
+    }
+});
 pluginCmd
     .command("enable <name>")
     .description("enable an installed plugin")

package/dist/mcp/client.js

@@ -148,6 +148,7 @@ export async function connectMcpServers(servers, log, options = {}) {
             transport = new StdioClientTransport({
                 command: cfg.command,
                 args: cfg.args ?? [],
+                ...(cfg.cwd ? { cwd: cfg.cwd } : {}),
                 // The inherited agent environment is scrubbed; server-specific cfg.env is an explicit grant.
                 env: toolSubprocessEnv(process.env, cfg.env ?? {}),
                 // The SDK default is "inherit", which would let an external server print credentials or terminal

package/dist/plugins/manifest.js

@@ -0,0 +1,317 @@
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { sensitiveFileReason } from "../security/sensitive-files.js";
+const MANIFEST_PATHS = [".claude-plugin/plugin.json", ".hara-plugin/plugin.json", "plugin.json"];
+const TOP_LEVEL_KEYS = new Set(["name", "version", "description", "skills", "agents", "mcpServers", "hooks", "bin", "panels"]);
+const MCP_KEYS = new Set(["command", "args", "env"]);
+const PANEL_KEYS = new Set(["id", "title", "command", "args", "port", "detect"]);
+const HOOK_KEYS = new Set(["matcher", "command"]);
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const ENV_KEY = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+const MAX_MANIFEST_BYTES = 256 * 1024;
+const MAX_PLUGIN_FILES = 20_000;
+const MAX_PLUGIN_BYTES = 512 * 1024 * 1024;
+const MAX_ARRAY_ENTRIES = 256;
+function record(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${label} must be an object`);
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null)
+        throw new Error(`${label} must be a plain object`);
+    return value;
+}
+function knownKeys(value, allowed, label) {
+    const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+    if (unknown.length)
+        throw new Error(`${label} contains unsupported field '${unknown[0]}'`);
+}
+function text(value, label, max = 4096) {
+    if (typeof value !== "string")
+        throw new Error(`${label} must be a string`);
+    if (!value || value.length > max || /[\0-\x1f\x7f]/u.test(value)) {
+        throw new Error(`${label} is empty, too long, or contains control characters`);
+    }
+    return value;
+}
+export function safePluginId(value, label = "plugin name") {
+    const id = text(value, label, 64);
+    if (!ID.test(id))
+        throw new Error(`${label} must match ${ID.source}`);
+    return id;
+}
+export function safePluginRelativePath(value, label) {
+    const input = text(value, label, 512);
+    const path = input.startsWith("./") ? input.slice(2) : input;
+    if (isAbsolute(path)
+        || path.includes("\\")
+        || path.startsWith("~")
+        || /^[A-Za-z]:/u.test(path)
+        || path.startsWith("//"))
+        throw new Error(`${label} must be a portable relative path`);
+    const parts = path.split("/");
+    if (parts.some((part) => !part || part === "." || part === ".." || /[\0-\x1f\x7f]/u.test(part))) {
+        throw new Error(`${label} must not contain empty, current, parent, or control-character components`);
+    }
+    return parts.join("/");
+}
+function inside(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+export function verifiedPluginPath(root, rel, kind, label) {
+    const safe = safePluginRelativePath(rel, label);
+    const canonicalRoot = realpathSync.native(resolve(root));
+    let current = canonicalRoot;
+    const parts = safe.split("/");
+    for (let index = 0; index < parts.length; index++) {
+        current = join(current, parts[index]);
+        const info = lstatSync(current);
+        if (info.isSymbolicLink())
+            throw new Error(`${label} contains a symbolic-link component`);
+        if (index < parts.length - 1 && !info.isDirectory())
+            throw new Error(`${label} crosses a non-directory component`);
+    }
+    const info = lstatSync(current);
+    if (kind === "file" && (!info.isFile() || info.nlink !== 1))
+        throw new Error(`${label} must be a single-link regular file`);
+    if (kind === "directory" && !info.isDirectory())
+        throw new Error(`${label} must be a directory`);
+    const canonical = realpathSync.native(current);
+    if (!inside(canonicalRoot, canonical))
+        throw new Error(`${label} escapes the immutable plugin root`);
+    return canonical;
+}
+function stringArray(value, label, pathValues = false) {
+    if (!Array.isArray(value) || value.length > MAX_ARRAY_ENTRIES)
+        throw new Error(`${label} must be a bounded array`);
+    return value.map((entry, index) => pathValues
+        ? safePluginRelativePath(entry, `${label}[${index}]`)
+        : text(entry, `${label}[${index}]`));
+}
+function validateHooks(value) {
+    const raw = record(value, "plugin hooks");
+    knownKeys(raw, new Set(["PreToolUse", "PostToolUse"]), "plugin hooks");
+    const out = {};
+    for (const event of ["PreToolUse", "PostToolUse"]) {
+        if (raw[event] === undefined)
+            continue;
+        if (!Array.isArray(raw[event]) || raw[event].length > 64)
+            throw new Error(`plugin hooks.${event} must be a bounded array`);
+        out[event] = raw[event].map((entry, index) => {
+            const item = record(entry, `plugin hooks.${event}[${index}]`);
+            knownKeys(item, HOOK_KEYS, `plugin hooks.${event}[${index}]`);
+            const hook = { command: text(item.command, `plugin hooks.${event}[${index}].command`, 16_384) };
+            if (item.matcher !== undefined)
+                hook.matcher = text(item.matcher, `plugin hooks.${event}[${index}].matcher`, 1024);
+            return hook;
+        });
+    }
+    return out;
+}
+function validateMcpServers(value) {
+    const raw = record(value, "plugin mcpServers");
+    if (Object.keys(raw).length > 64)
+        throw new Error("plugin mcpServers has too many entries");
+    const out = {};
+    for (const [rawName, rawConfig] of Object.entries(raw)) {
+        const name = safePluginId(rawName, "MCP server id");
+        const item = record(rawConfig, `MCP server '${name}'`);
+        knownKeys(item, MCP_KEYS, `MCP server '${name}'`);
+        const command = text(item.command, `MCP server '${name}' command`, 512);
+        if (/\s/u.test(command))
+            throw new Error(`MCP server '${name}' command must be one executable, not a shell command`);
+        const config = { command };
+        if (item.args !== undefined)
+            config.args = stringArray(item.args, `MCP server '${name}' args`);
+        if (item.env !== undefined) {
+            const env = record(item.env, `MCP server '${name}' env`);
+            if (Object.keys(env).length > 128)
+                throw new Error(`MCP server '${name}' env has too many entries`);
+            config.env = {};
+            for (const [key, rawValue] of Object.entries(env)) {
+                if (!ENV_KEY.test(key))
+                    throw new Error(`MCP server '${name}' env key '${key}' is invalid`);
+                config.env[key] = text(rawValue, `MCP server '${name}' env '${key}'`, 65_536);
+            }
+        }
+        out[name] = config;
+    }
+    return out;
+}
+function validateManifest(value, root) {
+    const raw = record(value, "plugin manifest");
+    knownKeys(raw, TOP_LEVEL_KEYS, "plugin manifest");
+    const manifest = { name: safePluginId(raw.name) };
+    if (raw.version !== undefined)
+        manifest.version = text(raw.version, "plugin version", 128);
+    if (raw.description !== undefined)
+        manifest.description = text(raw.description, "plugin description", 4096);
+    for (const field of ["skills", "agents"]) {
+        if (raw[field] === undefined)
+            continue;
+        const paths = stringArray(raw[field], `plugin ${field}`, true);
+        for (let index = 0; index < paths.length; index++) {
+            verifiedPluginPath(root, paths[index], "directory", `plugin ${field}[${index}]`);
+        }
+        manifest[field] = paths;
+    }
+    if (raw.bin !== undefined) {
+        const bins = record(raw.bin, "plugin bin");
+        if (Object.keys(bins).length > 128)
+            throw new Error("plugin bin has too many entries");
+        manifest.bin = {};
+        for (const [rawName, rawPath] of Object.entries(bins)) {
+            const name = safePluginId(rawName, "plugin command name");
+            const rel = safePluginRelativePath(rawPath, `plugin bin '${name}'`);
+            verifiedPluginPath(root, rel, "file", `plugin bin '${name}'`);
+            manifest.bin[name] = rel;
+        }
+    }
+    if (raw.mcpServers !== undefined)
+        manifest.mcpServers = validateMcpServers(raw.mcpServers);
+    if (raw.hooks !== undefined)
+        manifest.hooks = validateHooks(raw.hooks);
+    if (raw.panels !== undefined) {
+        if (!Array.isArray(raw.panels) || raw.panels.length > 64)
+            throw new Error("plugin panels must be a bounded array");
+        manifest.panels = raw.panels.map((entry, index) => {
+            const item = record(entry, `plugin panels[${index}]`);
+            knownKeys(item, PANEL_KEYS, `plugin panels[${index}]`);
+            const command = safePluginId(item.command, `plugin panels[${index}].command`);
+            if (!manifest.bin?.[command]) {
+                throw new Error(`plugin panels[${index}].command must reference a declared plugin bin`);
+            }
+            const panel = {
+                id: safePluginId(item.id, `plugin panels[${index}].id`),
+                title: text(item.title, `plugin panels[${index}].title`, 256),
+                command,
+            };
+            if (item.args !== undefined)
+                panel.args = stringArray(item.args, `plugin panels[${index}].args`);
+            if (item.detect !== undefined)
+                panel.detect = stringArray(item.detect, `plugin panels[${index}].detect`, true);
+            if (item.port !== undefined) {
+                if (!Number.isInteger(item.port) || Number(item.port) < 1 || Number(item.port) > 65_535) {
+                    throw new Error(`plugin panels[${index}].port must be an integer from 1 to 65535`);
+                }
+                panel.port = Number(item.port);
+            }
+            return panel;
+        });
+    }
+    // Validation must fail during staging, not only when a later session starts the server. This also catches
+    // `node server.mjs`-style relative entry scripts whose process cwd used to be the user's current project.
+    if (manifest.mcpServers)
+        bindPluginMcpServers(root, manifest);
+    return manifest;
+}
+export function verifyPluginTree(root) {
+    const canonicalRoot = realpathSync.native(resolve(root));
+    const rootInfo = lstatSync(canonicalRoot);
+    if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink())
+        throw new Error("plugin root must be a real directory");
+    const rootDevice = String(rootInfo.dev);
+    let files = 0;
+    let bytes = 0;
+    const stack = [canonicalRoot];
+    while (stack.length) {
+        const directory = stack.pop();
+        for (const name of readdirSync(directory)) {
+            files++;
+            if (files > MAX_PLUGIN_FILES)
+                throw new Error(`plugin contains more than ${MAX_PLUGIN_FILES} filesystem entries`);
+            const path = join(directory, name);
+            const info = lstatSync(path);
+            if (info.isSymbolicLink())
+                throw new Error(`plugin packages must not contain symbolic links: '${relative(canonicalRoot, path)}'`);
+            if (String(info.dev) !== rootDevice) {
+                throw new Error(`plugin packages must not cross filesystem boundaries: '${relative(canonicalRoot, path)}'`);
+            }
+            if (info.isDirectory()) {
+                stack.push(path);
+                continue;
+            }
+            if (!info.isFile() || info.nlink !== 1) {
+                throw new Error(`plugin packages may contain only directories and single-link regular files: '${relative(canonicalRoot, path)}'`);
+            }
+            const protectedReason = sensitiveFileReason(path);
+            if (protectedReason)
+                throw new Error(`plugin package contains protected ${protectedReason}: '${relative(canonicalRoot, path)}'`);
+            bytes += info.size;
+            if (bytes > MAX_PLUGIN_BYTES)
+                throw new Error(`plugin exceeds the ${MAX_PLUGIN_BYTES}-byte unpacked limit`);
+        }
+    }
+}
+export function readVerifiedPluginManifest(root, options = {}) {
+    if (options.scanTree !== false)
+        verifyPluginTree(root);
+    else {
+        const info = lstatSync(realpathSync.native(resolve(root)));
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new Error("plugin root must be a real directory");
+    }
+    const present = [];
+    for (const rel of MANIFEST_PATHS) {
+        try {
+            present.push(verifiedPluginPath(root, rel, "file", "plugin manifest"));
+        }
+        catch (error) {
+            if (error?.code !== "ENOENT")
+                throw error;
+        }
+    }
+    if (!present.length)
+        throw new Error("no supported plugin.json at the source root");
+    if (present.length > 1)
+        throw new Error("plugin package contains multiple ambiguous manifests");
+    const path = present[0];
+    const info = lstatSync(path);
+    if (info.size > MAX_MANIFEST_BYTES)
+        throw new Error("plugin manifest is too large");
+    const raw = readFileSync(path, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("plugin manifest is not valid JSON");
+    }
+    return {
+        manifest: validateManifest(parsed, root),
+        path,
+        sha256: createHash("sha256").update(raw).digest("hex"),
+    };
+}
+function pathLikeCommand(command) {
+    return command.startsWith(".") || command.includes("/") || command.includes("\\") || isAbsolute(command) || /^[A-Za-z]:/u.test(command);
+}
+/** Bind every plugin-owned MCP process to the installed package root. Bare PATH executables remain
+ * allowed, but relative executables and conventional runtime entry scripts become verified absolute files. */
+export function bindPluginMcpServers(root, manifest) {
+    const out = {};
+    for (const [name, input] of Object.entries(manifest.mcpServers ?? {})) {
+        let command = input.command;
+        const args = [...(input.args ?? [])];
+        if (pathLikeCommand(command)) {
+            command = verifiedPluginPath(root, safePluginRelativePath(command, `MCP server '${name}' command`), "file", `MCP server '${name}' command`);
+        }
+        else {
+            const runtime = command.toLowerCase().replace(/\.exe$/u, "");
+            if (["node", "bun", "deno", "python", "python3", "pythonw"].includes(runtime)) {
+                const scriptIndex = args.findIndex((arg) => !arg.startsWith("-") && /\.(?:[cm]?js|ts|py)$/iu.test(arg));
+                if (scriptIndex >= 0) {
+                    args[scriptIndex] = verifiedPluginPath(root, safePluginRelativePath(args[scriptIndex], `MCP server '${name}' entry script`), "file", `MCP server '${name}' entry script`);
+                }
+            }
+        }
+        out[name] = {
+            command,
+            ...(args.length ? { args } : {}),
+            ...(input.env ? { env: { ...input.env } } : {}),
+            cwd: realpathSync.native(resolve(root)),
+        };
+    }
+    return out;
+}