@sema-agent/core 5.0.1 → 5.2.0

package/dist/core/memory-engine/engine.js

@@ -6,7 +6,7 @@ import { inlineUntrusted } from "../untrusted-text.js";
 import { formatMemoryAge } from "../memory-recall.js";
 import { computeEntryRev, parseEntryFile, serializeEntryFile } from "./frontmatter.js";
 import { DEFAULT_MAX_ENTRY_DEPTH, MEMORY_INDEX_FILENAME, scanEntryFiles } from "./file-backend.js";
-import { QUARANTINE_DIR, SCAN_FUSE_THRESHOLD, quarantineAndTombstone, readIndexRevs, writeIndexRevs, bumpScanFuse, canonicalize, claimRootScope, clearScanFuse, deriveControlPlaneDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, isContainedIn, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirFor, } from "./layout.js";
+import { QUARANTINE_DIR, SCAN_FUSE_THRESHOLD, quarantineAndTombstone, readIndexRevs, writeIndexRevs, bumpScanFuse, canonicalize, claimRootScope, clearScanFuse, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, isContainedIn, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirFor, } from "./layout.js";
 import { scanMemoryFileName, scanMemoryWrite, scanRemediation } from "./scan.js";
 export const MEMORY_INSTRUCTION_TEMPLATE = `# Memory
 
@@ -50,6 +50,7 @@ export class MemoryEngine {
     maxDepth;
     harvestDeadlineMs;
     harvestFileBudget;
+    onIncident;
     backendPinnedRoot;
     constructor(opts) {
         this.backend = opts.backend;
@@ -61,7 +62,7 @@ export class MemoryEngine {
         this.controlDir =
             typeof backendControl === "string" && backendControl
                 ? backendControl
-                : (opts.controlDir ?? deriveControlPlaneDir(resolveMemoryEngineRoot(), opts.memoryDir));
+                : (opts.controlDir ?? (adoptCanonicalKeyedControlDir(resolveMemoryEngineRoot(), opts.memoryDir, opts.onIncident), deriveControlPlaneDir(resolveMemoryEngineRoot(), opts.memoryDir)));
         this.now = opts.now ?? Date.now;
         this.perScopeBudgetBytes = opts.perScopeBudgetBytes ?? Number.MAX_SAFE_INTEGER;
         this.perFileBytes = opts.perFileBytes ?? MAX_MEMORY_BYTES;
@@ -69,6 +70,20 @@ export class MemoryEngine {
         this.maxDepth = opts.maxDepth ?? DEFAULT_MAX_ENTRY_DEPTH;
         this.harvestDeadlineMs = opts.harvestDeadlineMs ?? DEFAULT_HARVEST_DEADLINE_MS;
         this.harvestFileBudget = opts.harvestFileBudget ?? DEFAULT_HARVEST_FILE_BUDGET;
+        this.onIncident = opts.onIncident;
+    }
+    discloseAnnounceFailure(stage, cause) {
+        const sink = this.onIncident;
+        if (sink === undefined)
+            return;
+        try {
+            const detail = cause instanceof Error ? cause.message : String(cause);
+            const err = new Error(`memory announcement queue ${stage} failed: ${detail}`);
+            err.code = "memory.announce_failed";
+            sink(err);
+        }
+        catch {
+        }
     }
     async materialize(scopes, writeScope) {
         ensureDirExists(this.memoryDir);
@@ -156,7 +171,8 @@ export class MemoryEngine {
                     items: [`memory index rejected and rebuilt: ${inlineUntrusted(indexGate.reason)}`],
                 });
             }
-            catch {
+            catch (err) {
+                this.discloseAnnounceFailure("index-gate enqueue", err);
             }
         }
         const indexText = this.rebuildIndex(handle, headers, { write: writeScope !== null });
@@ -191,7 +207,8 @@ export class MemoryEngine {
                 announceBlock = renderAnnouncements(drained.queue, drained.folded);
             }
         }
-        catch {
+        catch (err) {
+            this.discloseAnnounceFailure("inject drain", err);
         }
         const block = [instruction, index, announceBlock].filter((s) => Boolean(s && s.trim())).join("\n\n");
         return {
@@ -239,7 +256,8 @@ export class MemoryEngine {
                 enqueueMemoryAnnouncement(this.controlDir, { kind: "external", at: this.now(), items: capItems(items) });
             }
         }
-        catch {
+        catch (err) {
+            this.discloseAnnounceFailure("harvest enqueue", err);
         }
         return report;
     }
@@ -812,7 +830,8 @@ export class MemoryEngine {
                         .concat(sweepSkipped.length > 12 ? [`…and ${sweepSkipped.length - 12} more sweepSkipped path(s)`] : []),
                 });
             }
-            catch {
+            catch (err) {
+                this.discloseAnnounceFailure("mode-sweep enqueue", err);
             }
         }
     }

package/dist/core/memory-engine/file-backend.d.ts

@@ -1,4 +1,4 @@
-import { scopeDirName } from "./layout.js";
+import { scopeDirName, type MemoryPartitionIncidentSink } from "./layout.js";
 import type { HarvestRejection, MemoryBackend, MemoryEntry, MemoryEntryHeader, NotePatch, PatchReport, ScoredMemoryEntry } from "./types.js";
 export declare const MEMORY_INDEX_FILENAME = "MEMORY.md";
 export declare const DEFAULT_MAX_ENTRY_DEPTH = 3;
@@ -11,6 +11,11 @@ export declare function scanEntryFiles(dir: string, opts?: {
     exclude?: ReadonlySet<string>;
     onSkip?: (path: string, kind: "symlink" | "depth" | "nonmd" | "dotfile" | "unreadable") => void;
 }): ScannedEntryFile[];
+export interface FileMemoryEngineBackendOptions {
+    controlDir?: string;
+    now?: () => number;
+    onIncident?: MemoryPartitionIncidentSink;
+}
 export declare class FileMemoryEngineBackend implements MemoryBackend {
     readonly directoryRoot: string;
     readonly controlPlaneRoot: string;
@@ -18,10 +23,7 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
     private ledger;
     private inboundFindings;
     private batchScan;
-    constructor(dir: string, opts?: {
-        controlDir?: string;
-        now?: () => number;
-    });
+    constructor(dir: string, opts?: FileMemoryEngineBackendOptions);
     checkControlPlane(): void;
     drainInboundFindings(): HarvestRejection[];
     readCommittedShadow(id: string): string | undefined;

package/dist/core/memory-engine/file-backend.js

@@ -5,7 +5,7 @@ import { jaccardDistance, termSet } from "../memory-vector.js";
 import { MAX_MEMORY_BYTES } from "../memory.js";
 import { inlineUntrusted } from "../untrusted-text.js";
 import { computeEntryRev, entryFromFile, isValidEntryId, parseEntryFile, serializeEntryFile } from "./frontmatter.js";
-import { ControlPlaneCorruptError, CURSORS_FILE, QUARANTINE_DIR, atomicWriteFileSync, quarantineAndTombstone, claimRootScope, deriveControlPlaneDir, ensureDirExists, enqueueMemoryAnnouncement, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirName, writeAllSync, } from "./layout.js";
+import { ControlPlaneCorruptError, CURSORS_FILE, QUARANTINE_DIR, atomicWriteFileSync, quarantineAndTombstone, claimRootScope, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, ensureDirExists, enqueueMemoryAnnouncement, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirName, writeAllSync, } from "./layout.js";
 import { scanMemoryFileName, scanMemoryWrite } from "./scan.js";
 export const MEMORY_INDEX_FILENAME = "MEMORY.md";
 export const DEFAULT_MAX_ENTRY_DEPTH = 3;
@@ -78,6 +78,8 @@ export class FileMemoryEngineBackend {
     constructor(dir, opts = {}) {
         this.now = opts.now ?? Date.now;
         this.directoryRoot = dir;
+        if (opts.controlDir === undefined)
+            adoptCanonicalKeyedControlDir(resolveMemoryEngineRoot(), dir, opts.onIncident);
         this.controlPlaneRoot = opts.controlDir ?? deriveControlPlaneDir(resolveMemoryEngineRoot(), dir);
         ensureDirExists(dir);
         ensureDirExists(this.controlPlaneRoot);

package/dist/core/memory-engine/index.d.ts

@@ -1,7 +1,7 @@
 export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, renderAnnouncements, type MemoryEngineOptions, type MemoryInjection, } from "./engine.js";
 export { scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE } from "./scan.js";
 export { FileMemoryEngineBackend, scanEntryFiles, MEMORY_INDEX_FILENAME, DEFAULT_MAX_ENTRY_DEPTH, type ScannedEntryFile } from "./file-backend.js";
-export { ControlPlaneCorruptError, deriveControlPlaneDir, deriveRepoKey, deriveRepoMemoryDir, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, claimRootScope, rootScopeOf, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, } from "./layout.js";
+export { ControlPlaneCorruptError, deriveControlPlaneDir, deriveRepoControlPlaneDir, deriveRepoKey, deriveRepoMemoryDir, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, claimRootScope, rootScopeOf, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, } from "./layout.js";
 export { parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, type ParsedEntryFile } from "./frontmatter.js";
 export type { MemoryBackend, MemoryEntry, MemoryEntryFrontmatter, MemoryEntryHeader, ScoredMemoryEntry, NotePatch, PatchReport, MaterializedFile, MemorySessionHandle, HarvestReport, HarvestRejection, HarvestRejectionCode, MemoryAnnouncement, ScanFinding, } from "./types.js";
 export { memoryBackendContract, assertMemoryBackendSearchEquivalence, type MemoryBackendContractHooks, } from "./memory-backend-contract.js";

package/dist/core/memory-engine/index.js

@@ -1,7 +1,7 @@
 export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, renderAnnouncements, } from "./engine.js";
 export { scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE } from "./scan.js";
 export { FileMemoryEngineBackend, scanEntryFiles, MEMORY_INDEX_FILENAME, DEFAULT_MAX_ENTRY_DEPTH } from "./file-backend.js";
-export { ControlPlaneCorruptError, deriveControlPlaneDir, deriveRepoKey, deriveRepoMemoryDir, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, claimRootScope, rootScopeOf, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, } from "./layout.js";
+export { ControlPlaneCorruptError, deriveControlPlaneDir, deriveRepoControlPlaneDir, deriveRepoKey, deriveRepoMemoryDir, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, claimRootScope, rootScopeOf, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, } from "./layout.js";
 export { parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile } from "./frontmatter.js";
 export { memoryBackendContract, assertMemoryBackendSearchEquivalence, } from "./memory-backend-contract.js";
 export { SCOPE_SEGMENT_MAX_ENCODED, PROJECT_MARKER_PATH, encodeScopeSegment, decodeScopeSegment, parseScopeKey, formatUserScope, formatOrgScope, formatProjScope, formatUserProjScope, isPersonalScope, assertScopeContractPlacement, formatProjectMarker, parseProjectMarker, resolveProjectId, PROJECT_ID_REGEX, } from "./scope-contract.js";

package/dist/core/memory-engine/layout.d.ts

@@ -1,11 +1,17 @@
 import type { MemoryAnnouncement } from "./types.js";
 export declare const CURSORS_FILE = "cursors.json";
+export declare const CONTROL_PLANE_DIR = ".engine";
 export declare class ControlPlaneCorruptError extends Error {
     constructor(message: string, opts?: {
         cause?: unknown;
     });
 }
 export declare function deriveRepoKey(repoRoot: string): string;
+export type MemoryPartitionIncidentSink = (err: Error & {
+    code?: string;
+}) => void;
+export declare function adoptLegacyRepoDirs(configRoot: string, repoRoot: string, onIncident?: MemoryPartitionIncidentSink): void;
+export declare function adoptCanonicalKeyedControlDir(configRoot: string, dir: string, onIncident?: MemoryPartitionIncidentSink): void;
 export declare function deriveRepoMemoryDir(configRoot: string, repoRoot: string): string;
 export declare function deriveProjectMemoryDir(configRoot: string, projectId: string): string;
 export declare function deriveProjectControlDir(configRoot: string, projectId: string): string;
@@ -13,6 +19,7 @@ export declare const PROJECT_ID_HINTS_FILE = "project-id-hints.json";
 export declare function recordProjectIdHint(configRoot: string, repoRoot: string, projectId: string): void;
 export declare function lookupProjectIdHint(configRoot: string, repoRoot: string): string | undefined;
 export declare function deriveControlPlaneDir(configRoot: string, key: string): string;
+export declare function deriveRepoControlPlaneDir(configRoot: string, repoRoot: string): string;
 export declare function resolveMemoryEngineRoot(explicit?: string): string;
 export declare function scopeDirName(scope: string): string;
 export declare function rootScopeOf(controlDir: string): string | undefined;

package/dist/core/memory-engine/layout.js

@@ -1,17 +1,106 @@
-import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 const SCOPES_FILE = "scopes.json";
 export const CURSORS_FILE = "cursors.json";
+export const CONTROL_PLANE_DIR = ".engine";
 export class ControlPlaneCorruptError extends Error {
     constructor(message, opts) {
         super(message, opts);
         this.name = "ControlPlaneCorruptError";
     }
 }
+function slugifyPath(absPath) {
+    return absPath.normalize("NFC").replace(/[^A-Za-z0-9]/g, "-");
+}
 export function deriveRepoKey(repoRoot) {
-    return resolve(repoRoot).normalize("NFC").replace(/[^A-Za-z0-9]/g, "-");
+    return slugifyPath(canonicalize(resolve(repoRoot)));
+}
+function deriveDirKey(dir) {
+    return slugifyPath(resolve(dir));
+}
+function subtreeHasFiles(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return true;
+    }
+    for (const e of entries) {
+        if (!e.isDirectory())
+            return true;
+        if (subtreeHasFiles(join(dir, e.name)))
+            return true;
+    }
+    return false;
+}
+function migrateKeyedPartition(m) {
+    const disclose = (code, message) => {
+        try {
+            const e = new Error(message);
+            e.code = code;
+            m.onIncident?.(e);
+        }
+        catch {
+        }
+    };
+    const splitText = `memory partition split detected for ${m.subject}: BOTH ${m.fromDir} and ${m.toDir} hold content. This session uses ${m.toDir}; the other dir is left untouched (never merged — CAS baselines would collide). If it holds the newer memory, move its rows by hand and remove it.`;
+    try {
+        if (m.fromDir === m.toDir)
+            return;
+        if (!existsSync(m.fromDir))
+            return;
+        if (existsSync(m.toDir)) {
+            if (subtreeHasFiles(m.toDir)) {
+                disclose("memory.partition_split", splitText);
+                return;
+            }
+            try {
+                rmSync(m.toDir, { recursive: true });
+            }
+            catch (err) {
+                const code = err.code;
+                disclose("memory.partition_adopt_failed", `could not clear the empty directory scaffolding at ${m.toDir} before adopting ${m.fromDir} (${code ?? String(err)}): ` +
+                    `this session proceeds on ${m.toDir}; ${m.fromDir} still holds the prior memory — move it by hand.`);
+                return;
+            }
+        }
+        try {
+            ensureDirExists(dirname(m.toDir));
+            renameSync(m.fromDir, m.toDir);
+        }
+        catch (err) {
+            const code = err.code;
+            if ((code === "ENOENT" || code === "EEXIST" || code === "ENOTEMPTY") && existsSync(m.toDir)) {
+                if (!existsSync(m.fromDir))
+                    return;
+                disclose("memory.partition_split", splitText);
+                return;
+            }
+            disclose("memory.partition_adopt_failed", `could not adopt the memory partition ${m.fromDir} → ${m.toDir} (${code ?? String(err)}): this session proceeds on ${m.toDir}; ` +
+                `${m.fromDir} still holds the prior memory — move it by hand.`);
+        }
+    }
+    catch {
+    }
+}
+export function adoptLegacyRepoDirs(configRoot, repoRoot, onIncident) {
+    migrateKeyedPartition({
+        fromDir: join(configRoot, deriveDirKey(repoRoot)),
+        toDir: join(configRoot, deriveRepoKey(repoRoot)),
+        subject: repoRoot,
+        onIncident,
+    });
+}
+export function adoptCanonicalKeyedControlDir(configRoot, dir, onIncident) {
+    migrateKeyedPartition({
+        fromDir: join(configRoot, deriveRepoKey(dir), CONTROL_PLANE_DIR),
+        toDir: join(configRoot, deriveDirKey(dir), CONTROL_PLANE_DIR),
+        subject: dir,
+        onIncident,
+    });
 }
 export function deriveRepoMemoryDir(configRoot, repoRoot) {
     return join(configRoot, deriveRepoKey(repoRoot), "memory");
@@ -20,7 +109,7 @@ export function deriveProjectMemoryDir(configRoot, projectId) {
     return join(configRoot, `proj-${projectId.toLowerCase()}`, "memory");
 }
 export function deriveProjectControlDir(configRoot, projectId) {
-    return join(configRoot, `proj-${projectId.toLowerCase()}`, ".engine");
+    return join(configRoot, `proj-${projectId.toLowerCase()}`, CONTROL_PLANE_DIR);
 }
 export const PROJECT_ID_HINTS_FILE = "project-id-hints.json";
 export function recordProjectIdHint(configRoot, repoRoot, projectId) {
@@ -57,7 +146,10 @@ export function lookupProjectIdHint(configRoot, repoRoot) {
     }
 }
 export function deriveControlPlaneDir(configRoot, key) {
-    return join(configRoot, deriveRepoKey(key), ".engine");
+    return join(configRoot, deriveDirKey(key), CONTROL_PLANE_DIR);
+}
+export function deriveRepoControlPlaneDir(configRoot, repoRoot) {
+    return join(configRoot, deriveRepoKey(repoRoot), CONTROL_PLANE_DIR);
 }
 export function resolveMemoryEngineRoot(explicit) {
     const raw = explicit ?? process.env.AGENT_DATA_DIR ?? join(homedir(), ".ai-agent");
@@ -178,7 +270,8 @@ export function canonicalize(p) {
         const parent = resolve(p, "..");
         if (parent === p)
             return p;
-        return join(canonicalize(parent), p.slice(parent.length + 1) || "");
+        const rest = p.slice(parent.endsWith(sep) ? parent.length : parent.length + 1);
+        return join(canonicalize(parent), rest);
     }
 }
 export function isContainedIn(root, child) {

package/dist/core/memory.d.ts

@@ -91,7 +91,6 @@ export interface NormalizedMemorySpec {
     scopeContract?: "v2";
 }
 export type MemorySpecInput = {
-    scope?: string;
     scopes?: ReadonlyArray<string>;
     writeScope?: string | null;
     enabled?: boolean;

package/dist/core/memory.js

@@ -354,7 +354,13 @@ function mtimeMsOf(ts) {
 export function normalizeMemorySpec(input) {
     if (!input)
         return undefined;
-    const raw = input.scopes && input.scopes.length > 0 ? input.scopes : input.scope !== undefined ? [input.scope] : [];
+    if (Object.prototype.hasOwnProperty.call(input, "scope")) {
+        const e = new Error("TaskSpec.memory: the singular `scope` field was removed — write `scopes: [\"<scope>\"]` instead " +
+            "(an ordered read layering; `writeScope` defaults to its last entry). Refusing to start with memory silently off.");
+        e.code = "config.memory_scope_spelling";
+        throw e;
+    }
+    const raw = input.scopes ?? [];
     const scopes = [];
     const seen = new Set();
     for (const s of raw) {

package/dist/core/permission-rules.js

@@ -1,3 +1,4 @@
+import { MCP_NAMESPACE } from "./protocol-table.js";
 export const BASH_GENERIC_PARAMS = new Set(["command", "timeout", "description", "run_in_background"]);
 const DEFAULT_CAPS = {
     maxRules: 256,
@@ -95,7 +96,7 @@ const FILE_TOOL_PARAMS = {
     Write: new Set(["file_path", "path", "content"]),
     NotebookEdit: new Set(["notebook_path", "path", "cell_id", "cell_type", "edit_mode", "new_source"]),
     Grep: new Set([
-        "pattern", "path", "glob", "type", "output_mode", "head_limit", "max_results", "offset",
+        "pattern", "path", "glob", "type", "output_mode", "head_limit", "offset",
         "multiline", "context", "ignore_case", "-i", "-n", "-o", "-A", "-B", "-C",
     ]),
     Glob: new Set(["pattern", "path", "max_results"]),
@@ -142,7 +143,7 @@ function compile(rules, caps, primaryFieldGeneric) {
             }
         }
         const toolName = parsed.toolName;
-        if (toolName.startsWith("mcp__") && (parsed.ruleContent !== undefined || indexOfUnescaped(text, "(") !== -1)) {
+        if (toolName.startsWith(MCP_NAMESPACE.prefix) && (parsed.ruleContent !== undefined || indexOfUnescaped(text, "(") !== -1)) {
             bad(text, "unsupported.mcp_paren", "MCP rules do not support patterns in parentheses (CC parity); use the toolAxes system");
             continue;
         }
@@ -274,18 +275,18 @@ export function createPermissionRulePolicy(rules, opts) {
             const entry = byTool.get(req.toolName);
             if (entry) {
                 if (entry.bare.deny) {
-                    return { action: "deny", reason: ruleMessage("denied", entry.bare.deny.ruleText, entry.bare.deny.source) };
+                    return { action: "deny", message: ruleMessage("denied", entry.bare.deny.ruleText, entry.bare.deny.source) };
                 }
                 const paramDeny = matchParamRules(entry.param.deny, req.args, caps.maxScalarValueChars);
                 if (paramDeny) {
-                    return { action: "deny", reason: ruleMessage("denied", paramDeny.ruleText, paramDeny.source) };
+                    return { action: "deny", message: ruleMessage("denied", paramDeny.ruleText, paramDeny.source) };
                 }
                 if (entry.bare.ask) {
-                    return { action: "ask", reason: ruleMessage("flagged", entry.bare.ask.ruleText, entry.bare.ask.source) };
+                    return { action: "ask", message: ruleMessage("flagged", entry.bare.ask.ruleText, entry.bare.ask.source) };
                 }
                 const paramAsk = matchParamRules(entry.param.ask, req.args, caps.maxScalarValueChars);
                 if (paramAsk) {
-                    return { action: "ask", reason: ruleMessage("flagged", paramAsk.ruleText, paramAsk.source) };
+                    return { action: "ask", message: ruleMessage("flagged", paramAsk.ruleText, paramAsk.source) };
                 }
                 if (entry.bare.allow) {
                     return { action: "allow" };
@@ -293,7 +294,7 @@ export function createPermissionRulePolicy(rules, opts) {
             }
             if (defaultAction === "allow")
                 return { action: "allow" };
-            return { action: defaultAction, reason: `no permission rule matched "${req.toolName}" (default-${defaultAction} rule set)` };
+            return { action: defaultAction, message: `no permission rule matched "${req.toolName}" (default-${defaultAction} rule set)` };
         },
     };
 }

package/dist/core/protocol-table.d.ts

@@ -0,0 +1,17 @@
+export type ProtocolId = "mcp";
+export interface ProtocolPeerTool {
+    peer: string;
+    tool: string;
+}
+export interface ProtocolNamespace<P extends string = string> {
+    readonly id: ProtocolId;
+    readonly prefix: P;
+    makeName(peer: string, tool: string): string;
+    parse(name: string): ProtocolPeerTool | undefined;
+    displayGroupKey(name: string): string;
+}
+declare const MCP_PREFIX_NAME: "mcp__";
+export declare const MCP_NAMESPACE: ProtocolNamespace<typeof MCP_PREFIX_NAME>;
+export declare const PROTOCOL_TABLE: readonly ProtocolNamespace[];
+export declare function protocolOf(name: string): ProtocolNamespace | undefined;
+export {};

package/dist/core/protocol-table.js

@@ -0,0 +1,37 @@
+const NAME_SEP = "__";
+const MCP_PREFIX_NAME = `mcp${NAME_SEP}`;
+const parseMcpName = (name) => {
+    if (!name.startsWith(MCP_PREFIX_NAME))
+        return undefined;
+    const rest = name.slice(MCP_PREFIX_NAME.length);
+    const sep = rest.indexOf(NAME_SEP);
+    if (sep <= 0)
+        return undefined;
+    const tool = rest.slice(sep + NAME_SEP.length);
+    if (tool.length === 0)
+        return undefined;
+    return { peer: rest.slice(0, sep), tool };
+};
+const makeMcpName = (peer, tool) => {
+    if (peer.length === 0 || tool.length === 0) {
+        throw new Error(`protocol table (mcp): peer and tool must both be non-empty (got peer=${JSON.stringify(peer)}, tool=${JSON.stringify(tool)})`);
+    }
+    if (peer.includes(NAME_SEP)) {
+        throw new Error(`protocol table (mcp): peer must not contain the ${NAME_SEP} separator (got ${JSON.stringify(peer)}) — the composed name would parse back as a DIFFERENT peer`);
+    }
+    return `${MCP_PREFIX_NAME}${peer}${NAME_SEP}${tool}`;
+};
+export const MCP_NAMESPACE = {
+    id: "mcp",
+    prefix: MCP_PREFIX_NAME,
+    makeName: makeMcpName,
+    parse: parseMcpName,
+    displayGroupKey: (name) => {
+        const p = parseMcpName(name);
+        return p === undefined ? name : `${MCP_PREFIX_NAME}${p.peer}${NAME_SEP}*`;
+    },
+};
+export const PROTOCOL_TABLE = [MCP_NAMESPACE];
+export function protocolOf(name) {
+    return PROTOCOL_TABLE.find((ns) => name.startsWith(ns.prefix));
+}

package/dist/core/runner/active-skill-scope.js

@@ -28,7 +28,7 @@ export function createActiveSkillScopePolicy(opts) {
             if (unresolved && unresolved.kind === "unresolved") {
                 return {
                     action: "deny",
-                    reason: `tool "${req.toolName}" denied: active skill artifact "${unresolved.lineageId}" manifest could not be resolved (${unresolved.reason}) — fail-closed deny-all`,
+                    message: `tool "${req.toolName}" denied: active skill artifact "${unresolved.lineageId}" manifest could not be resolved (${unresolved.reason}) — fail-closed deny-all`,
                     decisionReason: "safety",
                 };
             }
@@ -49,7 +49,7 @@ export function createActiveSkillScopePolicy(opts) {
                 const ids = manifests.map((m) => m.lineageId).join(", ");
                 return {
                     action: "deny",
-                    reason: `tool "${req.toolName}" is not in the active skill manifest allowlist (artifact(s): ${ids})`,
+                    message: `tool "${req.toolName}" is not in the active skill manifest allowlist (artifact(s): ${ids})`,
                     decisionReason: "safety",
                 };
             }
@@ -68,7 +68,7 @@ export function createActiveSkillScopePolicy(opts) {
                 if (!admitted) {
                     return {
                         action: "deny",
-                        reason: `tool "${req.toolName}" is narrowed by skill manifest "${frame.manifest.lineageId}": ${rejections.join("; ")}`,
+                        message: `tool "${req.toolName}" is narrowed by skill manifest "${frame.manifest.lineageId}": ${rejections.join("; ")}`,
                         decisionReason: "safety",
                     };
                 }
@@ -80,7 +80,7 @@ export function createActiveSkillScopePolicy(opts) {
                     const ids = manifests.filter((m) => m.allowPaths?.length).map((m) => m.lineageId).join(", ");
                     return {
                         action: "deny",
-                        reason: `write-capable tool "${req.toolName}" denied: active skill manifest constrains writes to allowPaths but this tool's target cannot be path-confined (only ${[...PATH_WRITE_TOOLS].join("/")} are) — fail-closed (artifact(s): ${ids})`,
+                        message: `write-capable tool "${req.toolName}" denied: active skill manifest constrains writes to allowPaths but this tool's target cannot be path-confined (only ${[...PATH_WRITE_TOOLS].join("/")} are) — fail-closed (artifact(s): ${ids})`,
                         decisionReason: "safety",
                     };
                 }
@@ -92,7 +92,7 @@ export function createActiveSkillScopePolicy(opts) {
                     if (typeof path !== "string" || path.length === 0) {
                         return {
                             action: "deny",
-                            reason: `write tool "${req.toolName}" denied: active skill manifest constrains writes to allowPaths but the call has no resolvable path`,
+                            message: `write tool "${req.toolName}" denied: active skill manifest constrains writes to allowPaths but the call has no resolvable path`,
                             decisionReason: "safety",
                         };
                     }
@@ -100,7 +100,7 @@ export function createActiveSkillScopePolicy(opts) {
                     if (!canon.ok) {
                         return {
                             action: "deny",
-                            reason: `write to "${path}" denied: its real target could not be resolved against the active skill manifest allowPaths`,
+                            message: `write to "${path}" denied: its real target could not be resolved against the active skill manifest allowPaths`,
                             decisionReason: "safety",
                         };
                     }
@@ -115,7 +115,7 @@ export function createActiveSkillScopePolicy(opts) {
                         if (!inside) {
                             return {
                                 action: "deny",
-                                reason: `write to "${path}" is outside the paths allowed by skill manifest "${m.lineageId}" (allowPaths: ${(m.allowPaths ?? []).join(", ")})`,
+                                message: `write to "${path}" is outside the paths allowed by skill manifest "${m.lineageId}" (allowPaths: ${(m.allowPaths ?? []).join(", ")})`,
                                 decisionReason: "safety",
                             };
                         }

package/dist/core/runner/prepare-memory.js

@@ -1,4 +1,4 @@
-import { deriveControlPlaneDir, deriveProjectControlDir, deriveProjectMemoryDir, deriveRepoMemoryDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, lookupProjectIdHint, recordProjectIdHint, resolveMemoryEngineRoot } from "../memory-engine/layout.js";
+import { adoptLegacyRepoDirs, deriveRepoControlPlaneDir, deriveProjectControlDir, deriveProjectMemoryDir, deriveRepoMemoryDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, lookupProjectIdHint, recordProjectIdHint, resolveMemoryEngineRoot } from "../memory-engine/layout.js";
 import { classifyScopePlanes, derivePersonalControlDir, derivePersonalMemoryDir, mergeHarvestReports, mergeInjections, needsDualRoots, parsedProjectPlane } from "../memory-engine/dual-root.js";
 import { normalizeMemorySpec } from "../memory.js";
 import { MemoryEngine } from "../memory-engine/engine.js";
@@ -15,6 +15,9 @@ export async function prepareMemory(input) {
             const pinned = backend.directoryRoot;
             const engineRoot = resolveMemoryEngineRoot(deps.memoryEngineDir);
             const repoRoot = deps.rootPath ?? taskRootPath;
+            if (repoRoot) {
+                adoptLegacyRepoDirs(engineRoot, repoRoot, (err) => deps.onError?.(err, { phase: "memory", sessionId }));
+            }
             let identityKey;
             if (memorySpec.scopeContract === "v2" && repoRoot) {
                 const consumesProjectIdentity = [...memorySpec.scopes, ...(memorySpec.writeScope !== null ? [memorySpec.writeScope] : [])]
@@ -35,7 +38,7 @@ export async function prepareMemory(input) {
                     recordProjectIdHint(engineRoot, repoRoot, marker.projectId);
                     if (firstSwitch) {
                         try {
-                            const oldCtl = deriveControlPlaneDir(engineRoot, repoRoot);
+                            const oldCtl = deriveRepoControlPlaneDir(engineRoot, repoRoot);
                             const newCtl = deriveProjectControlDir(engineRoot, marker.projectId);
                             const drained = drainMemoryAnnouncements(oldCtl);
                             for (const ann of drained.queue)
@@ -97,7 +100,7 @@ export async function prepareMemory(input) {
                 const projectEngine = new MemoryEngine({
                     backend,
                     memoryDir,
-                    controlDir: identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveControlPlaneDir(engineRoot, repoRoot),
+                    controlDir: identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveRepoControlPlaneDir(engineRoot, repoRoot),
                 });
                 const personalEngine = createPersonalEngine();
                 const p = planes;
@@ -137,7 +140,7 @@ export async function prepareMemory(input) {
                 const engine = new MemoryEngine({
                     backend,
                     memoryDir,
-                    controlDir: identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveControlPlaneDir(engineRoot, repoRoot),
+                    controlDir: identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveRepoControlPlaneDir(engineRoot, repoRoot),
                 });
                 const handle = await engine.materialize(memorySpec.scopes, memorySpec.writeScope);
                 writeEngine = engine;