@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/shared/plan-mode-prompt.js

@@ -0,0 +1,74 @@
+/**
+ * The Plan-mode prompt directive, shared by both harnesses.
+ *
+ * Plan mode's output contract spans three components that must agree:
+ * - the model produces the plan as its FINAL message (this directive),
+ * - the runner publishes that final message verbatim as a plan markdown
+ *   artifact, named from the plan's title (`plan-artifact.ts` —
+ *   `extractFinalPlanText`, `planArtifactName`),
+ * - the SDK promotes the same message to a first-class plan document in the
+ *   thread and offers "Build from plan".
+ *
+ * This module is the single source of truth for how the model is told to
+ * behave, so the two harnesses can never drift apart on the contract. Each
+ * harness wraps the directive in its own prompt framing (the Cursor harness
+ * uses XML-tag sections, the native harness markdown headings) — the framing
+ * is house style; the words are shared.
+ *
+ * Enforcement is separate from instruction: the native harness ALSO denies
+ * filesystem writes at the tool layer (see execute-deep-agent/turn-setup.ts), so
+ * for it this directive is guidance toward a well-formed plan, not the
+ * enforcement mechanism. The Cursor harness has no tool-level lever (the
+ * Cursor SDK exposes no mode parameter), so there this directive is the
+ * enforcement — a documented stopgap.
+ */
+/**
+ * Directive body injected into the system prompt of every Plan-mode
+ * execution. Deliberately explicit about the deliverable's shape: the final
+ * message is published verbatim as a plan document (whose filename is derived
+ * from the leading `#` title), so a fenced or chat-suffixed plan degrades the
+ * reviewable document the user sees.
+ *
+ * Fence hygiene inside the document is part of the same contract. A plan
+ * frequently quotes file content that itself contains fenced code blocks
+ * ("insert this section into README.md"); with a same-length outer fence the
+ * inner block's closer terminates the outer fence early and corrupts the
+ * rendered document — on every client (the react SDK and the terminal
+ * renderer alike). And because the plan viewers render top-level ```mermaid
+ * fences as diagrams, the directive steers diagrams into the plan body proper
+ * rather than leaving them buried, unrendered, inside quoted file content.
+ */
+export const PLAN_MODE_DIRECTIVE = [
+    "IMPORTANT: You are in Plan mode — a read-only analysis turn whose " +
+        "deliverable is an implementation plan.",
+    "",
+    "Constraints:",
+    "- Do NOT create, edit, or delete any files.",
+    "- Do NOT run commands that modify the filesystem or any external state.",
+    "- Only read, search, and analyze.",
+    "",
+    "Deliverable — your FINAL message IS the plan. It is published verbatim " +
+        "as a plan document that the user reviews and builds from, so:",
+    "- Write it as a complete, well-structured markdown document: start with " +
+        "a single `#` title and organize the work under `##` section headings. " +
+        "Use lists and tables where they aid scanning.",
+    '- Give the `#` title a concise, descriptive name for the work itself; do ' +
+        'NOT prefix it with "Plan:" (this document is already a plan — the ' +
+        "prefix is redundant and leaks into the plan's filename).",
+    "- Reference concrete file paths and describe the specific changes " +
+        "planned for each.",
+    "- Do NOT wrap the document in a code fence.",
+    "- When quoting content that itself contains fenced code blocks (e.g. a " +
+        "proposed file section with a code sample inside), open the outer fence " +
+        "with MORE backticks than any inner fence (four or more) — a same-length " +
+        "inner closer would terminate the outer fence early and corrupt the " +
+        "rendered document.",
+    "- Fenced ```mermaid blocks at the top level of the document render as " +
+        "diagrams in the plan viewer. When a diagram helps communicate the " +
+        "design (architecture, flows), include it directly in the plan body — " +
+        "not only inside quoted file content, where it stays unrendered source.",
+    '- Do NOT end with conversational closers ("Let me know...", "Shall I ' +
+        'proceed?") — the next step is the user\'s Build action, and trailing ' +
+        "chat would be published as part of the document.",
+].join("\n");
+//# sourceMappingURL=plan-mode-prompt.js.map

package/dist/shared/plan-mode-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-mode-prompt.js","sourceRoot":"","sources":["../../src/shared/plan-mode-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,oEAAoE;QAClE,wCAAwC;IAC1C,EAAE;IACF,cAAc;IACd,6CAA6C;IAC7C,yEAAyE;IACzE,mCAAmC;IACnC,EAAE;IACF,yEAAyE;QACvE,+DAA+D;IACjE,0EAA0E;QACxE,wEAAwE;QACxE,+CAA+C;IACjD,2EAA2E;QACzE,oEAAoE;QACpE,0DAA0D;IAC5D,oEAAoE;QAClE,mBAAmB;IACrB,6CAA6C;IAC7C,yEAAyE;QACvE,yEAAyE;QACzE,0EAA0E;QAC1E,qEAAqE;QACrE,oBAAoB;IACtB,wEAAwE;QACtE,oEAAoE;QACpE,uEAAuE;QACvE,wEAAwE;IAC1E,uEAAuE;QACrE,uEAAuE;QACvE,kDAAkD;CACrD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC"}

package/dist/shared/platform-server-address.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The Stigmer server's address for user-defined MCP servers — the reserved
+ * STIGMER_SERVER_ADDRESS key, and the one dial-target rule every writer of
+ * that key shares (stigmer/stigmer#1433, #1446).
+ *
+ * The runner is the one component that supplies it, because the runner is
+ * the one that knows where the consumer runs:
+ *
+ *   - A remote HTTP server receives the key only through a templated header,
+ *     so it needs the server's PUBLIC address: STIGMER_MCP_PUBLIC_ENDPOINT,
+ *     which the server hands every sandbox it provisions from its own
+ *     configuration (stigmer/stigmer#1447), or an operator names to a
+ *     runner it starts by hand.
+ *   - A stdio server is a child of this runner (only a local runner spawns
+ *     one; mcp-transport-guard.ts), so the address the runner itself dials,
+ *     STIGMER_BACKEND_ENDPOINT, is right for it by construction.
+ *
+ * No page supplies it: a value a page could write (a conversation's own
+ * secrets) is resolved ahead of every vault the user saved
+ * (stigmer/stigmer#1446).
+ *
+ * The runner FILLS, it never overrides: a non-empty value already in the
+ * environment (one the user saved or typed to aim a server elsewhere)
+ * stands. A key nobody can supply stays missing, and a
+ * header that templates it fails with the resolver's named
+ * PlaceholderResolutionError instead of dialing a guess.
+ *
+ * Injection is opt-in exactly as for the caller-identity keys
+ * (caller-identity.ts): only a server that reads the key (its plugin entry
+ * names it in `env`) receives it. Applied before filterEnvToDeclaredKeys at
+ * execution (mcp-resolver.ts) and before placeholder resolution in a tools
+ * listing (shared/mcp-tool-listing.ts), so both share one rule.
+ */
+import type { McpServerEntry } from "@stigmer/apis/ai/stigmer/agentic/plugin/v1/status_pb";
+import type { Config } from "../config.js";
+/**
+ * Reserved env key: the Stigmer server's gRPC dial target, host:port. The
+ * name the mcp-server reads its target from (mcp-server/src/config.ts) and
+ * `@stigmer/react-sdk` keeps out of its setup prompts
+ * (sdk/react/src/environment/systemEnvVars.ts); a cross-package string,
+ * pinned on every side.
+ */
+export declare const SERVER_ADDRESS_ENV_KEY = "STIGMER_SERVER_ADDRESS";
+/** The two runner-known endpoints an address can be filled from. */
+export type PlatformEndpoints = Pick<Config, "mcpPublicEndpoint" | "stigmerBackendEndpoint">;
+/**
+ * The gRPC dial target (host:port) for an endpoint, the shape
+ * STIGMER_SERVER_ADDRESS wants.
+ *
+ * An http(s) URL becomes its host with an explicit port: the URL's own, else
+ * 80 for http and 443 for https. The port is never left implicit, because
+ * the mcp-server derives TLS from it and assumes :443 with TLS for a
+ * non-loopback host that has none (mcp-server/src/config.ts). Any other
+ * input (a scheme-less host:port, a bare host) is already a dial target and
+ * passes through unchanged.
+ */
+export declare function grpcTarget(endpoint: string): string;
+/**
+ * The address the platform supplies for a server of this transport, or
+ * `null` when the runner knows none: the operator's public endpoint for any
+ * transport, else the runner's own backend endpoint for a stdio child.
+ */
+export declare function platformServerAddress(transport: McpServerTransport | undefined, endpoints: PlatformEndpoints): string | null;
+/**
+ * Return the env map with STIGMER_SERVER_ADDRESS filled for `server` when it
+ * reads the key and the map holds no non-empty value for it; otherwise the
+ * map itself, unchanged. Never mutates its input.
+ */
+export declare function fillPlatformServerAddress(server: McpServerEntry, slug: string, envVars: Record<string, string>, endpoints: PlatformEndpoints): Record<string, string>;
+/** The transports a plugin's server entry declares (its `transport` oneof). */
+type McpServerTransport = NonNullable<McpServerEntry["transport"]["case"]>;
+export {};

package/dist/shared/platform-server-address.js

@@ -0,0 +1,103 @@
+/**
+ * The Stigmer server's address for user-defined MCP servers — the reserved
+ * STIGMER_SERVER_ADDRESS key, and the one dial-target rule every writer of
+ * that key shares (stigmer/stigmer#1433, #1446).
+ *
+ * The runner is the one component that supplies it, because the runner is
+ * the one that knows where the consumer runs:
+ *
+ *   - A remote HTTP server receives the key only through a templated header,
+ *     so it needs the server's PUBLIC address: STIGMER_MCP_PUBLIC_ENDPOINT,
+ *     which the server hands every sandbox it provisions from its own
+ *     configuration (stigmer/stigmer#1447), or an operator names to a
+ *     runner it starts by hand.
+ *   - A stdio server is a child of this runner (only a local runner spawns
+ *     one; mcp-transport-guard.ts), so the address the runner itself dials,
+ *     STIGMER_BACKEND_ENDPOINT, is right for it by construction.
+ *
+ * No page supplies it: a value a page could write (a conversation's own
+ * secrets) is resolved ahead of every vault the user saved
+ * (stigmer/stigmer#1446).
+ *
+ * The runner FILLS, it never overrides: a non-empty value already in the
+ * environment (one the user saved or typed to aim a server elsewhere)
+ * stands. A key nobody can supply stays missing, and a
+ * header that templates it fails with the resolver's named
+ * PlaceholderResolutionError instead of dialing a guess.
+ *
+ * Injection is opt-in exactly as for the caller-identity keys
+ * (caller-identity.ts): only a server that reads the key (its plugin entry
+ * names it in `env`) receives it. Applied before filterEnvToDeclaredKeys at
+ * execution (mcp-resolver.ts) and before placeholder resolution in a tools
+ * listing (shared/mcp-tool-listing.ts), so both share one rule.
+ */
+/**
+ * Reserved env key: the Stigmer server's gRPC dial target, host:port. The
+ * name the mcp-server reads its target from (mcp-server/src/config.ts) and
+ * `@stigmer/react-sdk` keeps out of its setup prompts
+ * (sdk/react/src/environment/systemEnvVars.ts); a cross-package string,
+ * pinned on every side.
+ */
+export const SERVER_ADDRESS_ENV_KEY = "STIGMER_SERVER_ADDRESS";
+/**
+ * The gRPC dial target (host:port) for an endpoint, the shape
+ * STIGMER_SERVER_ADDRESS wants.
+ *
+ * An http(s) URL becomes its host with an explicit port: the URL's own, else
+ * 80 for http and 443 for https. The port is never left implicit, because
+ * the mcp-server derives TLS from it and assumes :443 with TLS for a
+ * non-loopback host that has none (mcp-server/src/config.ts). Any other
+ * input (a scheme-less host:port, a bare host) is already a dial target and
+ * passes through unchanged.
+ */
+export function grpcTarget(endpoint) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        return endpoint;
+    }
+    // `new URL("host:7234")` parses with `host:` as its scheme, so only a
+    // real http(s) URL is taken apart.
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        return endpoint;
+    }
+    const port = url.port || (url.protocol === "https:" ? "443" : "80");
+    return `${url.hostname}:${port}`;
+}
+/**
+ * The address the platform supplies for a server of this transport, or
+ * `null` when the runner knows none: the operator's public endpoint for any
+ * transport, else the runner's own backend endpoint for a stdio child.
+ */
+export function platformServerAddress(transport, endpoints) {
+    if (endpoints.mcpPublicEndpoint) {
+        return grpcTarget(endpoints.mcpPublicEndpoint);
+    }
+    if (transport === "stdio") {
+        return grpcTarget(endpoints.stigmerBackendEndpoint);
+    }
+    return null;
+}
+/**
+ * Return the env map with STIGMER_SERVER_ADDRESS filled for `server` when it
+ * reads the key and the map holds no non-empty value for it; otherwise the
+ * map itself, unchanged. Never mutates its input.
+ */
+export function fillPlatformServerAddress(server, slug, envVars, endpoints) {
+    if (!server.env.includes(SERVER_ADDRESS_ENV_KEY) || envVars[SERVER_ADDRESS_ENV_KEY]) {
+        return envVars;
+    }
+    const value = platformServerAddress(server.transport.case, endpoints);
+    if (value === null) {
+        return envVars;
+    }
+    const source = endpoints.mcpPublicEndpoint
+        ? "STIGMER_MCP_PUBLIC_ENDPOINT"
+        : "STIGMER_BACKEND_ENDPOINT";
+    console.info(`MCP server '${slug}': ${SERVER_ADDRESS_ENV_KEY} ` +
+        `filled from ${source} (no value in the server's own values)`);
+    return { ...envVars, [SERVER_ADDRESS_ENV_KEY]: value };
+}
+//# sourceMappingURL=platform-server-address.js.map

package/dist/shared/platform-server-address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-server-address.js","sourceRoot":"","sources":["../../src/shared/platform-server-address.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAKH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,wBAAwB,CAAC;AAK/D;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,QAAgB;IACzC,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,sEAAsE;IACtE,mCAAmC;IACnC,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1D,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACpE,OAAO,GAAG,GAAG,CAAC,QAAQ,IAAI,IAAI,EAAE,CAAC;AACnC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CACnC,SAAyC,EACzC,SAA4B;IAE5B,IAAI,SAAS,CAAC,iBAAiB,EAAE,CAAC;QAChC,OAAO,UAAU,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC;IACjD,CAAC;IACD,IAAI,SAAS,KAAK,OAAO,EAAE,CAAC;QAC1B,OAAO,UAAU,CAAC,SAAS,CAAC,sBAAsB,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CACvC,MAAsB,EACtB,IAAY,EACZ,OAA+B,EAC/B,SAA4B;IAE5B,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,sBAAsB,CAAC,IAAI,OAAO,CAAC,sBAAsB,CAAC,EAAE,CAAC;QACpF,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,MAAM,KAAK,GAAG,qBAAqB,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACtE,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,MAAM,MAAM,GAAG,SAAS,CAAC,iBAAiB;QACxC,CAAC,CAAC,6BAA6B;QAC/B,CAAC,CAAC,0BAA0B,CAAC;IAC/B,OAAO,CAAC,IAAI,CACV,eAAe,IAAI,MAAM,sBAAsB,GAAG;QAClD,eAAe,MAAM,wCAAwC,CAC9D,CAAC;IACF,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC,sBAAsB,CAAC,EAAE,KAAK,EAAE,CAAC;AACzD,CAAC"}

package/dist/shared/plugin-mount.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Plugin mount — a referenced plugin's archive as a directory tree its hooks
+ * run from (`${CLAUDE_PLUGIN_ROOT}`), held to the verified archive before
+ * each hook run.
+ *
+ * Where it lands, under the session's platform dir:
+ *
+ *   plugins/<digest>.zip   the archive, cached across the session's turns
+ *   plugins/<digest>/      the tree a hook runs from
+ *   plugin-data/<slug>/    `${CLAUDE_PLUGIN_DATA}`, kept across turns
+ *
+ * The cache is content-addressed by the plugin's `status.digest`, the
+ * server's SHA-256 of the archive it installed. A cached archive is used
+ * only when its own SHA-256 equals that digest; anything else is fetched
+ * again (`archive-mount.ts`) and verified the same way, and an archive that
+ * cannot be fetched or verified throws, which refuses the turn: a hook that
+ * silently does not run is a policy that vanished. This deliberately differs
+ * from a skill, whose failed download degrades to `SKILL.md` alone.
+ *
+ * The tamper guard. The agent's shell runs as the same user as the runner,
+ * and the platform dir is reachable from the workspace, so the shell can
+ * rewrite anything under it, a marker file included. The reference copy
+ * therefore lives in the runner's memory: the verified archive's bytes and a
+ * table of every entry's size, SHA-256 and mode. {@link PluginTree.verify}
+ * runs before each hook run: it `lstat`s the tree, re-hashes only the files
+ * whose size, mode, inode or change time moved since the last check, and
+ * rebuilds the whole tree from the archive in memory on any difference (an
+ * edited, added, removed or replaced file). It is a check before the spawn,
+ * not a lock: a shell call running in the same model step can still write
+ * the tree between the check and the hook reading it. Neither can it stop
+ * an interpreter on `PATH` replaced by the shell. Both walls are the
+ * sandbox's. A hook that writes into its own tree has it rebuilt before the
+ * next run, even under another of the plugin's hooks still running from it;
+ * `${CLAUDE_PLUGIN_DATA}` is the plugin's writable place, and its hooks run
+ * with Python's bytecode cache off (`hooks/evaluate.ts`).
+ *
+ * The plugin's eval suite is never mounted: `evals/`, the directory
+ * `PluginStatus.evals.dir` names when the manifest moved the suite, and the
+ * manifest's own `experimental.evals` read from the archive (a plugin
+ * installed before the status carried the directory has none recorded),
+ * under the library's rule that refuses a directory overlapping the
+ * skills, are left out of the tree, so an agent under test cannot read the cases it is
+ * graded on, as Claude Code hides them from its own runs. An entry is
+ * judged by its cleaned, root-relative name, the name the server's suite
+ * reader gives it, so `./evals/…` or `x/../evals/…` is a suite file here
+ * too. Hooks never need
+ * them; the suite is the eval workflow's, which reads the archive itself.
+ * For the same reason an archive that carries a suite is never cached on
+ * disk: the cache must hash to the digest, so it is the whole archive, and
+ * the shell could unzip it. Such an archive is fetched on every turn
+ * instead (plugins are small), and a cached copy an earlier runner left is
+ * removed.
+ *
+ * Turns of one workspace are serialised (`harness/turn-context.ts`
+ * `acquireWorkspaceTurnLock`), so no two turns mount one tree at once; within
+ * a turn, concurrent hook runs share one check in flight.
+ */
+import type { Plugin } from "@stigmer/apis/ai/stigmer/agentic/plugin/v1/api_pb";
+import type { StigmerClient } from "../client/stigmer-client.js";
+import { type ZipFileEntry } from "./zip-extract.js";
+/** Subdirectory of the platform dir holding plugin archives and trees. */
+export declare const PLUGINS_SUBDIR = "plugins";
+/** Subdirectory of the platform dir holding each plugin's `${CLAUDE_PLUGIN_DATA}`. */
+export declare const PLUGIN_DATA_SUBDIR = "plugin-data";
+/** One mounted plugin, as a hook run reads it. */
+export interface MountedPlugin {
+    /** The plugin's id: its hooks' values are grouped by it (`RunValues.plugins`). */
+    readonly id: string;
+    /** The plugin's slug, the name a run records as the deciding hook. */
+    readonly slug: string;
+    /** The plugin's own name (its manifest's), as Claude Code names its servers. */
+    readonly name: string;
+    /** `${CLAUDE_PLUGIN_ROOT}`. */
+    readonly root: string;
+    /** `${CLAUDE_PLUGIN_DATA}`. */
+    readonly data: string;
+    /** Bring the tree back to the verified archive if anything changed it; run before every hook run. */
+    readonly verify: () => Promise<void>;
+}
+/** A plugin that cannot be mounted; its message names the plugin. */
+export declare class PluginMountError extends Error {
+    constructor(slug: string, detail: string, options?: {
+        readonly cause?: unknown;
+    });
+}
+export declare function sha256Hex(bytes: Uint8Array): string;
+/**
+ * Mount a referenced plugin for this turn: its archive cached and verified,
+ * its tree equal to the archive, its data directory present. Throws
+ * {@link PluginMountError} when any of that cannot be done.
+ */
+export declare function mountPlugin(client: StigmerClient, plugin: Plugin, platformDir: string): Promise<MountedPlugin>;
+/**
+ * The archive's entries minus the eval suite: everything under `evals/`,
+ * and under each of `dirs` (the directory the install recorded, the one
+ * the manifest names) that is set. An entry is matched by
+ * {@link cleanEntryPath}, the directories are plugin-relative paths of
+ * plain segments.
+ */
+export declare function withoutEvalSuite(entries: readonly ZipFileEntry[], ...dirs: readonly (string | undefined)[]): readonly ZipFileEntry[];
+/**
+ * An entry's name as the server's archive gate sanitises it before the
+ * suite reader sees it (`stigmer-server` `archive/prefilter.ts`
+ * `sanitizePath`): backslashes as slashes, `.` and `..` resolved against
+ * the root, no leading slash.
+ */
+export declare function cleanEntryPath(name: string): string;
+/**
+ * Whether an archive holds a plugin manifest, by its cleaned name. A
+ * plugin's root skill is the whole package as one skill, manifests
+ * included, so its archive always holds one; a skill pushed on its own
+ * holds none unless its author put one there.
+ */
+export declare function holdsPluginManifest(entries: readonly ZipFileEntry[]): boolean;
+/**
+ * The suite directory the archive's own manifest names, by the library's
+ * rule (`@stigmer/plugin-package` `evals/eval-dir.ts` `resolveEvalDir`):
+ * the first manifest carrying `experimental.evals` decides (an array by its
+ * first entry, a `./` prefix stripped), and its value
+ * is used only when it is a relative path of plain directory names that
+ * does not overlap the skills (`skills/` or a declared skill path, other
+ * than the plugin's root, being it, holding it or lying inside it);
+ * anything else leaves `evals/` alone, as the library falls back to it, so
+ * a skill is never mounted short of its own files. A manifest that does
+ * not parse contributes nothing, as the library reads it. Parsed here
+ * rather than through the library, which the runner does not depend on (it
+ * would bring its YAML and ZIP dependencies into every runner build for
+ * two fields).
+ */
+export declare function manifestEvalDir(entries: readonly ZipFileEntry[]): string | undefined;
+/**
+ * A plugin's tree and the in-memory reference it is held to. Exported for
+ * the guard's own tests; every other caller goes through {@link mountPlugin}.
+ */
+export declare class PluginTree {
+    readonly root: string;
+    private readonly entries;
+    private readonly expected;
+    private readonly seen;
+    private inFlight;
+    constructor(root: string, entries: readonly ZipFileEntry[]);
+    /**
+     * Hold the tree to the archive: a check that hashes only what moved, and
+     * a rebuild on any difference. Concurrent callers share one check.
+     */
+    verify(): Promise<void>;
+    private check;
+    /**
+     * Whether the tree on disk is exactly the archive. Anything that fails
+     * while reading it (the tree missing, a file the shell removed between the
+     * listing and its read) is a difference.
+     */
+    private intact;
+    /** The comparison itself; records each file's signature as it goes, and throws when the tree cannot be read. */
+    private matches;
+    /** Every entry under the root as a regular file's signature; `undefined` when it holds anything but files and directories. */
+    private listFiles;
+    /**
+     * Write the archive's files afresh. A write that fails leaves a partial
+     * tree the next check rebuilds; a tree that still differs once written
+     * (a filesystem that folds two names into one, say) refuses, because a
+     * hook would run from something other than the archive.
+     */
+    private rebuild;
+}