@tangle-network/agent-profile-materialize 0.18.1 → 0.19.1

package/dist/candidate-types.d.ts

@@ -17,6 +17,10 @@ export interface AgentCandidateWorkspacePlanReceipt {
     appendSystemPrompt?: AgentCandidateConfigValue;
     unsupported: Unsupported[];
 }
+export interface ApplyAgentCandidateWorkspacePlanOptions {
+    /** Absolute private agent directory required by agent-root plan files. */
+    agentDir?: string;
+}
 export interface MaterializeCandidateProfileOptions {
     /** Exact text fetched from pinned resource refs, keyed by declared SHA-256. */
     resolvedResources?: ReadonlyMap<Sha256Digest, string>;

package/dist/candidate.d.ts

@@ -1,9 +1,9 @@
 import type { AgentCandidateProfile, AgentCandidateProfileApplication } from "@tangle-network/agent-interface";
-import type { AgentCandidateWorkspacePlan, AgentCandidateWorkspacePlanReceipt, MaterializeCandidateProfileOptions } from "./candidate-types.js";
+import type { AgentCandidateWorkspacePlan, AgentCandidateWorkspacePlanReceipt, ApplyAgentCandidateWorkspacePlanOptions, MaterializeCandidateProfileOptions } from "./candidate-types.js";
 import type { HarnessId } from "./harness.js";
 export declare function materializeCandidateProfile(profile: AgentCandidateProfile, harness: HarnessId, opts?: MaterializeCandidateProfileOptions): AgentCandidateWorkspacePlan;
 /**
  * Apply a candidate plan and return its spawn values together with captured
  * canonical evidence. No caller needs to re-serialize or reinterpret the plan.
  */
-export declare function applyAgentCandidateWorkspacePlan(plan: AgentCandidateWorkspacePlan, workspaceDir: string, targetWorkspace: AgentCandidateProfileApplication["targetWorkspace"]): AgentCandidateWorkspacePlanReceipt;
+export declare function applyAgentCandidateWorkspacePlan(plan: AgentCandidateWorkspacePlan, workspaceDir: string, targetWorkspace: AgentCandidateProfileApplication["targetWorkspace"], options?: ApplyAgentCandidateWorkspacePlanOptions): AgentCandidateWorkspacePlanReceipt;

package/dist/candidate.js

@@ -29,6 +29,7 @@ export function materializeCandidateProfile(profile, harness, opts = {}) {
     };
     const classicPlan = materializeProfile(classicProfile, harness, {
         binds: opts.binds,
+        ...(harness === "pi" ? { instructionsRoot: "agent" } : {}),
     });
     // Canonical candidate evidence has no field for a launcher-addressed binding.
     // Refuse that shape instead of returning a candidate plan whose receipt would
@@ -58,7 +59,7 @@ export function materializeCandidateProfile(profile, harness, opts = {}) {
  * Apply a candidate plan and return its spawn values together with captured
  * canonical evidence. No caller needs to re-serialize or reinterpret the plan.
  */
-export function applyAgentCandidateWorkspacePlan(plan, workspaceDir, targetWorkspace) {
+export function applyAgentCandidateWorkspacePlan(plan, workspaceDir, targetWorkspace, options = {}) {
     assertWorkspacePlanSupported(plan);
     const profilePlan = captureAgentCandidateProfilePlan(plan);
     const activationFiles = normalizePlanFiles(plan.files).map((file) => ({
@@ -85,12 +86,14 @@ export function applyAgentCandidateWorkspacePlan(plan, workspaceDir, targetWorks
         flags: plan.flags.map(candidatePublicString),
         ...promptIntentFields(plan, candidatePublicString),
         unsupported: plan.unsupported,
-    }, workspaceDir);
+    }, workspaceDir, { agentDir: options.agentDir });
     return {
         profileActivation,
         application: {
             planDigest: profilePlan.digest,
             targetWorkspace,
+            // The candidate execution-plan contract lists workspace mounts here.
+            // Agent-root placement remains explicit in profile-plan material.files.
             mountPaths: applied.written,
         },
         env: { ...plan.env },

package/dist/harness.d.ts

@@ -9,6 +9,8 @@ export declare const OPENCODE_CONFIG_SCHEMA = "https://opencode.ai/config.json";
 export declare const OPENCODE_PRIMARY_AGENT_PREFIX = "tangle-profile-";
 export declare const CLAUDE_SETTINGS_PATH = ".tangle/claude-settings.json";
 export declare function harnessAutoLoadsContextFile(harness: HarnessId): boolean;
+/** Whether the shared materializer may place its context file in the harness agent directory. */
+export declare function harnessAutoLoadsAgentContextFile(harness: HarnessId): boolean;
 /**
  * The project context file this harness reads from cwd — its stable, documented
  * ALWAYS-LOADED surface. Exported so a caller lowering additive context (e.g. a
@@ -56,28 +58,74 @@ export declare const CONTEXT_FILE: Record<HarnessId, string>;
  * bounded by the names being ones no harness or user convention uses.
  */
 export declare const MATERIALIZER_RESERVED_PATHS: ReadonlySet<string>;
+/**
+ * The context files this package owns by MARKER rather than by name:
+ * `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `HERMES.md`.
+ *
+ * Each is a documented name a repository can already carry, so the name proves
+ * nothing. A generated one carries the line {@link markMaterializerContextFile}
+ * writes, and only that line lets the next materialization replace it.
+ *
+ * opencode's context file is absent because it is a RESERVED name this package
+ * invented, already owned by the name alone.
+ */
+export declare const MATERIALIZER_CONTEXT_PATHS: ReadonlySet<string>;
 /**
  * The paths whose generated content is wholly this package's output, per
- * {@link PlanFile.ownership}: the reserved names plus `opencode.json`, which
- * carries only the registrations this package generates from the profile.
+ * {@link PlanFile.ownership}: the reserved names, the context files, and
+ * `opencode.json`, which carries only the registrations this package generates
+ * from the profile.
+ *
+ * `opencode.json` and every context file is a documented name a user repository
+ * can carry, so the name alone proves nothing and a profile resource may still
+ * mount one. An existing file there is replaced only when
+ * {@link isMaterializerOutput} recognizes its bytes as this package's own
+ * earlier output.
  *
- * `opencode.json` is a documented name a user repository can carry, so the
- * name alone proves nothing and a profile resource may still mount it. An
- * existing file there is replaced only when {@link isMaterializerOutput}
- * recognizes its bytes as this package's own earlier output.
+ * Deliberately absent: `.gemini/system.md`, the file `prompt.systemPrompt`
+ * lowers to. The line a marker would have to add is the reason. A REPLACEMENT
+ * is the caller's exact bytes and this package may add none of its own, so that
+ * path keeps refusing. A context file carries `prompt.instructions`, which this
+ * package already composes — it joins the blocks and appends the final newline
+ * — so one more composed line is inside the same authority.
  *
- * Deliberately absent: `.gemini/system.md` (gemini's own documented name),
- * `GEMINI.md`, `CLAUDE.md`, `AGENTS.md`. A user's repository can carry any of
- * those with content this package cannot tell from its own, and clobbering
- * one is worse than refusing the turn.
+ * That line, not "which channel the harness reads it on", is what separates the
+ * two. `GEMINI.md` is owned even though gemini lowers its context file into the
+ * system-prompt position as an ADDITION ({@link appendSystemPromptRefusal}),
+ * because the intent it carries is still instructions this package composed.
  */
 export declare const MATERIALIZER_OWNED_PATHS: ReadonlySet<string>;
 /** Mark one generated native agent file without changing its harness meaning. */
 export declare function markMaterializerSubagent(relPath: string, content: string): string;
+/**
+ * Mark one generated context file so the NEXT materialization can prove this
+ * package wrote the bytes it is about to replace.
+ *
+ * The marker is an HTML comment on line 1. CommonMark closes an HTML block at
+ * the line holding `-->`, so every instruction below it parses exactly as it
+ * did without the line, and the line itself states no instruction. It is one
+ * more line this package composes into a file it already composes: it goes on
+ * a context file, which carries `prompt.instructions`, and NEVER on a
+ * system-prompt REPLACEMENT, whose bytes are the caller's exact text
+ * (`.gemini/system.md`; `.codex/system-prompt.md` is a reserved name this
+ * package invented and needs no marker to be owned).
+ *
+ * It carries the digest of everything BELOW it, which the subagent marker does
+ * not need. `CLAUDE.md` is claude-code's own memory file and the agent appends
+ * to it mid-session, so a bare marker would still sit on line 1 of a file the
+ * agent has since rewritten. Ownership has to mean "these are still our bytes",
+ * not "this package wrote here once".
+ *
+ * A reserved context path — opencode's invented instruction file — is returned
+ * unchanged: its NAME already proves the provenance, and nothing else may mount
+ * there.
+ */
+export declare function markMaterializerContextFile(relPath: string, content: string): string;
 /**
  * Whether a generated file occupies a path that the profile materializer owns.
  *
- * Generated native agent files come from the active profile.
+ * Generated native agent files and generated context files come from the active
+ * profile.
  * The active profile must replace the prior profile version at the same path.
  * Otherwise, a profile update stops every resumed session before launch.
  * Explicit resources at these paths stay shared.
@@ -90,9 +138,11 @@ export declare const OPENCODE_CONFIG_KEYS: ReadonlySet<string>;
 /**
  * Whether the file already at owned path `relPath` is this package's own
  * earlier output. A reserved name proves that by itself. Native agent files
- * require the generated marker. An exact unmarked copy of the planned file is
- * adopted once for upgrades from materializer versions without that marker.
- * `undefined` content means no regular file is there.
+ * require the generated marker; context files require the marker AND the body
+ * digest it commits to, so an agent that appended to its memory file is no
+ * longer holding this package's bytes. An exact unmarked copy of the planned
+ * file is adopted once for upgrades from materializer versions without that
+ * marker. `undefined` content means no regular file is there.
  *
  * An `opencode.json` this package wrote holds the opencode schema id, only the
  * keys this package writes, and only instruction paths this package invented.

package/dist/harness.js

@@ -29,6 +29,13 @@ export function harnessAutoLoadsContextFile(harness) {
     assertMaterializerHarness(harness);
     return harness !== "opencode";
 }
+/** Whether the shared materializer may place its context file in the harness agent directory. */
+export function harnessAutoLoadsAgentContextFile(harness) {
+    assertMaterializerHarness(harness);
+    // Prime uses the fork-specific materializePrimeProfileControls path. It
+    // does not consume the shared agent-root plan produced by this predicate.
+    return harness === "pi";
+}
 /**
  * The project context file this harness reads from cwd — its stable, documented
  * ALWAYS-LOADED surface. Exported so a caller lowering additive context (e.g. a
@@ -123,27 +130,54 @@ export const MATERIALIZER_RESERVED_PATHS = new Set([
     OPENCODE_APPEND_SYSTEM_PROMPT_FILE,
     CONTEXT_FILE.opencode,
 ]);
+/** Every path any harness reads as its project context file. */
+const CONTEXT_FILE_PATHS = new Set(Object.values(CONTEXT_FILE));
+/**
+ * The context files this package owns by MARKER rather than by name:
+ * `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `HERMES.md`.
+ *
+ * Each is a documented name a repository can already carry, so the name proves
+ * nothing. A generated one carries the line {@link markMaterializerContextFile}
+ * writes, and only that line lets the next materialization replace it.
+ *
+ * opencode's context file is absent because it is a RESERVED name this package
+ * invented, already owned by the name alone.
+ */
+export const MATERIALIZER_CONTEXT_PATHS = new Set([...CONTEXT_FILE_PATHS].filter((path) => !MATERIALIZER_RESERVED_PATHS.has(path)));
 /**
  * The paths whose generated content is wholly this package's output, per
- * {@link PlanFile.ownership}: the reserved names plus `opencode.json`, which
- * carries only the registrations this package generates from the profile.
+ * {@link PlanFile.ownership}: the reserved names, the context files, and
+ * `opencode.json`, which carries only the registrations this package generates
+ * from the profile.
+ *
+ * `opencode.json` and every context file is a documented name a user repository
+ * can carry, so the name alone proves nothing and a profile resource may still
+ * mount one. An existing file there is replaced only when
+ * {@link isMaterializerOutput} recognizes its bytes as this package's own
+ * earlier output.
  *
- * `opencode.json` is a documented name a user repository can carry, so the
- * name alone proves nothing and a profile resource may still mount it. An
- * existing file there is replaced only when {@link isMaterializerOutput}
- * recognizes its bytes as this package's own earlier output.
+ * Deliberately absent: `.gemini/system.md`, the file `prompt.systemPrompt`
+ * lowers to. The line a marker would have to add is the reason. A REPLACEMENT
+ * is the caller's exact bytes and this package may add none of its own, so that
+ * path keeps refusing. A context file carries `prompt.instructions`, which this
+ * package already composes — it joins the blocks and appends the final newline
+ * — so one more composed line is inside the same authority.
  *
- * Deliberately absent: `.gemini/system.md` (gemini's own documented name),
- * `GEMINI.md`, `CLAUDE.md`, `AGENTS.md`. A user's repository can carry any of
- * those with content this package cannot tell from its own, and clobbering
- * one is worse than refusing the turn.
+ * That line, not "which channel the harness reads it on", is what separates the
+ * two. `GEMINI.md` is owned even though gemini lowers its context file into the
+ * system-prompt position as an ADDITION ({@link appendSystemPromptRefusal}),
+ * because the intent it carries is still instructions this package composed.
  */
 export const MATERIALIZER_OWNED_PATHS = new Set([
     ...MATERIALIZER_RESERVED_PATHS,
+    ...MATERIALIZER_CONTEXT_PATHS,
     OPENCODE_CONFIG_FILE,
 ]);
 const MATERIALIZER_SUBAGENT_PATH = /^(?:(?:\.claude|\.opencode|\.gemini)\/agents\/[a-z0-9][a-z0-9_-]*\.md|\.codex\/agents\/[a-z0-9][a-z0-9_-]*\.toml)$/u;
-const MATERIALIZER_SUBAGENT_MARKER = "# tangle-agent-profile-materialize: generated";
+/** The one provenance token every generated-file marker carries. */
+const MATERIALIZER_MARKER = "tangle-agent-profile-materialize: generated";
+const MATERIALIZER_SUBAGENT_MARKER = `# ${MATERIALIZER_MARKER}`;
+const MATERIALIZER_CONTEXT_MARKER_NOTE = "do not edit; the next profile materialization replaces this file";
 function materializerSubagentMarkerPrefix(relPath) {
     return relPath.endsWith(".toml")
         ? `${MATERIALIZER_SUBAGENT_MARKER}\n`
@@ -162,10 +196,58 @@ export function markMaterializerSubagent(relPath, content) {
     }
     return `${materializerSubagentMarkerPrefix(relPath)}${content.slice(4)}`;
 }
+/** The marker line a generated context file whose body is `body` carries. */
+function materializerContextMarker(body) {
+    const digest = createHash("sha256").update(body, "utf8").digest("hex");
+    return `<!-- ${MATERIALIZER_MARKER} sha256:${digest}; ${MATERIALIZER_CONTEXT_MARKER_NOTE} -->`;
+}
+/**
+ * Mark one generated context file so the NEXT materialization can prove this
+ * package wrote the bytes it is about to replace.
+ *
+ * The marker is an HTML comment on line 1. CommonMark closes an HTML block at
+ * the line holding `-->`, so every instruction below it parses exactly as it
+ * did without the line, and the line itself states no instruction. It is one
+ * more line this package composes into a file it already composes: it goes on
+ * a context file, which carries `prompt.instructions`, and NEVER on a
+ * system-prompt REPLACEMENT, whose bytes are the caller's exact text
+ * (`.gemini/system.md`; `.codex/system-prompt.md` is a reserved name this
+ * package invented and needs no marker to be owned).
+ *
+ * It carries the digest of everything BELOW it, which the subagent marker does
+ * not need. `CLAUDE.md` is claude-code's own memory file and the agent appends
+ * to it mid-session, so a bare marker would still sit on line 1 of a file the
+ * agent has since rewritten. Ownership has to mean "these are still our bytes",
+ * not "this package wrote here once".
+ *
+ * A reserved context path — opencode's invented instruction file — is returned
+ * unchanged: its NAME already proves the provenance, and nothing else may mount
+ * there.
+ */
+export function markMaterializerContextFile(relPath, content) {
+    if (!CONTEXT_FILE_PATHS.has(relPath)) {
+        throw new Error(`Not a harness context file: ${relPath}`);
+    }
+    if (!MATERIALIZER_CONTEXT_PATHS.has(relPath))
+        return content;
+    return `${materializerContextMarker(content)}\n${content}`;
+}
+/**
+ * Whether `existing` is a context file this package wrote and nothing edited
+ * afterwards: line 1 is exactly the marker computed over every byte below it.
+ */
+function isMarkedContextOutput(existing) {
+    const lineEnd = existing.indexOf("\n");
+    if (lineEnd === -1)
+        return false;
+    return (existing.slice(0, lineEnd) ===
+        materializerContextMarker(existing.slice(lineEnd + 1)));
+}
 /**
  * Whether a generated file occupies a path that the profile materializer owns.
  *
- * Generated native agent files come from the active profile.
+ * Generated native agent files and generated context files come from the active
+ * profile.
  * The active profile must replace the prior profile version at the same path.
  * Otherwise, a profile update stops every resumed session before launch.
  * Explicit resources at these paths stay shared.
@@ -187,9 +269,11 @@ export const OPENCODE_CONFIG_KEYS = new Set([
 /**
  * Whether the file already at owned path `relPath` is this package's own
  * earlier output. A reserved name proves that by itself. Native agent files
- * require the generated marker. An exact unmarked copy of the planned file is
- * adopted once for upgrades from materializer versions without that marker.
- * `undefined` content means no regular file is there.
+ * require the generated marker; context files require the marker AND the body
+ * digest it commits to, so an agent that appended to its memory file is no
+ * longer holding this package's bytes. An exact unmarked copy of the planned
+ * file is adopted once for upgrades from materializer versions without that
+ * marker. `undefined` content means no regular file is there.
  *
  * An `opencode.json` this package wrote holds the opencode schema id, only the
  * keys this package writes, and only instruction paths this package invented.
@@ -216,6 +300,23 @@ export function isMaterializerOutput(relPath, content, plannedContent) {
             : `---\n${plannedContent.slice(markerPrefix.length)}`;
         return existing === legacyContent;
     }
+    if (MATERIALIZER_CONTEXT_PATHS.has(relPath)) {
+        const existing = content();
+        if (existing === undefined)
+            return false;
+        if (isMarkedContextOutput(existing))
+            return true;
+        // A workspace materialized before this marker existed carries the body
+        // alone. Adopt it once, and only when it is byte-identical to the body this
+        // plan writes, so upgrading the package does not turn every resumed session
+        // into a refusal. A body that differs is either a user's file or an earlier
+        // profile's, and neither can be told apart without the marker.
+        if (plannedContent === undefined)
+            return false;
+        if (!isMarkedContextOutput(plannedContent))
+            return false;
+        return existing === plannedContent.slice(plannedContent.indexOf("\n") + 1);
+    }
     if (relPath !== OPENCODE_CONFIG_FILE)
         return false;
     const bytes = content();
@@ -280,3 +381,4 @@ export function skillDirForHarness(harness) {
     assertMaterializerHarness(harness);
     return HARNESS_SKILL_DIRS[harness];
 }
+import { createHash } from "node:crypto";

package/dist/index.d.ts

@@ -1,18 +1,18 @@
 /** Stable public facade for profile materialization and workspace application. */
 export { applyAgentCandidateWorkspacePlan, materializeCandidateProfile, } from "./candidate.js";
-export type { AgentCandidateWorkspacePlan, AgentCandidateWorkspacePlanReceipt, MaterializeCandidateProfileOptions, } from "./candidate-types.js";
+export type { AgentCandidateWorkspacePlan, AgentCandidateWorkspacePlanReceipt, ApplyAgentCandidateWorkspacePlanOptions, MaterializeCandidateProfileOptions, } from "./candidate-types.js";
 export { OPENCODE_NATIVE_TOOL_IDS, openCodeNativeToolId, } from "./control-maps.js";
 export type { HarnessId } from "./harness.js";
-export { HARNESS_SKILL_DIRS, harnessAutoLoadsContextFile, harnessContextFile, isMaterializerHarness, MATERIALIZER_HARNESSES, skillDirForHarness, } from "./harness.js";
+export { HARNESS_SKILL_DIRS, harnessAutoLoadsAgentContextFile, harnessAutoLoadsContextFile, harnessContextFile, isMaterializerHarness, MATERIALIZER_CONTEXT_PATHS, MATERIALIZER_HARNESSES, markMaterializerContextFile, skillDirForHarness, } from "./harness.js";
 export type { OpenCodeMcpConfig } from "./mcp.js";
 export { openCodeMcpConfig } from "./mcp.js";
 export { modelIdsMatch, qualifyModelId, unqualifyModelId, } from "./model-id.js";
-export { buildPiModelsConfig, buildPiModelsConfigFile, PI_MODELS_CONFIG_PATH, type PiModelsConfigFile, type PiModelsConfigInput, } from "./pi-models-config.js";
+export { buildPiModelsConfig, buildPiModelsConfigFile, PI_MODELS_CONFIG_PATH, type PiModelsConfigFile, type PiModelsConfigInput, type PiRuntimePaths, resolvePiRuntimePaths, } from "./pi-models-config.js";
 export { applyWorkspacePlan, applyWorkspacePlanWithSecretProvider, } from "./plan-application.js";
 export { agentCandidateProfilePlanMaterial, canonicalizeAgentCandidateProfilePlan, captureAgentCandidateProfilePlan, hashWorkspacePlan, } from "./plan-digest.js";
 export { takeSystemPromptBinding } from "./plan-prompt.js";
 export { assertWorkspacePlanSupported, enforceWorkspacePlanSupport, } from "./plan-support.js";
-export type { ApplyWorkspacePlanOptions, BindableLaunchControl, ExecutorSystemPromptBinding, PlanFile, PlanFileSecretSlot, PlanRequirement, SkippableDimension, Unsupported, WorkspacePlan, WorkspacePlanApplication, WorkspacePlanArgument, WorkspacePlanArgumentTemplate, WorkspacePlanConfigValue, WorkspacePlanReceipt, WorkspacePlanSecretSegment, WorkspacePlanSpawnInputs, WorkspacePlanSystemPromptBinding, } from "./plan-types.js";
+export type { ApplyWorkspacePlanOptions, BindableLaunchControl, ExecutorSystemPromptBinding, PlanFile, PlanFileRoot, PlanFileSecretSlot, PlanRequirement, SkippableDimension, Unsupported, WorkspacePlan, WorkspacePlanApplication, WorkspacePlanArgument, WorkspacePlanArgumentTemplate, WorkspacePlanConfigValue, WorkspacePlanReceipt, WorkspacePlanSecretSegment, WorkspacePlanSpawnInputs, WorkspacePlanSystemPromptBinding, WorkspacePlanWrittenFile, } from "./plan-types.js";
 export { BINDABLE_LAUNCH_CONTROLS, EXECUTOR_SYSTEM_PROMPT_BINDINGS, isExecutorSystemPromptBinding, isSkippableDimension, SKIPPABLE_DIMENSIONS, WorkspacePlanCleanupError, } from "./plan-types.js";
 export type { PrimeMaterializeOptions } from "./prime-agent-dir.js";
 export { materializePrimeProfileControls, prunePrimeProfileMaterial, seedPrimeProfileSubagents, writePrimeAgentFile, } from "./prime-agent-dir.js";

package/dist/index.js

@@ -1,10 +1,10 @@
 /** Stable public facade for profile materialization and workspace application. */
 export { applyAgentCandidateWorkspacePlan, materializeCandidateProfile, } from "./candidate.js";
 export { OPENCODE_NATIVE_TOOL_IDS, openCodeNativeToolId, } from "./control-maps.js";
-export { HARNESS_SKILL_DIRS, harnessAutoLoadsContextFile, harnessContextFile, isMaterializerHarness, MATERIALIZER_HARNESSES, skillDirForHarness, } from "./harness.js";
+export { HARNESS_SKILL_DIRS, harnessAutoLoadsAgentContextFile, harnessAutoLoadsContextFile, harnessContextFile, isMaterializerHarness, MATERIALIZER_CONTEXT_PATHS, MATERIALIZER_HARNESSES, markMaterializerContextFile, skillDirForHarness, } from "./harness.js";
 export { openCodeMcpConfig } from "./mcp.js";
 export { modelIdsMatch, qualifyModelId, unqualifyModelId, } from "./model-id.js";
-export { buildPiModelsConfig, buildPiModelsConfigFile, PI_MODELS_CONFIG_PATH, } from "./pi-models-config.js";
+export { buildPiModelsConfig, buildPiModelsConfigFile, PI_MODELS_CONFIG_PATH, resolvePiRuntimePaths, } from "./pi-models-config.js";
 export { applyWorkspacePlan, applyWorkspacePlanWithSecretProvider, } from "./plan-application.js";
 export { agentCandidateProfilePlanMaterial, canonicalizeAgentCandidateProfilePlan, captureAgentCandidateProfilePlan, hashWorkspacePlan, } from "./plan-digest.js";
 export { takeSystemPromptBinding } from "./plan-prompt.js";

package/dist/pi-models-config.d.ts

@@ -1,9 +1,3 @@
-/**
- * One custom-model shape for upstream Pi and the Prime fork.
- *
- * Both agents read the same `models.json` provider schema.
- * Callers own the file lifecycle, but they must not build different payloads.
- */
 export interface PiModelsConfigInput {
     /** Provider key in models.json and the matching `--provider` value. */
     providerName: string;
@@ -25,6 +19,12 @@ export interface PiModelsConfigFile {
     mode: number;
 }
 export declare const PI_MODELS_CONFIG_PATH = ".pi/agent/models.json";
+export interface PiRuntimePaths {
+    agentDir: string;
+    sessionDir: string;
+}
+/** Resolve Pi's private roots from the one runtime HOME supplied to Pi. */
+export declare function resolvePiRuntimePaths(runtimeHome: string): PiRuntimePaths;
 export declare function buildPiModelsConfig(input: PiModelsConfigInput): Record<string, unknown>;
 /** Build the owner-only Pi file used by headless and interactive processes. */
 export declare function buildPiModelsConfigFile(input: PiModelsConfigInput): PiModelsConfigFile;

package/dist/pi-models-config.js

@@ -1,4 +1,20 @@
+/**
+ * One custom-model shape for upstream Pi and the Prime fork.
+ *
+ * Both agents read the same `models.json` provider schema.
+ * Callers own the file lifecycle, but they must not build different payloads.
+ */
+import path from "node:path";
 export const PI_MODELS_CONFIG_PATH = ".pi/agent/models.json";
+/** Resolve Pi's private roots from the one runtime HOME supplied to Pi. */
+export function resolvePiRuntimePaths(runtimeHome) {
+    const home = path.resolve(runtimeHome);
+    const agentDir = path.dirname(path.join(home, PI_MODELS_CONFIG_PATH));
+    return {
+        agentDir,
+        sessionDir: path.join(agentDir, "sessions"),
+    };
+}
 const DEFAULT_CONTEXT_WINDOW = 128_000;
 export function buildPiModelsConfig(input) {
     for (const [field, value] of [

package/dist/plan-digest.js

@@ -2,6 +2,7 @@ export const sha256 = (value) => createHash("sha256").update(value, "utf8").dige
 export function hashWorkspacePlan(plan) {
     const files = normalizePlanFiles(plan.files).map((file) => ({
         relPath: file.relPath,
+        ...(file.root === "workspace" ? {} : { root: file.root }),
         mode: file.mode,
         contentSha256: sha256(file.content),
         // Ownership decides whether re-application may replace the file, so two
@@ -42,20 +43,35 @@ export function hashWorkspacePlan(plan) {
 }
 /** Build the exact digest-free identity document required by agent-interface. */
 export function agentCandidateProfilePlanMaterial(plan) {
+    const files = normalizePlanFiles(plan.files);
+    const materialFiles = files.map((file) => ({
+        relPath: file.relPath,
+        mode: file.mode,
+        contentSha256: `sha256:${sha256(file.content)}`,
+        ...(file.root === "agent" ? { root: "agent" } : {}),
+    }));
     const material = {
         sourceProfileDigest: plan.sourceProfileDigest,
         harness: plan.harness,
-        files: normalizePlanFiles(plan.files).map((file) => ({
-            relPath: file.relPath,
-            mode: file.mode,
-            contentSha256: `sha256:${sha256(file.content)}`,
-        })),
+        // Interface 1 has the same candidate material shape without the optional
+        // root field. Keep the local file model richer, then validate against the
+        // installed peer schema at the compatibility boundary.
+        files: materialFiles,
         env: Object.fromEntries(Object.entries(plan.env).sort(([left], [right]) => compareStrings(left, right))),
         flags: [...plan.flags],
         ...promptIntentFields(plan, samePromptIntentValue),
         unsupported: [...plan.unsupported].sort((left, right) => compareStrings(`${left.dimension}\0${left.reason}`, `${right.dimension}\0${right.reason}`)),
     };
-    return agentCandidateProfilePlanMaterialSchema.parse(material);
+    const hasAgentRoot = materialFiles.some((file) => file.root === "agent");
+    if (!hasAgentRoot) {
+        return agentCandidateProfilePlanMaterialSchema.parse(material);
+    }
+    const parsed = agentCandidateProfilePlanMaterialSchema.safeParse(material);
+    if (!parsed.success) {
+        throw new Error("Agent-root candidate evidence requires @tangle-network/agent-interface >=2.1.1; " +
+            'the installed peer schema cannot preserve root:"agent". Upgrade the peer before applying this candidate plan.');
+    }
+    return parsed.data;
 }
 /**
  * Return the RFC 8785 UTF-8 bytes and SHA-256 identity of a candidate profile

package/dist/plan-normalize.d.ts

@@ -2,12 +2,17 @@ export declare function mergeJsonFiles(files: PlanFile[]): PlanFile[];
 export interface NormalizedPlanFile {
     relPath: string;
     content: string;
+    root: PlanFileRoot;
     mode: number;
     ownership: NonNullable<PlanFile["ownership"]>;
     secretSlots: PlanFileSecretSlot[];
 }
-export declare function valueAtJsonPath(root: unknown, path: readonly (string | number)[]): unknown;
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare function normalizePlanFileRoot(root: PlanFileRoot | undefined): PlanFileRoot;
+export declare function valueAtJsonPath(root: JsonValue, path: readonly (string | number)[]): JsonValue | undefined;
 export declare function normalizePlanFileSecretSlots(file: PlanFile): PlanFileSecretSlot[];
 export declare function normalizePlanFiles(files: PlanFile[]): NormalizedPlanFile[];
 export declare function normalizeWorkspacePlanArgument(value: WorkspacePlanArgument): WorkspacePlanArgument;
-import type { PlanFile, PlanFileSecretSlot, WorkspacePlanArgument } from "./plan-types.js";
+import type { PlanFile, PlanFileRoot, PlanFileSecretSlot, WorkspacePlanArgument } from "./plan-types.js";

package/dist/plan-normalize.js

@@ -1,9 +1,11 @@
 export function mergeJsonFiles(files) {
     const byPath = new Map();
     for (const f of files) {
-        const prev = byPath.get(f.relPath);
+        const root = normalizePlanFileRoot(f.root);
+        const identity = `${root}\0${f.relPath}`;
+        const prev = byPath.get(identity);
         if (!prev) {
-            byPath.set(f.relPath, f);
+            byPath.set(identity, f);
             continue;
         }
         if (f.relPath.endsWith(".json")) {
@@ -20,7 +22,7 @@ export function mergeJsonFiles(files) {
                     ...(f.secretSlots ?? []),
                 ];
                 const { secretSlots: _previousSecretSlots, ...previousFile } = prev;
-                byPath.set(f.relPath, {
+                byPath.set(identity, {
                     ...previousFile,
                     content: JSON.stringify(merged, null, 2),
                     ...(secretSlots.length > 0 ? { mode: PRIVATE_FILE_MODE } : {}),
@@ -32,10 +34,17 @@ export function mergeJsonFiles(files) {
                 /* fall through to last-wins */
             }
         }
-        byPath.set(f.relPath, f); // non-JSON or parse-fail: last wins
+        byPath.set(identity, f); // non-JSON or parse-fail: last wins
     }
     return [...byPath.values()];
 }
+export function normalizePlanFileRoot(root) {
+    if (root === undefined || root === "workspace")
+        return "workspace";
+    if (root === "agent")
+        return root;
+    throw new Error(`Unsupported workspace plan file root: ${String(root)}`);
+}
 export function valueAtJsonPath(root, path) {
     let current = root;
     for (const segment of path) {
@@ -94,11 +103,13 @@ export function normalizePlanFiles(files) {
     const seen = new Set();
     return files
         .map((file) => {
+        const root = normalizePlanFileRoot(file.root);
         const relPath = normalizeWorkspaceRelativePath(file.relPath);
-        if (seen.has(relPath)) {
-            throw new Error(`Duplicate workspace plan file: ${relPath}`);
+        const identity = `${root}\0${relPath}`;
+        if (seen.has(identity)) {
+            throw new Error(`Duplicate ${root} plan file: ${relPath}`);
         }
-        seen.add(relPath);
+        seen.add(identity);
         if (typeof file.content !== "string") {
             throw new Error(`Workspace file content must be a string: ${relPath}`);
         }
@@ -110,12 +121,13 @@ export function normalizePlanFiles(files) {
         return {
             relPath,
             content: file.content,
+            root,
             mode,
             ownership: file.ownership ?? "shared",
             secretSlots,
         };
     })
-        .sort((a, b) => compareStrings(a.relPath, b.relPath));
+        .sort((a, b) => compareStrings(`${a.root}\0${a.relPath}`, `${b.root}\0${b.relPath}`));
 }
 export function normalizeWorkspacePlanArgument(value) {
     if (typeof value === "string")

package/dist/plan-types.d.ts

@@ -1,7 +1,11 @@
 export type { HarnessId } from "./harness.js";
+/** The executor-owned root that receives a materialized file. */
+export type PlanFileRoot = "workspace" | "agent";
 export interface PlanFile {
     relPath: string;
     content: string;
+    /** Defaults to the run workspace. `agent` is the harness's private agent directory. */
+    root?: PlanFileRoot;
     /** chmod mode (e.g. 0o755 for hook scripts); default 0o644. */
     mode?: number;
     /**
@@ -29,19 +33,23 @@ export interface PlanFile {
      * replaced.
      *
      * `"materializer"` = a path whose generated content is wholly this
-     * package's output: a name this package invented, or `opencode.json`, which
-     * carries only the registrations generated from the profile. A file already
-     * there is this materializer's own output from an earlier application into
-     * the same workspace, and replacing it is how turn two of a resumed session
-     * gets the current profile instead of the previous one. Application replaces
-     * it only when the existing bytes prove that provenance — by the name for an
-     * invented path, by the content for `opencode.json`.
+     * package's output: a name this package invented, the generated context file
+     * (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `HERMES.md`), or `opencode.json`,
+     * which carries only the registrations generated from the profile. A file
+     * already there is this materializer's own output from an earlier application
+     * into the same workspace, and replacing it is how turn two of a resumed
+     * session — or the first turn of a branched one — gets the current profile
+     * instead of the previous one. Application replaces it only when the existing
+     * bytes prove that provenance — by the name for an invented path, by a marker
+     * line committing to the body digest for a context file, by the content for
+     * `opencode.json`.
      *
      * `"shared"` (the default, and every other file) = a path the user or the
-     * harness also owns — `CLAUDE.md`, `AGENTS.md`, `.gemini/system.md` are all
-     * documented, user-authorable names whose content this package cannot tell
-     * from its own. An existing file there may be the caller's own work, so it is
-     * never replaced.
+     * harness also owns. `.gemini/system.md` is a documented, user-authorable
+     * name whose content this package cannot tell from its own, and so is a
+     * context file mounted as an explicit profile resource rather than generated.
+     * An existing file there may be the caller's own work, so it is never
+     * replaced.
      *
      * Optional because hand-constructed plans have no path provenance to report;
      * absent reads as `"shared"`, the safe answer.
@@ -114,6 +122,11 @@ export interface WorkspacePlanSystemPromptBinding {
     /** Exact text the control receives. */
     systemPrompt: string;
 }
+/** One file applied by a plan, with the executor root kept explicit. */
+export interface WorkspacePlanWrittenFile {
+    root: PlanFileRoot;
+    relPath: string;
+}
 /**
  * The dimensions `materializeProfile`'s `skip` option honors.
  *
@@ -254,7 +267,14 @@ export interface WorkspacePlanReceipt {
     /** The launcher-bound intent, so a receipt says which control owed the work. */
     systemPromptBinding?: WorkspacePlanSystemPromptBinding;
     unsupported: Unsupported[];
+    /**
+     * Legacy workspace-root paths for existing workspace-only consumers.
+     * Agent-root files are available in `writtenFiles` and are never encoded as
+     * an `agent:` path because that spelling is legal in the workspace root.
+     */
     written: string[];
+    /** Every applied file, including its executor-owned root. */
+    writtenFiles: WorkspacePlanWrittenFile[];
 }
 /** Private values handed directly to the provider spawn, never to receipts. */
 export interface WorkspacePlanSpawnInputs {
@@ -281,6 +301,8 @@ export declare class WorkspacePlanCleanupError extends AggregateError {
 export interface ApplyWorkspacePlanOptions {
     /** Plan files consumed in memory by the runtime and never persisted to cwd. */
     runtimeOnlyFiles?: readonly string[];
+    /** Absolute private agent directory required by files whose root is `agent`. */
+    agentDir?: string;
     /** Own newly written workspace files as the process that will read them. */
     ownership?: {
         uid: number;

package/dist/profile-materializer.d.ts

@@ -1,6 +1,6 @@
 import type { AgentProfile, AgentProfileSecretProvider } from "@tangle-network/agent-interface";
 import { type HarnessId } from "./harness.js";
-import { type BindableLaunchControl, type SkippableDimension, type WorkspacePlan } from "./plan-types.js";
+import { type BindableLaunchControl, type PlanFileRoot, type SkippableDimension, type WorkspacePlan } from "./plan-types.js";
 export declare const UNAVAILABLE_AGENT_PROFILE_SECRET_PROVIDER: AgentProfileSecretProvider;
 /**
  * Build a pure workspace plan for one canonical harness.
@@ -9,4 +9,5 @@ export declare const UNAVAILABLE_AGENT_PROFILE_SECRET_PROVIDER: AgentProfileSecr
 export declare function materializeProfile(inputProfile: AgentProfile, harness: HarnessId, opts?: {
     skip?: SkippableDimension[];
     binds?: readonly BindableLaunchControl[];
+    instructionsRoot?: PlanFileRoot;
 }): WorkspacePlan;

package/dist/profile-materializer.js

@@ -1,6 +1,6 @@
 import { agentProfileSchema } from "@tangle-network/agent-interface";
 import { materializeExecutionControls } from "./execution-controls.js";
-import { assertMaterializerHarness } from "./harness.js";
+import { assertMaterializerHarness, harnessAutoLoadsAgentContextFile, } from "./harness.js";
 import { materializeHooks } from "./hooks.js";
 import { materializeMcp } from "./mcp.js";
 import { assertBindableLaunchControls, assertSkippableDimensions, } from "./plan-types.js";
@@ -23,9 +23,17 @@ export function materializeProfile(inputProfile, harness, opts = {}) {
     const profile = agentProfileSchema.parse(inputProfile);
     const skip = new Set(assertSkippableDimensions(opts.skip));
     const binds = assertBindableLaunchControls(opts.binds);
+    const instructionsRoot = opts.instructionsRoot ?? "workspace";
+    if (instructionsRoot !== "workspace" && instructionsRoot !== "agent") {
+        throw new Error(`materializeProfile: unsupported instructions root ${String(instructionsRoot)}`);
+    }
+    if (instructionsRoot === "agent" &&
+        !harnessAutoLoadsAgentContextFile(harness)) {
+        throw new Error(`materializeProfile: harness "${harness}" does not load instructions from its agent directory`);
+    }
     const builder = createProfilePlanBuilder(harness);
     lowerProfileResources(profile, harness, builder);
-    lowerProfilePrompt(profile, harness, binds, builder);
+    lowerProfilePrompt(profile, harness, binds, instructionsRoot, builder);
     materializeExecutionControls(harness, profile.tools, profile.permissions, profile.modes, builder.plan, builder.add, builder.unsupported);
     if ((profile.connections?.length ?? 0) > 0) {
         builder.unsupported("connections", `${harness}: Hub connections must be resolved to authorized MCP servers by the execution runtime`);

package/dist/profile-plan.d.ts

@@ -1,14 +1,16 @@
 import type { AgentProfileConfigValue } from "@tangle-network/agent-interface";
 import type { HarnessId } from "./harness.js";
-import type { AddPlanFile } from "./plan-json.js";
-import type { Unsupported, WorkspacePlan } from "./plan-types.js";
+import type { AddPlanFile, SerializedPlanFileContent } from "./plan-json.js";
+import type { PlanFileRoot, Unsupported, WorkspacePlan } from "./plan-types.js";
 export interface ProfilePlanBuilder {
     plan: WorkspacePlan;
     add: AddPlanFile;
+    addAtRoot: AddRootedPlanFile;
     addExplicitResource: AddExplicitResource;
     unsupported: (dimension: Unsupported["dimension"], reason: string) => void;
     finalize: (failOnError?: boolean) => WorkspacePlan;
 }
+export type AddRootedPlanFile = (root: PlanFileRoot, path: string, content: string | SerializedPlanFileContent, mode?: number) => void;
 export type AddExplicitResource = (dimension: Unsupported["dimension"], path: string, content: string, mode?: number) => void;
 export declare function createProfilePlanBuilder(harness: HarnessId): ProfilePlanBuilder;
 export declare function setPlanEnvironment(plan: WorkspacePlan, name: string, value: string | AgentProfileConfigValue): void;

package/dist/profile-plan.js

@@ -12,7 +12,7 @@ export function createProfilePlanBuilder(harness) {
         unsupported: [],
         requires: [],
     };
-    const pushPlanFile = (relPath, serialized, source, mode) => {
+    const pushPlanFile = (relPath, serialized, source, mode, root = "workspace") => {
         const normalizedPath = normalizeWorkspaceRelativePath(relPath);
         const content = typeof serialized === "string" ? serialized : serialized.content;
         const secretSlots = typeof serialized === "string" ? undefined : serialized.secretSlots;
@@ -24,6 +24,7 @@ export function createProfilePlanBuilder(harness) {
             relPath: normalizedPath,
             content,
             source,
+            ...(root === "workspace" ? {} : { root }),
             ...(source === "generated" && isMaterializerOwnedPath(normalizedPath)
                 ? { ownership: "materializer" }
                 : {}),
@@ -39,6 +40,7 @@ export function createProfilePlanBuilder(harness) {
         });
     };
     const add = (relPath, content, mode) => pushPlanFile(relPath, content, "generated", mode);
+    const addAtRoot = (root, relPath, content, mode) => pushPlanFile(relPath, content, "generated", mode, root);
     const unsupported = (dimension, reason) => plan.unsupported.push({ dimension, reason });
     const explicitResourcePaths = new Map();
     const addExplicitResource = (dimension, relPath, content, mode) => {
@@ -58,16 +60,18 @@ export function createProfilePlanBuilder(harness) {
     return {
         plan,
         add,
+        addAtRoot,
         addExplicitResource,
         unsupported,
         finalize(failOnError) {
             for (const [relPath, dimension] of explicitResourcePaths) {
-                const writers = plan.files.filter((file) => file.relPath === relPath).length;
+                const writers = plan.files.filter((file) => (file.root ?? "workspace") === "workspace" &&
+                    file.relPath === relPath).length;
                 if (writers > 1) {
                     throw new Error(`Profile ${dimension} resource conflicts with generated harness file: ${relPath}`);
                 }
             }
-            plan.files = mergeJsonFiles(plan.files).sort((a, b) => compareStrings(a.relPath, b.relPath));
+            plan.files = mergeJsonFiles(plan.files).sort((a, b) => compareStrings(`${a.root ?? "workspace"}\0${a.relPath}`, `${b.root ?? "workspace"}\0${b.relPath}`));
             if (failOnError && plan.unsupported.length) {
                 throw new Error(formatUnsupported(plan.unsupported));
             }

package/dist/profile-prompt.d.ts

@@ -1,4 +1,4 @@
 import type { AgentProfile } from "@tangle-network/agent-interface";
-import type { BindableLaunchControl, HarnessId } from "./plan-types.js";
+import type { BindableLaunchControl, HarnessId, PlanFileRoot } from "./plan-types.js";
 import type { ProfilePlanBuilder } from "./profile-plan.js";
-export declare function lowerProfilePrompt(profile: AgentProfile, harness: HarnessId, binds: ReadonlySet<BindableLaunchControl>, builder: ProfilePlanBuilder): void;
+export declare function lowerProfilePrompt(profile: AgentProfile, harness: HarnessId, binds: ReadonlySet<BindableLaunchControl>, instructionsRoot: PlanFileRoot, builder: ProfilePlanBuilder): void;

package/dist/profile-prompt.js

@@ -1,8 +1,8 @@
-import { appendSystemPromptRefusal, CODEX_SYSTEM_PROMPT_FILE, CONTEXT_FILE, markMaterializerSubagent, OPENCODE_APPEND_SYSTEM_PROMPT_FILE, OPENCODE_CONFIG_FILE, OPENCODE_CONFIG_SCHEMA, OPENCODE_PRIMARY_AGENT_PREFIX, systemPromptRefusal, } from "./harness.js";
+import { appendSystemPromptRefusal, CODEX_SYSTEM_PROMPT_FILE, CONTEXT_FILE, markMaterializerContextFile, markMaterializerSubagent, OPENCODE_APPEND_SYSTEM_PROMPT_FILE, OPENCODE_CONFIG_FILE, OPENCODE_CONFIG_SCHEMA, OPENCODE_PRIMARY_AGENT_PREFIX, systemPromptRefusal, } from "./harness.js";
 import { sha256 } from "./plan-digest.js";
 import { serializeWorkspacePlanJson } from "./plan-json.js";
-export function lowerProfilePrompt(profile, harness, binds, builder) {
-    const { plan, add, unsupported } = builder;
+export function lowerProfilePrompt(profile, harness, binds, instructionsRoot, builder) {
+    const { plan, add, addAtRoot, unsupported } = builder;
     if (profile.prompt?.systemPrompt !== undefined) {
         if (harness === "claude-code" || harness === "pi" || harness === "prime") {
             plan.systemPrompt = profile.prompt.systemPrompt;
@@ -90,7 +90,7 @@ export function lowerProfilePrompt(profile, harness, binds, builder) {
         }
         else {
             const instructionPath = CONTEXT_FILE[harness];
-            add(instructionPath, `${instructions.join("\n\n")}\n`);
+            addAtRoot(instructionsRoot, instructionPath, markMaterializerContextFile(instructionPath, `${instructions.join("\n\n")}\n`));
             if (harness === "opencode") {
                 openCodeInstructionFiles.push(instructionPath);
             }

package/dist/workspace-apply-files.js

@@ -47,7 +47,8 @@ function sha256Hex(content) {
  * over.
  */
 function workspaceFileConflictMessage(file, existingFiles, planDigest) {
-    const prefix = `Refusing to replace existing workspace file: ${file.relPath}`;
+    const rootLabel = file.root === "workspace" ? "workspace" : "agent-directory";
+    const prefix = `Refusing to replace existing ${rootLabel} file: ${file.relPath}`;
     if (existingFiles === "reject") {
         return `${prefix} — the reject policy forbids any pre-existing plan path (plan ${planDigest})`;
     }

package/dist/workspace-apply.d.ts

@@ -7,6 +7,6 @@ export interface ResolvedWorkspacePlan {
     appendSystemPrompt?: string;
     systemPromptBinding?: WorkspacePlanSystemPromptBinding;
 }
-export declare function safeWorkspacePlanReceipt(plan: WorkspacePlan, written: string[], workspacePlanDigest?: string): WorkspacePlanReceipt;
+export declare function safeWorkspacePlanReceipt(plan: WorkspacePlan, writtenFiles: WorkspacePlanWrittenFile[], workspacePlanDigest?: string): WorkspacePlanReceipt;
 import { type NormalizedPlanFile } from "./plan-normalize.js";
-import type { ApplyWorkspacePlanOptions, WorkspacePlan, WorkspacePlanApplication, WorkspacePlanReceipt, WorkspacePlanSystemPromptBinding } from "./plan-types.js";
+import type { ApplyWorkspacePlanOptions, WorkspacePlan, WorkspacePlanApplication, WorkspacePlanReceipt, WorkspacePlanSystemPromptBinding, WorkspacePlanWrittenFile } from "./plan-types.js";

package/dist/workspace-apply.js

@@ -1,23 +1,36 @@
 export function applyResolvedWorkspacePlan(publicPlan, resolvedPlan, workspaceDir, options, publicPlanDigest = hashWorkspacePlan(publicPlan)) {
     const workspaceRoot = resolve(workspaceDir);
+    if (options.agentDir !== undefined && !isAbsolute(options.agentDir)) {
+        throw new Error("ApplyWorkspacePlanOptions.agentDir must be absolute");
+    }
+    const agentRoot = options.agentDir === undefined ? undefined : resolve(options.agentDir);
+    const publicFiles = normalizePlanFiles(publicPlan.files);
+    if (publicFiles.some((file) => file.root === "agent") && !agentRoot) {
+        throw new Error("Workspace plan contains agent-root files but ApplyWorkspacePlanOptions.agentDir is missing");
+    }
+    const rootFor = (root) => root === "workspace" ? workspaceRoot : agentRoot;
+    const fileIdentity = (file) => `${file.root}\0${file.relPath}`;
+    const receiptFile = (file) => ({
+        root: file.root,
+        relPath: file.relPath,
+    });
     const runtimeOnlyFiles = new Set((options.runtimeOnlyFiles ?? []).map(normalizeWorkspaceRelativePath));
     const ownership = validateWorkspaceOwnership(options.ownership);
-    const privateFilePaths = new Set(normalizePlanFiles(publicPlan.files)
-        .filter((file) => file.secretSlots.length > 0)
-        .map((file) => file.relPath));
+    const privateFilePaths = new Set(publicFiles.filter((file) => file.secretSlots.length > 0).map(fileIdentity));
     const existingFiles = options.existingFiles ?? "allow-identical";
     if (existingFiles !== "allow-identical" && existingFiles !== "reject") {
         throw new Error(`Unsupported existing workspace file policy: ${existingFiles}`);
     }
     const resolvedFiles = resolvedPlan.files;
     const privateRuntimeFiles = Object.fromEntries(resolvedFiles
-        .filter((file) => runtimeOnlyFiles.has(file.relPath))
+        .filter((file) => file.root === "workspace" && runtimeOnlyFiles.has(file.relPath))
         .map((file) => [file.relPath, file.content]));
     const files = resolvedFiles
-        .filter((file) => !runtimeOnlyFiles.has(file.relPath))
+        .filter((file) => file.root !== "workspace" || !runtimeOnlyFiles.has(file.relPath))
         .map((file) => ({
         ...file,
-        absPath: resolveWorkspaceFilePath(workspaceRoot, file.relPath),
+        rootDir: rootFor(file.root),
+        absPath: resolveWorkspaceFilePath(rootFor(file.root), file.relPath),
     }));
     // A prior application of this exact plan makes the workspace live agent
     // state. Preserve changed and removed files. Refresh private generated files
@@ -31,13 +44,13 @@ export function applyResolvedWorkspacePlan(publicPlan, resolvedPlan, workspaceDi
         ? files.filter((file) => {
             if (file.ownership !== "materializer")
                 return false;
-            assertNoSymlinkPathComponents(workspaceRoot, file.absPath);
+            assertNoSymlinkPathComponents(file.rootDir, file.absPath);
             if (!workspaceFileExists(file.absPath))
                 return false;
             const matches = workspaceFileMatches(file);
             const hasCurrentOwnership = ownership === undefined ||
                 workspaceFileHasOwnership(file.absPath, ownership);
-            if (privateFilePaths.has(file.relPath)) {
+            if (privateFilePaths.has(fileIdentity(file))) {
                 return !matches || !hasCurrentOwnership;
             }
             return matches && !hasCurrentOwnership;
@@ -45,7 +58,7 @@ export function applyResolvedWorkspacePlan(publicPlan, resolvedPlan, workspaceDi
         : files;
     if (resumeSamePlan && filesToApply.length === 0) {
         return {
-            receipt: safeWorkspacePlanReceipt(publicPlan, files.map((file) => file.relPath), publicPlanDigest),
+            receipt: safeWorkspacePlanReceipt(publicPlan, files.map(receiptFile), publicPlanDigest),
             spawn: {
                 env: { ...resolvedPlan.env },
                 flags: [...resolvedPlan.flags],
@@ -66,7 +79,7 @@ export function applyResolvedWorkspacePlan(publicPlan, resolvedPlan, workspaceDi
     // Validate the complete plan before the first write so a late traversal or
     // existing symlink cannot leave a partially materialized workspace.
     for (const file of filesToApply) {
-        assertNoSymlinkPathComponents(workspaceRoot, file.absPath);
+        assertNoSymlinkPathComponents(file.rootDir, file.absPath);
         if (workspaceFileExists(file.absPath) &&
             !mayReplace(file) &&
             (existingFiles === "reject" || !workspaceFileMatches(file))) {
@@ -79,7 +92,7 @@ export function applyResolvedWorkspacePlan(publicPlan, resolvedPlan, workspaceDi
         mkdirSync(dirname(file.absPath), { recursive: true });
     }
     for (const file of filesToApply) {
-        assertNoSymlinkPathComponents(workspaceRoot, file.absPath);
+        assertNoSymlinkPathComponents(file.rootDir, file.absPath);
     }
     const prepared = [];
     // Prepared temp links stay alive through publication and rollback. Their
@@ -94,10 +107,10 @@ export function applyResolvedWorkspacePlan(publicPlan, resolvedPlan, workspaceDi
                     workspaceFileHasOwnership(file.absPath, ownership))) {
                 continue;
             }
-            prepared.push(prepareWorkspaceFile(workspaceRoot, file, ownership));
+            prepared.push(prepareWorkspaceFile(file.rootDir, file, ownership));
         }
         for (const entry of prepared) {
-            assertNoSymlinkPathComponents(workspaceRoot, entry.file.absPath);
+            assertNoSymlinkPathComponents(rootFor(entry.file.root), entry.file.absPath);
             try {
                 linkSync(entry.temporaryPath, entry.file.absPath);
                 entry.published = true;
@@ -120,7 +133,7 @@ export function applyResolvedWorkspacePlan(publicPlan, resolvedPlan, workspaceDi
                     // superseded bytes. That is the fail-closed direction: the harness
                     // whose flag names a missing file refuses to start, whereas silently
                     // restored previous-turn bytes would run the wrong prompt.
-                    assertNoSymlinkPathComponents(workspaceRoot, entry.file.absPath);
+                    assertNoSymlinkPathComponents(rootFor(entry.file.root), entry.file.absPath);
                     renameSync(entry.temporaryPath, entry.file.absPath);
                     entry.published = true;
                     continue;
@@ -158,7 +171,7 @@ export function applyResolvedWorkspacePlan(publicPlan, resolvedPlan, workspaceDi
         }
         throw error;
     }
-    const receipt = safeWorkspacePlanReceipt(publicPlan, files.map((file) => file.relPath), publicPlanDigest);
+    const receipt = safeWorkspacePlanReceipt(publicPlan, files.map(receiptFile), publicPlanDigest);
     const cleanupErrors = [];
     const temporaryPaths = [];
     for (const entry of prepared) {
@@ -186,7 +199,7 @@ export function applyResolvedWorkspacePlan(publicPlan, resolvedPlan, workspaceDi
         runtimeOnlyFiles: privateRuntimeFiles,
     };
 }
-export function safeWorkspacePlanReceipt(plan, written, workspacePlanDigest = hashWorkspacePlan(plan)) {
+export function safeWorkspacePlanReceipt(plan, writtenFiles, workspacePlanDigest = hashWorkspacePlan(plan)) {
     return {
         workspacePlanDigest,
         env: Object.fromEntries(Object.entries(plan.env).map(([name, value]) => [
@@ -197,11 +210,14 @@ export function safeWorkspacePlanReceipt(plan, written, workspacePlanDigest = ha
         ...promptIntentFields(plan, samePromptIntentValue),
         ...systemPromptBindingField(plan),
         unsupported: plan.unsupported.map((entry) => ({ ...entry })),
-        written: [...written],
+        written: writtenFiles
+            .filter((file) => file.root === "workspace")
+            .map((file) => file.relPath),
+        writtenFiles: writtenFiles.map((file) => ({ ...file })),
     };
 }
 import { linkSync, mkdirSync, renameSync, unlinkSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { dirname, isAbsolute, resolve } from "node:path";
 import { isMaterializerOutput } from "./harness.js";
 import { hashWorkspacePlan } from "./plan-digest.js";
 import { normalizePlanFiles, normalizeWorkspacePlanArgument, } from "./plan-normalize.js";

package/dist/workspace-files.d.ts

@@ -1,4 +1,4 @@
-export declare const compareStrings: (a: string, b: string) => 0 | 1 | -1;
+export declare const compareStrings: (a: string, b: string) => 1 | -1 | 0;
 export declare const DEFAULT_FILE_MODE = 420;
 export declare const PRIVATE_FILE_MODE = 384;
 export declare const EXECUTABLE_FILE_MODE = 493;

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@tangle-network/agent-profile-materialize",
-  "version": "0.18.1",
+  "version": "0.19.1",
   "description": "Materialize an AgentProfile into the native per-harness workspace files (the one shared materializer for cli-bridge, agent-dev-container, and VB).",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tangle-network/agent-dev-container.git",
+    "directory": "packages/agent-profile-materialize"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -20,7 +25,8 @@
     "dist"
   ],
   "devDependencies": {
-    "@tangle-network/agent-interface": "2.0.0",
+    "@tangle-network/agent-interface": "2.1.1",
+    "@tangle-network/agent-interface-current": "npm:@tangle-network/agent-interface@2.1.1",
     "@types/node": "25.6.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
@@ -32,7 +38,9 @@
     "build": "tsc -p tsconfig.json",
     "check-types": "tsc --noEmit",
     "clean": "rm -rf dist",
-    "test": "vitest run",
+    "test": "pnpm run test:installed-peer && pnpm run test:current-peer",
+    "test:installed-peer": "vitest run",
+    "test:current-peer": "vitest run --config vitest.current-peer.config.ts",
     "test:watch": "vitest"
   }
 }