@tangle-network/agent-profile-materialize 0.19.0 → 0.19.2

package/dist/harness.d.ts

@@ -58,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.
@@ -92,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

@@ -130,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` 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.
+ * `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.
  *
- * 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.
+ * 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.
+ *
+ * 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`
@@ -169,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.
@@ -194,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.
@@ -223,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();
@@ -287,3 +381,4 @@ export function skillDirForHarness(harness) {
     assertMaterializerHarness(harness);
     return HARNESS_SKILL_DIRS[harness];
 }
+import { createHash } from "node:crypto";

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { applyAgentCandidateWorkspacePlan, materializeCandidateProfile, } from "
 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, harnessAutoLoadsAgentContextFile, 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";

package/dist/index.js

@@ -1,7 +1,7 @@
 /** 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, harnessAutoLoadsAgentContextFile, 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, resolvePiRuntimePaths, } from "./pi-models-config.js";

package/dist/plan-types.d.ts

@@ -33,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.

package/dist/profile-prompt.js

@@ -1,4 +1,4 @@
-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, instructionsRoot, builder) {
@@ -90,7 +90,7 @@ export function lowerProfilePrompt(profile, harness, binds, instructionsRoot, bu
         }
         else {
             const instructionPath = CONTEXT_FILE[harness];
-            addAtRoot(instructionsRoot, instructionPath, `${instructions.join("\n\n")}\n`);
+            addAtRoot(instructionsRoot, instructionPath, markMaterializerContextFile(instructionPath, `${instructions.join("\n\n")}\n`));
             if (harness === "opencode") {
                 openCodeInstructionFiles.push(instructionPath);
             }

package/dist/resource-resolution.js

@@ -29,6 +29,43 @@ export function resolveInlineRef(ref) {
 }
 const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
 const collapse = (s) => s.replace(/\s+/g, " ").trim();
+function frontmatterScalar(value) {
+    const trimmed = value.trim();
+    if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (typeof parsed === "string")
+                return parsed;
+        }
+        catch {
+            return trimmed;
+        }
+    }
+    if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+        return trimmed.slice(1, -1).replaceAll("''", "'");
+    }
+    return trimmed;
+}
+function frontmatterValue(frontmatter, field) {
+    const lines = frontmatter.split("\n");
+    const index = lines.findIndex((line) => line.startsWith(`${field}:`));
+    if (index < 0)
+        return undefined;
+    const inline = (lines[index] ?? "").slice(field.length + 1).trim();
+    if (inline && ![">", "|", ">-", "|-"].includes(inline)) {
+        return frontmatterScalar(inline);
+    }
+    const block = [];
+    for (let offset = index + 1; offset < lines.length; offset += 1) {
+        const line = lines[offset] ?? "";
+        if (/^\s+\S/.test(line))
+            block.push(line.trim());
+        else if (line.trim() !== "")
+            break;
+    }
+    const value = collapse(block.join(" "));
+    return value || undefined;
+}
 const DEFAULT_RESOURCE_FETCH_TIMEOUT_MS = 30_000;
 const MAX_RESOURCE_BYTES = 10 * 1024 * 1024;
 const MAX_PROFILE_RESOURCE_BYTES = 32 * 1024 * 1024;
@@ -210,30 +247,17 @@ export function normalizeSkillMd(name, raw) {
     const m = raw.match(FRONTMATTER_RE);
     const fm = m?.[1] ?? "";
     const body = (m?.[2] ?? raw).trim();
-    let desc = `Skill ${name}. Use when the task matches its domain.`;
-    if (fm) {
-        const lines = fm.split("\n");
-        const i = lines.findIndex((l) => /^description:/.test(l));
-        if (i >= 0) {
-            const inline = (lines[i] ?? "").replace(/^description:\s*/, "").trim();
-            if (inline && ![">", "|", ">-", "|-"].includes(inline))
-                desc = collapse(inline);
-            else {
-                const buf = [];
-                for (let j = i + 1; j < lines.length; j++) {
-                    const ln = lines[j] ?? "";
-                    if (/^\s+\S/.test(ln))
-                        buf.push(ln.trim());
-                    else if (ln.trim() === "")
-                        continue;
-                    else
-                        break;
-                }
-                if (buf.length)
-                    desc = collapse(buf.join(" "));
-            }
-        }
+    if (fm &&
+        frontmatterValue(fm, "name") === name &&
+        (frontmatterValue(fm, "description")?.trim().length ?? 0) > 0) {
+        return raw;
     }
+    let desc = `Skill ${name}. Use when the task matches its domain.`;
+    const declaredDescription = fm
+        ? frontmatterValue(fm, "description")
+        : undefined;
+    if (declaredDescription)
+        desc = collapse(declaredDescription);
     return `---\nname: ${name}\ndescription: ${JSON.stringify(desc)}\n---\n\n${body}\n`;
 }
 import { basename } from "node:path";

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,6 +1,6 @@
 {
   "name": "@tangle-network/agent-profile-materialize",
-  "version": "0.19.0",
+  "version": "0.19.2",
   "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": {