@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/shared/placeholder-resolver.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Strict placeholder resolver for ${VAR_NAME} syntax in MCP server configs.
+ *
+ * Port of the Python agent-runner's PlaceholderResolver (strict mode only).
+ * Always raises on unresolved placeholders — sending literal ${VAR} as an
+ * HTTP header value (e.g. Authorization: Bearer ${API_KEY}) produces
+ * cryptic auth failures from the remote server.
+ */
+/** The `${VAR_NAME}` scanner; the plugin library and the server hold a pinned copy. */
+export declare const PLACEHOLDER_RE: RegExp;
+export declare class PlaceholderResolutionError extends Error {
+    readonly variableName: string;
+    readonly context?: string | undefined;
+    constructor(variableName: string, context?: string | undefined);
+}
+/**
+ * Resolve all ${VAR_NAME} placeholders in a template string.
+ *
+ * @throws PlaceholderResolutionError if any placeholder cannot be resolved.
+ */
+export declare function resolvePlaceholders(template: string, envVars: Record<string, string>, context?: string): string;
+/**
+ * Resolve placeholders in all values of a headers map.
+ *
+ * @throws PlaceholderResolutionError if any header value contains an
+ *   unresolvable placeholder.
+ */
+export declare function resolveHeaders(headers: Record<string, string>, envVars: Record<string, string>): Record<string, string>;
+/**
+ * Filter env vars to only the keys a declarer declares in its spec.env:
+ * an MCP server for its subprocess or HTTP environment, the agent for its
+ * shell (shared/shell-env.ts).
+ *
+ * Mirrors the agent-runner's _filter_env_to_declared_keys: prevents
+ * secret over-sharing by restricting each consumer to explicitly declared
+ * variables. A declarer that declares nothing receives nothing.
+ * `declarer` names it in the log lines ("MCP server 'linear'").
+ */
+export declare function filterEnvToDeclaredKeys(declaredEnv: Record<string, unknown> | undefined, envVars: Record<string, string>, declarer: string): Record<string, string>;

package/dist/shared/placeholder-resolver.js

@@ -0,0 +1,86 @@
+/**
+ * Strict placeholder resolver for ${VAR_NAME} syntax in MCP server configs.
+ *
+ * Port of the Python agent-runner's PlaceholderResolver (strict mode only).
+ * Always raises on unresolved placeholders — sending literal ${VAR} as an
+ * HTTP header value (e.g. Authorization: Bearer ${API_KEY}) produces
+ * cryptic auth failures from the remote server.
+ */
+/** The `${VAR_NAME}` scanner; the plugin library and the server hold a pinned copy. */
+export const PLACEHOLDER_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+export class PlaceholderResolutionError extends Error {
+    variableName;
+    context;
+    constructor(variableName, context) {
+        const where = context ? ` in ${context}` : "";
+        super(`Unresolved placeholder \${${variableName}}${where}: ` +
+            `variable is not present in the execution environment`);
+        this.variableName = variableName;
+        this.context = context;
+        this.name = "PlaceholderResolutionError";
+    }
+}
+/**
+ * Resolve all ${VAR_NAME} placeholders in a template string.
+ *
+ * @throws PlaceholderResolutionError if any placeholder cannot be resolved.
+ */
+export function resolvePlaceholders(template, envVars, context) {
+    return template.replace(PLACEHOLDER_RE, (match, varName) => {
+        if (varName in envVars) {
+            return envVars[varName];
+        }
+        throw new PlaceholderResolutionError(varName, context);
+    });
+}
+/**
+ * Resolve placeholders in all values of a headers map.
+ *
+ * @throws PlaceholderResolutionError if any header value contains an
+ *   unresolvable placeholder.
+ */
+export function resolveHeaders(headers, envVars) {
+    const resolved = {};
+    for (const [key, value] of Object.entries(headers)) {
+        resolved[key] = resolvePlaceholders(value, envVars, `header "${key}"`);
+    }
+    return resolved;
+}
+/**
+ * Filter env vars to only the keys a declarer declares in its spec.env:
+ * an MCP server for its subprocess or HTTP environment, the agent for its
+ * shell (shared/shell-env.ts).
+ *
+ * Mirrors the agent-runner's _filter_env_to_declared_keys: prevents
+ * secret over-sharing by restricting each consumer to explicitly declared
+ * variables. A declarer that declares nothing receives nothing.
+ * `declarer` names it in the log lines ("MCP server 'linear'").
+ */
+export function filterEnvToDeclaredKeys(declaredEnv, envVars, declarer) {
+    if (!declaredEnv || Object.keys(declaredEnv).length === 0) {
+        if (Object.keys(envVars).length > 0) {
+            console.log(`${declarer} has no env declarations — ` +
+                `dropping ${Object.keys(envVars).length} env var(s)`);
+        }
+        return {};
+    }
+    const declaredKeys = new Set(Object.keys(declaredEnv));
+    const filtered = {};
+    for (const [key, value] of Object.entries(envVars)) {
+        if (declaredKeys.has(key)) {
+            filtered[key] = value;
+        }
+    }
+    const dropped = Object.keys(envVars).length - Object.keys(filtered).length;
+    if (dropped > 0) {
+        console.log(`${declarer}: passing ${Object.keys(filtered).length} ` +
+            `declared env var(s), filtered out ${dropped} undeclared key(s)`);
+    }
+    const missing = [...declaredKeys].filter((k) => !(k in filtered));
+    if (missing.length > 0) {
+        console.warn(`${declarer}: env declares [${missing.sort().join(", ")}] ` +
+            `but they are not present in the resolved environment`);
+    }
+    return filtered;
+}
+//# sourceMappingURL=placeholder-resolver.js.map

package/dist/shared/placeholder-resolver.js.map

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

package/dist/shared/plan-artifact.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Plan-mode artifact publishing.
+ *
+ * When an execution runs in Plan mode (InteractionMode.PLAN), the agent's final
+ * message IS the plan. We publish that text as a first-class plan markdown
+ * RunArtifact so the UI can render a reviewable Plan card with
+ * copy/download, and a follow-up "Implement" execution can reference it
+ * deterministically.
+ *
+ * The artifact is named from the plan's own title — a hyphenated slug of its
+ * leading `# H1`, a `_<hash>` discriminator, and a `.plan.md` suffix (e.g.
+ * `plan-card-ux-cleanup_a1b2c3d4.plan.md`), so a downloaded plan lands as a
+ * recognizable file and the card, plan tab, and saved file all agree on one
+ * name. A plan with no derivable title falls back to a bare `<hash>.plan.md`.
+ *
+ * The `_<hash>` discriminator (first 8 hex of the plan content's SHA-256) is
+ * NOT for storage uniqueness — storage keys are already execution-scoped
+ * (`artifacts/{execId}/<name>`). It exists because the artifact BASENAME is a
+ * user-facing shared namespace: downloads save under it (see the artifact
+ * download disposition) and the artifact list surfaces it, so two same-titled
+ * plans would otherwise collide in the user's Downloads folder and read
+ * identically in the list. Deriving it from content (not a random or
+ * execution-scoped value) keeps naming honestly idempotent — identical content
+ * yields an identical name, so a finalize retry re-uploads to the same key,
+ * while any real edit yields a distinct one. A plain no-uniqueness-hash rule
+ * would be correct about storage but would overlook the download/list
+ * basename namespace.
+ *
+ * This is deliberately a single, harness-agnostic helper:
+ * - The native (deepagents) harness already auto-publishes files an agent
+ *   writes (InlinePublisher), but Plan mode is read-only, so there is no file to
+ *   publish — the plan lives only in the final message.
+ * - The Cursor harness has no artifact pipeline at all.
+ *
+ * Publishing the final message here, at finalization, gives both harnesses an
+ * identical, durable plan artifact derived from the single source of truth (the
+ * final AI message). It mirrors the InlinePublisher "publish a derived artifact"
+ * pattern: one immutable artifact, published once, never a parallel copy that
+ * can drift.
+ *
+ * The plan content is NOT duplicated as a separate stored blob beyond this
+ * artifact — the chat message remains the live/streamed view; the artifact is
+ * the durable/exportable view, detected by convention (a FILE artifact whose
+ * name satisfies {@link isPlanArtifactName}).
+ */
+import type { RunStatus } from "@stigmer/apis/ai/stigmer/agentic/run/v1/api_pb";
+import type { ArtifactStorage } from "./artifact-storage.js";
+import type { TurnRows } from "../gen/turn/ai/stigmer/runner/turn/v1/rows_pb.js";
+/**
+ * Legacy plan filename. Detection-only: {@link isPlanArtifactName} still
+ * accepts this exact name so plans published before named artifacts existed
+ * keep working. It is NEVER freshly emitted — a titleless plan now falls back
+ * to a bare `<hash>.plan.md` (see {@link planArtifactName}).
+ */
+export declare const PLAN_ARTIFACT_NAME = "plan.md";
+/**
+ * Suffix every named plan artifact carries. The UI keys plan detection on this
+ * suffix, so it must stay in sync with the SDK's `PLAN_ARTIFACT_SUFFIX`
+ * (`sdk/react/src/library/detect-plan-artifact.ts`). The two cannot share a
+ * module — the runner and the browser SDK have disjoint module graphs — so the
+ * constant is duplicated by design, mirroring {@link PLAN_ARTIFACT_NAME}.
+ */
+export declare const PLAN_ARTIFACT_SUFFIX = ".plan.md";
+/**
+ * Reports whether an artifact filename is a plan: the legacy exact name, or any
+ * `*.plan.md`. Kept in sync with the SDK's `isPlanArtifactName`.
+ */
+export declare function isPlanArtifactName(name: string): boolean;
+/**
+ * Derives the plan artifact's filename from its text: `<slug>_<id>.plan.md`
+ * when the plan opens with a titled `# H1`, else a bare `<id>.plan.md`. The
+ * `<id>` is the first {@link PLAN_ID_LENGTH} hex of the content's SHA-256 — a
+ * user-facing discriminator for the shared download/list basename namespace,
+ * not a storage-uniqueness device (see the module doc).
+ */
+export declare function planArtifactName(planText: string): string;
+/**
+ * Sandbox path recorded on the artifact for a given filename. Routes under
+ * `.stigmer/` (the session platform dir), so it never pollutes the user's
+ * workspace, and a follow-up execution can reference it via workspace file
+ * refs if desired.
+ */
+export declare function planArtifactSandboxPath(name: string): string;
+/**
+ * Returns the text of the last AI message in a completed turn's rows.
+ * Returns `undefined` when there is no AI message with content — the plan was
+ * empty and nothing should be published.
+ */
+export declare function extractFinalPlanText(rows: Pick<TurnRows, "messages">): string | undefined;
+/**
+ * Publishes `planText` as a plan RunArtifact (named from its title —
+ * see {@link planArtifactName}) and registers it on `status.artifacts`.
+ * Idempotent: re-publishing replaces any existing plan artifact — matched by
+ * {@link isPlanArtifactName}, not exact name, so a re-plan whose title changed
+ * still supersedes rather than appends — preserving a single source of truth.
+ *
+ * Fire-and-forget by contract: a plan that fails to upload must never fail the
+ * execution. Errors are logged and swallowed.
+ */
+export declare function publishPlanArtifact(opts: {
+    readonly status: RunStatus;
+    readonly executionId: string;
+    readonly planText: string;
+    readonly artifactStorage: ArtifactStorage;
+}): Promise<void>;

package/dist/shared/plan-artifact.js

@@ -0,0 +1,225 @@
+/**
+ * Plan-mode artifact publishing.
+ *
+ * When an execution runs in Plan mode (InteractionMode.PLAN), the agent's final
+ * message IS the plan. We publish that text as a first-class plan markdown
+ * RunArtifact so the UI can render a reviewable Plan card with
+ * copy/download, and a follow-up "Implement" execution can reference it
+ * deterministically.
+ *
+ * The artifact is named from the plan's own title — a hyphenated slug of its
+ * leading `# H1`, a `_<hash>` discriminator, and a `.plan.md` suffix (e.g.
+ * `plan-card-ux-cleanup_a1b2c3d4.plan.md`), so a downloaded plan lands as a
+ * recognizable file and the card, plan tab, and saved file all agree on one
+ * name. A plan with no derivable title falls back to a bare `<hash>.plan.md`.
+ *
+ * The `_<hash>` discriminator (first 8 hex of the plan content's SHA-256) is
+ * NOT for storage uniqueness — storage keys are already execution-scoped
+ * (`artifacts/{execId}/<name>`). It exists because the artifact BASENAME is a
+ * user-facing shared namespace: downloads save under it (see the artifact
+ * download disposition) and the artifact list surfaces it, so two same-titled
+ * plans would otherwise collide in the user's Downloads folder and read
+ * identically in the list. Deriving it from content (not a random or
+ * execution-scoped value) keeps naming honestly idempotent — identical content
+ * yields an identical name, so a finalize retry re-uploads to the same key,
+ * while any real edit yields a distinct one. A plain no-uniqueness-hash rule
+ * would be correct about storage but would overlook the download/list
+ * basename namespace.
+ *
+ * This is deliberately a single, harness-agnostic helper:
+ * - The native (deepagents) harness already auto-publishes files an agent
+ *   writes (InlinePublisher), but Plan mode is read-only, so there is no file to
+ *   publish — the plan lives only in the final message.
+ * - The Cursor harness has no artifact pipeline at all.
+ *
+ * Publishing the final message here, at finalization, gives both harnesses an
+ * identical, durable plan artifact derived from the single source of truth (the
+ * final AI message). It mirrors the InlinePublisher "publish a derived artifact"
+ * pattern: one immutable artifact, published once, never a parallel copy that
+ * can drift.
+ *
+ * The plan content is NOT duplicated as a separate stored blob beyond this
+ * artifact — the chat message remains the live/streamed view; the artifact is
+ * the durable/exportable view, detected by convention (a FILE artifact whose
+ * name satisfies {@link isPlanArtifactName}).
+ */
+import { createHash } from "node:crypto";
+import { create } from "@bufbuild/protobuf";
+import { RunArtifactSchema } from "@stigmer/apis/ai/stigmer/agentic/run/v1/artifact_pb";
+import { RunArtifactKind, } from "@stigmer/apis/ai/stigmer/agentic/run/v1/enum_pb";
+import { utcTimestamp } from "./status.js";
+import { MessageType } from "../gen/turn/ai/stigmer/runner/turn/v1/enum_pb.js";
+/**
+ * Legacy plan filename. Detection-only: {@link isPlanArtifactName} still
+ * accepts this exact name so plans published before named artifacts existed
+ * keep working. It is NEVER freshly emitted — a titleless plan now falls back
+ * to a bare `<hash>.plan.md` (see {@link planArtifactName}).
+ */
+export const PLAN_ARTIFACT_NAME = "plan.md";
+/**
+ * Suffix every named plan artifact carries. The UI keys plan detection on this
+ * suffix, so it must stay in sync with the SDK's `PLAN_ARTIFACT_SUFFIX`
+ * (`sdk/react/src/library/detect-plan-artifact.ts`). The two cannot share a
+ * module — the runner and the browser SDK have disjoint module graphs — so the
+ * constant is duplicated by design, mirroring {@link PLAN_ARTIFACT_NAME}.
+ */
+export const PLAN_ARTIFACT_SUFFIX = ".plan.md";
+/** Longest slug we derive from a plan title before the `_<id>.plan.md` tail. */
+const MAX_PLAN_SLUG_LENGTH = 60;
+/** Hex length of the content-hash discriminator appended to named plans. */
+const PLAN_ID_LENGTH = 8;
+/**
+ * Reports whether an artifact filename is a plan: the legacy exact name, or any
+ * `*.plan.md`. Kept in sync with the SDK's `isPlanArtifactName`.
+ */
+export function isPlanArtifactName(name) {
+    return name === PLAN_ARTIFACT_NAME || name.endsWith(PLAN_ARTIFACT_SUFFIX);
+}
+// Plan-title extraction, mirrored from the SDK so the runner's derived filename
+// and the card's displayed title agree on one title from one source (the plan's
+// leading `# H1`). These three patterns are a verbatim copy of
+// `sdk/react/src/internal/markdown-components.tsx`
+// (`ENCLOSING_MARKDOWN_FENCE_RE`, `ENCLOSING_BARE_FENCE_RE`, `LEADING_H1_RE`)
+// and MUST stay in sync with it — a fence-wrapped plan whose title the card
+// unwraps must slug to that same title here, never to the fallback.
+const ENCLOSING_MARKDOWN_FENCE_RE = /^(`{3,})[ \t]*(?:markdown|md)[ \t]*\r?\n([\s\S]*?)\r?\n\1[ \t]*$/i;
+const ENCLOSING_BARE_FENCE_RE = /^(`{3,})[ \t]*\r?\n([\s\S]*?)\r?\n\1[ \t]*$/;
+const LEADING_H1_RE = /^#[ \t]+(.+?)[ \t]*(?:\r?\n+|$)/;
+/**
+ * The plan's title: the leading `# H1` of the plan text, after the same
+ * plan-scoped enclosing-fence unwrap (tagged ```markdown``` or a bare ``` `)
+ * the document renderers apply. `undefined` when the plan has no leading H1.
+ */
+function extractPlanTitle(planText) {
+    const trimmed = planText.trim();
+    let body = trimmed;
+    const tagged = ENCLOSING_MARKDOWN_FENCE_RE.exec(trimmed);
+    if (tagged) {
+        body = tagged[2];
+    }
+    else {
+        const bare = ENCLOSING_BARE_FENCE_RE.exec(trimmed);
+        if (bare)
+            body = bare[2];
+    }
+    const h1 = LEADING_H1_RE.exec(body.trim());
+    return h1 ? h1[1] : undefined;
+}
+/**
+ * Strips a leading "Plan" LABEL from a title, e.g. `Plan: Create X` -> `Create
+ * X`. The separator (`:` or a dash) is REQUIRED: this removes a redundant label
+ * (a plan document already announces itself via the `.plan.md` suffix and the
+ * Plan card framing) without ever clipping a real title word — a bare `\bplan\b`
+ * would wrongly turn "Plan card UX cleanup" into "card UX cleanup".
+ *
+ * Deliberately runner/filename-only and NOT mirrored into the SDK's title
+ * extraction: display surfaces render the message's own `# H1` faithfully
+ * (`extractLeadingH1` is general-purpose and render-time-only), so the clean
+ * title is fixed at the source — the plan-mode prompt tells the model not to
+ * prefix titles with "Plan:". This strip is the durable-artifact safety net for
+ * when the model (or the enforcement-less Cursor harness) drifts.
+ */
+function stripPlanLabel(title) {
+    return title.replace(/^plan\s*[:\u2013\u2014-]\s*/i, "");
+}
+/**
+ * Slugifies a plan title into a filename-safe stem: lowercase, every run of
+ * non-alphanumerics collapsed to `-`, trimmed of leading/trailing `-`, and
+ * capped at {@link MAX_PLAN_SLUG_LENGTH}. Returns `""` for a title with no
+ * alphanumerics (e.g. only punctuation), which selects the fallback name.
+ */
+function slugifyPlanTitle(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, MAX_PLAN_SLUG_LENGTH)
+        .replace(/-+$/g, "");
+}
+/**
+ * Derives the plan artifact's filename from its text: `<slug>_<id>.plan.md`
+ * when the plan opens with a titled `# H1`, else a bare `<id>.plan.md`. The
+ * `<id>` is the first {@link PLAN_ID_LENGTH} hex of the content's SHA-256 — a
+ * user-facing discriminator for the shared download/list basename namespace,
+ * not a storage-uniqueness device (see the module doc).
+ */
+export function planArtifactName(planText) {
+    const id = createHash("sha256")
+        .update(planText, "utf-8")
+        .digest("hex")
+        .slice(0, PLAN_ID_LENGTH);
+    const title = extractPlanTitle(planText);
+    const slug = title ? slugifyPlanTitle(stripPlanLabel(title)) : "";
+    return slug.length > 0
+        ? `${slug}_${id}${PLAN_ARTIFACT_SUFFIX}`
+        : `${id}${PLAN_ARTIFACT_SUFFIX}`;
+}
+/**
+ * Sandbox path recorded on the artifact for a given filename. Routes under
+ * `.stigmer/` (the session platform dir), so it never pollutes the user's
+ * workspace, and a follow-up execution can reference it via workspace file
+ * refs if desired.
+ */
+export function planArtifactSandboxPath(name) {
+    return `.stigmer/plans/${name}`;
+}
+/**
+ * Returns the text of the last AI message in a completed turn's rows.
+ * Returns `undefined` when there is no AI message with content — the plan was
+ * empty and nothing should be published.
+ */
+export function extractFinalPlanText(rows) {
+    for (let i = rows.messages.length - 1; i >= 0; i--) {
+        const msg = rows.messages[i];
+        if (msg.type === MessageType.MESSAGE_AI && msg.content.trim().length > 0) {
+            return msg.content;
+        }
+    }
+    return undefined;
+}
+/**
+ * Publishes `planText` as a plan RunArtifact (named from its title —
+ * see {@link planArtifactName}) and registers it on `status.artifacts`.
+ * Idempotent: re-publishing replaces any existing plan artifact — matched by
+ * {@link isPlanArtifactName}, not exact name, so a re-plan whose title changed
+ * still supersedes rather than appends — preserving a single source of truth.
+ *
+ * Fire-and-forget by contract: a plan that fails to upload must never fail the
+ * execution. Errors are logged and swallowed.
+ */
+export async function publishPlanArtifact(opts) {
+    const { status, executionId, planText, artifactStorage } = opts;
+    if (planText.trim().length === 0) {
+        return;
+    }
+    try {
+        const content = Buffer.from(planText, "utf-8");
+        const contentHash = createHash("sha256").update(content).digest("hex");
+        const name = planArtifactName(planText);
+        const storageKey = `artifacts/${executionId}/${name}`;
+        await artifactStorage.upload(storageKey, content, "text/markdown");
+        const artifact = create(RunArtifactSchema, {
+            name,
+            sandboxPath: planArtifactSandboxPath(name),
+            kind: RunArtifactKind.FILE,
+            sizeBytes: BigInt(content.length),
+            storageKey,
+            createdAt: utcTimestamp(),
+            contentHash,
+        });
+        const existingIdx = status.artifacts.findIndex((a) => isPlanArtifactName(a.name));
+        if (existingIdx >= 0) {
+            status.artifacts[existingIdx] = artifact;
+        }
+        else {
+            status.artifacts.push(artifact);
+        }
+        console.log(`[plan-artifact] execution=${executionId} — published ${name} ` +
+            `(${content.length} bytes, hash=${contentHash.slice(0, 12)})`);
+    }
+    catch (err) {
+        console.warn(`[plan-artifact] execution=${executionId} — ` +
+            `failed to publish plan (non-fatal): ${err}`);
+    }
+}
+//# sourceMappingURL=plan-artifact.js.map

package/dist/shared/plan-artifact.js.map

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

package/dist/shared/plan-mode-permissions.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The Plan-mode filesystem permission rules — the enforcement twin of
+ * `plan-mode-prompt.ts` (which carries the instruction half of the contract).
+ *
+ * Plan mode's policy is: reads anywhere in the workspace, writes nowhere.
+ * Only the write half needs a RULE. The read boundary that issue #528 built
+ * out of rules (workspace read-allow + read-deny, glob-escaped real root) is
+ * now STRUCTURAL: every native-harness backend is virtual-rooted
+ * (`virtualMode: true` — see cas-capture-backend.ts, issue #754), so every
+ * path a tool can express resolves inside the workspace root and traversal
+ * is rejected at resolution. A rule cannot widen that, and no workspace-root
+ * glob is needed to narrow it — which also retires the whole
+ * special-characters-in-the-root hazard (`escapeGlobLiteral` and its
+ * end-to-end matcher suite) that the real-path rules carried.
+ *
+ * Paths in these rules are VIRTUAL: "/" is the workspace root, matched by
+ * micromatch against the raw tool-call path (dot:true) after the
+ * path-normalization middleware has canonicalized it (relative → "/"-rooted;
+ * see middleware/path-normalization.ts). The legitimate platform-dir reads
+ * (skills, attachments, the approved plan) keep working exactly as before:
+ * they are addressed through the `{workspace}/.stigmer` symlink
+ * (shared/workspace/stigmer-link.ts), an in-root path string in either
+ * dialect.
+ *
+ * Applied in execute-deep-agent/turn-setup.ts to the parent graph AND threaded
+ * into every compiled sub-agent graph: deepagents' parent-permission
+ * inheritance covers only spec-style sub-agents, and ours are pre-built
+ * CompiledSubAgents, so each sub-agent graph must carry the rules itself
+ * (issue #255). Kept as its own side-effect-free module so tests can pin the
+ * production rules without dragging in the engine build's import graph.
+ *
+ * Invariant: never combine these rules with a shell-capable (sandbox)
+ * backend — deepagents rejects that pairing at graph construction (see the
+ * cas-capture-backend.ts header). Plan mode guarantees it by construction:
+ * it is the mode that clears `shellEnv`, and `shellEnv` is the single switch
+ * for shell capability on both the parent and sub-agent backends.
+ */
+import type { FilesystemPermission } from "deepagents";
+/**
+ * Build the plan-mode rule set. One rule IS the policy: writes denied
+ * everywhere ("/**" is every virtual path; deepagents evaluates
+ * first-match-wins with a permissive default, so reads stay allowed —
+ * workspace-confined structurally, not by rule).
+ *
+ * Deliberately parameterless: the pre-#754 signature took the workspace root
+ * to build a real-path read fence; resurrecting a root-derived rule would
+ * silently mismatch the virtual dialect the enforcement now sees.
+ */
+export declare function buildPlanModePermissions(): FilesystemPermission[];

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

@@ -0,0 +1,51 @@
+/**
+ * The Plan-mode filesystem permission rules — the enforcement twin of
+ * `plan-mode-prompt.ts` (which carries the instruction half of the contract).
+ *
+ * Plan mode's policy is: reads anywhere in the workspace, writes nowhere.
+ * Only the write half needs a RULE. The read boundary that issue #528 built
+ * out of rules (workspace read-allow + read-deny, glob-escaped real root) is
+ * now STRUCTURAL: every native-harness backend is virtual-rooted
+ * (`virtualMode: true` — see cas-capture-backend.ts, issue #754), so every
+ * path a tool can express resolves inside the workspace root and traversal
+ * is rejected at resolution. A rule cannot widen that, and no workspace-root
+ * glob is needed to narrow it — which also retires the whole
+ * special-characters-in-the-root hazard (`escapeGlobLiteral` and its
+ * end-to-end matcher suite) that the real-path rules carried.
+ *
+ * Paths in these rules are VIRTUAL: "/" is the workspace root, matched by
+ * micromatch against the raw tool-call path (dot:true) after the
+ * path-normalization middleware has canonicalized it (relative → "/"-rooted;
+ * see middleware/path-normalization.ts). The legitimate platform-dir reads
+ * (skills, attachments, the approved plan) keep working exactly as before:
+ * they are addressed through the `{workspace}/.stigmer` symlink
+ * (shared/workspace/stigmer-link.ts), an in-root path string in either
+ * dialect.
+ *
+ * Applied in execute-deep-agent/turn-setup.ts to the parent graph AND threaded
+ * into every compiled sub-agent graph: deepagents' parent-permission
+ * inheritance covers only spec-style sub-agents, and ours are pre-built
+ * CompiledSubAgents, so each sub-agent graph must carry the rules itself
+ * (issue #255). Kept as its own side-effect-free module so tests can pin the
+ * production rules without dragging in the engine build's import graph.
+ *
+ * Invariant: never combine these rules with a shell-capable (sandbox)
+ * backend — deepagents rejects that pairing at graph construction (see the
+ * cas-capture-backend.ts header). Plan mode guarantees it by construction:
+ * it is the mode that clears `shellEnv`, and `shellEnv` is the single switch
+ * for shell capability on both the parent and sub-agent backends.
+ */
+/**
+ * Build the plan-mode rule set. One rule IS the policy: writes denied
+ * everywhere ("/**" is every virtual path; deepagents evaluates
+ * first-match-wins with a permissive default, so reads stay allowed —
+ * workspace-confined structurally, not by rule).
+ *
+ * Deliberately parameterless: the pre-#754 signature took the workspace root
+ * to build a real-path read fence; resurrecting a root-derived rule would
+ * silently mismatch the virtual dialect the enforcement now sees.
+ */
+export function buildPlanModePermissions() {
+    return [{ operations: ["write"], paths: ["/**"], mode: "deny" }];
+}
+//# sourceMappingURL=plan-mode-permissions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plan-mode-permissions.js","sourceRoot":"","sources":["../../src/shared/plan-mode-permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAIH;;;;;;;;;GASG;AACH,MAAM,UAAU,wBAAwB;IACtC,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;AACnE,CAAC"}

package/dist/shared/plan-mode-prompt.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 declare const PLAN_MODE_DIRECTIVE: string;