blun-king-cli 9.1.520 → 9.1.525

package/agent-spine-plugin/src/lib/paths.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { lstat, mkdir, realpath } from "node:fs/promises";
 
 export async function canonicalPath(input = process.cwd()) {
@@ -49,6 +50,54 @@ export function stateRoot(env = process.env) {
   return join(env.XDG_STATE_HOME || join(homedir(), ".local", "state"), "agentspine");
 }
 
+export function comparablePath(value) {
+  let cursor = resolve(value);
+  const missing = [];
+  let canonical = cursor;
+  while (true) {
+    try {
+      canonical = realpathSync.native(cursor);
+      break;
+    } catch (error) {
+      if (error.code !== "ENOENT") break;
+      const parent = dirname(cursor);
+      if (parent === cursor) break;
+      missing.unshift(basename(cursor));
+      cursor = parent;
+    }
+  }
+  canonical = join(canonical, ...missing);
+  return canonical.replace(/[\\/]+$/, "");
+}
+
+function samePath(left, right) {
+  const normalize = comparablePath;
+  const a = normalize(left);
+  const b = normalize(right);
+  return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+
+export function isUserHomeRoot(root, env = process.env) {
+  const candidates = [homedir(), env.HOME, env.USERPROFILE,
+    env.HOMEDRIVE && env.HOMEPATH ? `${env.HOMEDRIVE}${env.HOMEPATH}` : null]
+    .filter((value) => typeof value === "string" && value && isAbsolute(value));
+  return candidates.some((candidate) => samePath(root, candidate));
+}
+
+export function statePathIsScanExcluded(catalog, path, env = process.env) {
+  if (!catalog || catalog.schema !== "agentspine.catalog/v1" || typeof path !== "string") return false;
+  const localStateRoot = stateRoot(env);
+  const pathBelongsToState = isInside(localStateRoot, path);
+  const canonicalRoot = comparablePath(catalog.root);
+  const canonicalStateRoot = comparablePath(localStateRoot);
+  if (!pathBelongsToState && !isInside(canonicalRoot, comparablePath(path))) return true;
+  if (pathBelongsToState && !isInside(canonicalRoot, canonicalStateRoot)) return true;
+  return catalog.scanPolicy?.stateRoot === "excluded"
+    && isUserHomeRoot(canonicalRoot, env)
+    && isInside(canonicalRoot, canonicalStateRoot)
+    && pathBelongsToState;
+}
+
 export function projectId(root) {
   return createHash("sha256").update(root).digest("hex").slice(0, 20);
 }

package/agent-spine-plugin/src/lib/persona-runtime.js

@@ -249,7 +249,7 @@ function sameRuntimeEntity(entity, persona, binding) {
 }
 
 async function reconcilePersonaGraph(paths, policy, runtime) {
-  let { graph } = await loadGraph(paths.catalog.root);
+  let { graph } = await loadGraph(paths.catalog.root, paths.catalog);
   const changes = { groupsCreated: 0, entitiesUpdated: 0, membershipsAdded: 0, membershipsRemoved: 0 };
   const activeGroupIds = [...new Set(runtime.personas
     .filter((item) => item.status === "active" && item.groupId !== null)
@@ -265,9 +265,9 @@ async function reconcilePersonaGraph(paths, policy, runtime) {
     }
     if (!existing) {
       await upsertEntity({ root: paths.catalog.root, id: groupId, kind: "group", privacy: "group",
-        attributes: { identitySource: "authenticated-persona-roster" }, confidence: 1 });
+        attributes: { identitySource: "authenticated-persona-roster" }, confidence: 1, catalog: paths.catalog });
       changes.groupsCreated += 1;
-      graph = (await loadGraph(paths.catalog.root)).graph;
+      graph = (await loadGraph(paths.catalog.root, paths.catalog)).graph;
     }
   }
 
@@ -284,36 +284,40 @@ async function reconcilePersonaGraph(paths, policy, runtime) {
         sourceDocument: existing?.sourceDocument
           && paths.catalog.documents.some((item) => item.relativePath === existing.sourceDocument)
           ? existing.sourceDocument : null,
-        privacy: persona.groupId ? "group" : "shared", confidence: 1 });
+        privacy: persona.groupId ? "group" : "shared", confidence: 1, catalog: paths.catalog });
       changes.entitiesUpdated += 1;
-      graph = (await loadGraph(paths.catalog.root)).graph;
+      graph = (await loadGraph(paths.catalog.root, paths.catalog)).graph;
       existing = graph.entities.find((item) => item.id === persona.personaId);
     }
 
     const memberships = graph.entityEdges.filter((edge) => edge.from === persona.personaId && edge.relation === "member-of");
     for (const edge of memberships.filter((item) => persona.status !== "active" || item.to !== persona.groupId)) {
-      await unlinkEntities({ root: paths.catalog.root, from: edge.from, to: edge.to, relation: edge.relation });
+      await unlinkEntities({ root: paths.catalog.root, from: edge.from, to: edge.to, relation: edge.relation,
+        catalog: paths.catalog });
       changes.membershipsRemoved += 1;
-      graph = (await loadGraph(paths.catalog.root)).graph;
+      graph = (await loadGraph(paths.catalog.root, paths.catalog)).graph;
     }
     if (persona.status === "active" && persona.groupId !== null
       && !graph.entityEdges.some((edge) => edge.from === persona.personaId && edge.to === persona.groupId
         && edge.relation === "member-of" && edge.privacy === "group")) {
       await linkEntities({ root: paths.catalog.root, from: persona.personaId, to: persona.groupId,
-        relation: "member-of", reason: "Authenticated roster membership; context only.", confidence: 1, privacy: "group" });
+        relation: "member-of", reason: "Authenticated roster membership; context only.", confidence: 1, privacy: "group",
+        catalog: paths.catalog });
       changes.membershipsAdded += 1;
-      graph = (await loadGraph(paths.catalog.root)).graph;
+      graph = (await loadGraph(paths.catalog.root, paths.catalog)).graph;
     }
   }
   return changes;
 }
 
-export async function applyPersonaRoster({ root = process.cwd(), bindings, rosterScopes = [], confirmation, now = new Date() }) {
+export async function applyPersonaRoster({
+  root = process.cwd(), bindings, rosterScopes = [], confirmation, now = new Date(), catalog: providedCatalog = null
+}) {
   if (confirmation !== CONFIRMATION) throw new Error("persona roster changes require explicit local owner confirmation");
   if (!Array.isArray(bindings) || bindings.length > 256 || (!bindings.length && !rosterScopes.length)) {
     throw new Error("bindings must contain up to 256 persona bindings or one explicit roster scope");
   }
-  const paths = await pathsFor(root);
+  const paths = await pathsFor(root, providedCatalog);
   return withLock(paths, async () => {
     const [policy, runtime] = await Promise.all([
       readJson(paths.personaPolicyPath, paths.catalog.root, normalizePolicy, emptyPolicy),
@@ -471,11 +475,13 @@ export async function loadPersonaRuntime(root = process.cwd(), providedCatalog =
   return { policy, runtime, ...paths };
 }
 
-export async function syncPersonaRosterFromEnvironment({ root = process.cwd(), env = process.env, now = new Date() } = {}) {
+export async function syncPersonaRosterFromEnvironment({
+  root = process.cwd(), env = process.env, now = new Date(), catalog: providedCatalog = null
+} = {}) {
   const configured = env.AGENTSPINE_PERSONA_ROSTER_FILE;
   if (!configured) return { configured: false, changed: false };
   if (!isAbsolute(configured)) throw new Error("AGENTSPINE_PERSONA_ROSTER_FILE must be an absolute path");
-  const catalog = await buildCatalog(root);
+  const catalog = providedCatalog || await buildCatalog(root);
   const supplied = await lstat(configured);
   if (supplied.isSymbolicLink() || !supplied.isFile()) throw new Error("persona roster must be a regular non-symlink file");
   const canonical = await realpath(configured);
@@ -497,7 +503,7 @@ export async function syncPersonaRosterFromEnvironment({ root = process.cwd(), e
   const rosterScopes = nativeScopes.map((scope) => ({ authenticator: "host-manifest", issuer: scope.issuer,
     tenantId: scope.tenantId, host: scope.host, profileId: scope.profileId }));
   const result = await applyPersonaRoster({ root: catalog.root, bindings, rosterScopes,
-    confirmation: CONFIRMATION, now: value.observedAt || now });
+    confirmation: CONFIRMATION, now: value.observedAt || now, catalog });
   return { configured: true, changed: !result.duplicate || result.graphReconciled,
     rosterChanged: !result.duplicate, graphReconciled: result.graphReconciled, graphChanges: result.graphChanges,
     revision: value.revision,

package/agent-spine-plugin/src/lib/preflight.js

@@ -21,8 +21,8 @@ const ENV_RE = /^[A-Z_][A-Z0-9_]{0,127}$/;
 const MAX_POLICY_BYTES = 1024 * 1024;
 const MAX_STATE_BYTES = 8 * 1024 * 1024;
 const MAX_PROVIDER_BYTES = 1024 * 1024;
-const MAX_REQUIRED_INSTRUCTION_FILE_BYTES = 4 * 1024 * 1024;
-const MAX_REQUIRED_INSTRUCTION_METADATA_BYTES = 4 * 1024;
+const STANDARD_REQUIRED_INSTRUCTIONS_BYTES = 8 * 1024;
+const MAX_CLAUDE_REQUIRED_INSTRUCTIONS_BYTES = 16 * 1024;
 const MAX_REQUIRED_MEMORY_BYTES = 6 * 1024;
 const RECEIPT_TTL_MS = 60_000;
 const FORBIDDEN_MEMORY = /-----BEGIN [A-Z ]*PRIVATE KEY-----|\b(?:sk|gh[opusu])_[A-Za-z0-9_-]{20,}\b|\b(?:password|passwort|secret|token|api[-_ ]?key|credential|permission|rights?|roles?|delegat|authoriz|berechtig|freigabe|approval|tool access|file access|network|production|payment|zahlung|policy)\b/i;
@@ -326,13 +326,16 @@ async function assertNoSymlinkParents(path, allowedRoot) {
   }
   return { root, target };
 }
-async function safeReadRequired(path, allowedRoot, maximum = MAX_REQUIRED_INSTRUCTION_FILE_BYTES, fileHooks = null) {
+async function safeReadRequired(path, allowedRoot, maximum = STANDARD_REQUIRED_INSTRUCTIONS_BYTES, fileHooks = null) {
   const checked = await assertNoSymlinkParents(path, allowedRoot);
   const flags = fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW || 0);
   const handle = await open(checked.target, flags);
   try {
     const before = await handle.stat();
-    if (!before.isFile() || before.size > maximum) throw new Error(`required instruction ${basename(path)} cannot fit the mandatory context budget`);
+    if (!before.isFile()) throw new Error(`required instruction ${basename(path)} is not a regular file`);
+    if (before.size > maximum) {
+      throw new Error(`required instruction ${basename(path)} is ${before.size} bytes; mandatory limit is ${maximum} bytes`);
+    }
     const buffer = Buffer.alloc(Number(before.size));
     let offset = 0;
     while (offset < buffer.length) {
@@ -350,8 +353,8 @@ async function safeReadRequired(path, allowedRoot, maximum = MAX_REQUIRED_INSTRU
       || current.size !== before.size || current.mtimeMs !== before.mtimeMs || current.ctimeMs !== before.ctimeMs) {
       throw new Error(`required instruction ${basename(path)} was replaced during preflight`);
     }
-    return { bytes: buffer.length, sha256: sha256(buffer),
-      identity: sha256(`${before.dev}\0${before.ino}\0${before.size}\0${before.mtimeMs}\0${before.ctimeMs}`) };
+    return { content: buffer.toString("utf8"), bytes: buffer.length, sha256: sha256(buffer),
+      identity: sha256(`${before.dev}\0${before.ino}\0${before.size}\0${before.mtimeMs}\0${before.ctimeMs}`) };
   } finally { await handle.close(); }
 }
 
@@ -374,6 +377,19 @@ function instructionDocuments(catalog, host) {
   return catalog.documents.filter((item) => item.layer === "constitution" && pattern.test(item.relativePath))
     .sort((left, right) => left.precedence - right.precedence || left.relativePath.localeCompare(right.relativePath));
 }
+function instructionBudget(host, usedBytes = 0) {
+  const hardLimitBytes = host === "claude"
+    ? MAX_CLAUDE_REQUIRED_INSTRUCTIONS_BYTES
+    : STANDARD_REQUIRED_INSTRUCTIONS_BYTES;
+  const overflowBytes = Math.max(0, usedBytes - STANDARD_REQUIRED_INSTRUCTIONS_BYTES);
+  return {
+    mode: overflowBytes ? "claude-required-overflow" : "standard",
+    standardBytes: STANDARD_REQUIRED_INSTRUCTIONS_BYTES,
+    hardLimitBytes,
+    usedBytes,
+    overflowBytes
+  };
+}
 async function rejectKnownInstructionSymlinks(resolvedSources, host) {
   const candidates = host === "claude"
     ? [join(resolvedSources.hostHome, "CLAUDE.md"), ...ancestorsBetween(resolvedSources.projectRoot, resolvedSources.cwd)
@@ -485,21 +501,22 @@ export async function runPreflight({ input, scope, resolvedSources, prompt, now
     && item.profileId === exactScope.profileId && item.tenantId === exactScope.tenantId) || null;
   const instructionHost = resolvedSources.host;
   await rejectKnownInstructionSymlinks(resolvedSources, instructionHost);
-  const documents = instructionDocuments(resolvedSources.catalog, instructionHost);
-  const requiredInstructions = [];
-  for (const document of documents) {
-    const allowedRoot = document.sourceScope === "user" ? resolvedSources.hostHome : resolvedSources.projectRoot;
-    const snapshot = await safeReadRequired(document.path, allowedRoot, MAX_REQUIRED_INSTRUCTION_FILE_BYTES, fileHooks);
-    if (snapshot.sha256 !== document.sha256 || snapshot.bytes !== document.bytes) throw new Error(`required instruction changed after source resolution: ${document.relativePath}`);
-    requiredInstructions.push({ path: document.path, displayPath: document.relativePath, scope: document.sourceScope,
-      bytes: snapshot.bytes, sha256: snapshot.sha256, identity: snapshot.identity });
-  }
-  const instructionBriefing = requiredInstructions.map(({ path: _path, identity: _identity, ...item }) => ({
-    ...item, delivery: "host-native", authority: "host-instruction-verified"
-  }));
-  if (Buffer.byteLength(JSON.stringify(instructionBriefing)) > MAX_REQUIRED_INSTRUCTION_METADATA_BYTES) {
-    throw new Error("required host instruction descriptors exceed the mandatory preflight metadata budget");
-  }
+  const documents = instructionDocuments(resolvedSources.catalog, instructionHost);
+  const requiredInstructions = [];
+  let instructionBytes = 0;
+  const maximumInstructionBytes = instructionBudget(instructionHost).hardLimitBytes;
+  for (const document of documents) {
+    const allowedRoot = document.sourceScope === "user" ? resolvedSources.hostHome : resolvedSources.projectRoot;
+    const snapshot = await safeReadRequired(document.path, allowedRoot, maximumInstructionBytes, fileHooks);
+    if (snapshot.sha256 !== document.sha256 || snapshot.bytes !== document.bytes) throw new Error(`required instruction changed after source resolution: ${document.relativePath}`);
+    instructionBytes += snapshot.bytes;
+    if (instructionBytes > maximumInstructionBytes) {
+      throw new Error(`required host instructions total ${instructionBytes} bytes; mandatory limit is ${maximumInstructionBytes} bytes`);
+    }
+    requiredInstructions.push({ path: document.path, displayPath: document.relativePath, scope: document.sourceScope,
+      bytes: snapshot.bytes, sha256: snapshot.sha256, identity: snapshot.identity, content: snapshot.content });
+  }
+  const appliedInstructionBudget = instructionBudget(instructionHost, instructionBytes);
   const memoryState = validateMemories(await readJson(paths.memories, MAX_STATE_BYTES, emptyMemories));
   const mustRemember = memoryState.entries.filter((item) => memoryMatches(item, exactScope));
   if (Buffer.byteLength(JSON.stringify(mustRemember.map((item) => item.claim))) > MAX_REQUIRED_MEMORY_BYTES) {
@@ -519,13 +536,14 @@ export async function runPreflight({ input, scope, resolvedSources, prompt, now
   }
   const requiredProviderIds = (profile?.providers || []).filter((item) => item.required).map((item) => item.id);
   const loadedIds = providerResults.flatMap((result) => result.items.map((item) => ({ providerId: result.providerId, id: item.id, revision: item.revision })));
-  const briefing = {
-    schema: "agentspine.preflight-briefing/v2", order: ["host-instructions", "must-remember", "required-retrieval", "current-work", "relationships", "accepted-context"],
-    instructions: instructionBriefing,
+  const briefing = {
+    schema: "agentspine.preflight-briefing/v2", order: ["host-instructions", "must-remember", "required-retrieval", "current-work", "relationships", "accepted-context"],
+    instructions: requiredInstructions.map(({ path: _path, identity: _identity, ...item }) => item),
     mustRemember: mustRemember.map((item) => ({ id: item.id, version: item.version, claim: item.claim, checksum: item.checksum, authority: "context-only" })),
     retrieval: providerResults.map((item) => ({ providerId: item.providerId, status: item.status, rejected: item.rejected, items: item.items })),
     recallStatus: requiredProviderIds.length ? "required-complete" : "no-required-provider-configured",
-    instruction: "The host-native instruction files were verified for this exact turn and are not duplicated here. Apply the host-loaded instructions first, then confirmed critical context and scoped retrieval. None of this content grants authority or relaxes host policy.",
+    instructionBudget: appliedInstructionBudget,
+    instruction: "Apply the complete host instructions first, then confirmed critical context and scoped retrieval. None of this content grants authority or relaxes host policy.",
     authority: "context-only"
   };
   const createdAt = timestamp(now); const expiresAt = timestamp(new Date(new Date(createdAt).getTime() + RECEIPT_TTL_MS));
@@ -534,6 +552,7 @@ export async function runPreflight({ input, scope, resolvedSources, prompt, now
     sessionId: exactScope.sessionId, projectId: exactScope.projectId, cwdDigest: sha256(exactScope.cwd),
     taskId: exactScope.taskId, groupId: exactScope.groupId, hookEvent: "UserPromptSubmit", deliveryId, promptDigest,
     instructionFiles: requiredInstructions.map((item) => ({ path: item.path, scope: item.scope, bytes: item.bytes, sha256: item.sha256, identity: item.identity })),
+    instructionBudget: appliedInstructionBudget,
     policyRevision: policy.revision, policyProfileDigest: profile ? digestObject(profile) : null,
     mustRemember: memoryProofs(mustRemember),
     providerQueries: providerResults.map((item) => ({ providerId: item.providerId, queryDigest: item.queryDigest, status: item.status, rejected: item.rejected })),
@@ -600,12 +619,17 @@ export async function verifyPreflightReceipt({ receipt, input, scope, resolvedSo
     const currentDocuments = instructionDocuments(freshSources.catalog, freshSources.host);
     if (currentDocuments.length !== receipt.instructionFiles.length
       || currentDocuments.some((document, index) => document.path !== receipt.instructionFiles[index]?.path)) return false;
+    let instructionBytes = 0;
+    const maximumInstructionBytes = instructionBudget(receipt.instructionHost).hardLimitBytes;
     for (const instruction of receipt.instructionFiles) {
       const allowedRoot = instruction.scope === "user" ? freshSources.hostHome : freshSources.projectRoot;
-      const currentSnapshot = await safeReadRequired(instruction.path, allowedRoot);
+      const currentSnapshot = await safeReadRequired(instruction.path, allowedRoot, maximumInstructionBytes);
       if (currentSnapshot.sha256 !== instruction.sha256 || currentSnapshot.bytes !== instruction.bytes
         || currentSnapshot.identity !== instruction.identity) return false;
+      instructionBytes += currentSnapshot.bytes;
     }
+    if (instructionBytes > maximumInstructionBytes
+      || canonical(receipt.instructionBudget) !== canonical(instructionBudget(receipt.instructionHost, instructionBytes))) return false;
   } catch { return false; }
   if (consume) {
     const paths = storagePaths(env);

package/agent-spine-plugin/src/lib/source-roots.js

@@ -6,6 +6,7 @@ import { ancestorsBetween, canonicalPath, isInside, stateRoot } from "./paths.js
 import { indexExplicitDocuments } from "./documents.js";
 import { isFileLockContention, replaceFileWithRetry } from "./filesystem-retry.js";
 import { purgeIndexedMemoryCache, resolveIndexedMemory } from "./indexed-memory.js";
+import { catalogScanPolicy } from "./catalog.js";
 
 export const SOURCE_REGISTRY_SCHEMA = "agentspine.source-roots/v1";
 const MAX_REGISTRY_BYTES = 1024 * 1024;
@@ -109,6 +110,21 @@ function expandHome(value, home) {
   return value;
 }
 
+function samePath(left, right) {
+  const normalize = (value) => resolve(value).replace(/[\\/]+$/, "");
+  const a = normalize(left);
+  const b = normalize(right);
+  return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+
+async function homeRoots(env) {
+  const candidates = [homedir(), env.HOME, env.USERPROFILE,
+    env.HOMEDRIVE && env.HOMEPATH ? `${env.HOMEDRIVE}${env.HOMEPATH}` : null]
+    .filter((value) => typeof value === "string" && value && isAbsolute(value));
+  return [...new Set(await Promise.all(candidates.map(async (value) =>
+    await existingDirectory(value) || resolve(value))))];
+}
+
 async function readJsonObject(path) {
   const file = await existingRegular(path);
   if (!file) return null;
@@ -150,16 +166,22 @@ async function findRoot(cwd, markers) {
   let cursor = cwd;
   while (true) {
     for (const marker of markers) {
-      try { await lstat(join(cursor, marker)); return cursor; } catch (error) {
+      try { await lstat(join(cursor, marker)); return { root: cursor, resolution: "project-marker" }; } catch (error) {
         if (error.code !== "ENOENT") throw error;
       }
     }
     const parent = dirname(cursor);
-    if (parent === cursor) return cwd;
+    if (parent === cursor) return { root: cwd, resolution: "cwd-fallback" };
     cursor = parent;
   }
 }
 
+function skippedExtraDirectory(name) {
+  const lower = name.toLowerCase();
+  return SKIP_EXTRA_DIRS.has(name) || SKIP_EXTRA_DIRS.has(lower)
+    || lower.includes("dropbox") || lower === "onedrive" || lower.startsWith("onedrive - ");
+}
+
 async function containsProjectMarker(directory) {
   try {
     await lstat(join(directory, ".git"));
@@ -201,7 +223,7 @@ async function boundedMarkdownTree(directory, prefix, host, scope, precedenceSta
       if (output.length >= maxFiles) throw new Error(`host-native rule tree exceeds ${maxFiles} files`);
       if (entry.isSymbolicLink()) continue;
       const path = join(current, entry.name);
-      if (entry.isDirectory() && !entry.name.startsWith(".") && !SKIP_EXTRA_DIRS.has(entry.name)) await walk(path);
+      if (entry.isDirectory() && !entry.name.startsWith(".") && !skippedExtraDirectory(entry.name)) await walk(path);
       else if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
         output.push({ path, id: `${prefix}/${relative(root, path).replaceAll("\\", "/")}`, host, scope,
           binding: "host-native-rule-tree", precedence: precedenceStart + output.length });
@@ -390,23 +412,29 @@ export async function resolveHostSourceCatalog({ host, cwd = process.cwd(), inpu
   let projectRoot;
   let sources;
   let hostDetails = {};
+  let rootResolution = "explicit-root";
   if (host === "codex") {
     const codexHome = env.CODEX_HOME || env.BLUN_HOME || join(homedir(), ".codex");
     hostHome = await existingDirectory(resolve(codexHome)) || resolve(codexHome);
     const config = await codexConfig(hostHome);
-    projectRoot = env.AGENTSPINE_ROOT ? await canonicalPath(env.AGENTSPINE_ROOT) : await findRoot(canonicalCwd, config.rootMarkers);
+    if (env.AGENTSPINE_ROOT) projectRoot = await canonicalPath(env.AGENTSPINE_ROOT);
+    else ({ root: projectRoot, resolution: rootResolution } = await findRoot(canonicalCwd, config.rootMarkers));
     sources = await codexSources({ cwd: canonicalCwd, projectRoot, codexHome: hostHome, config });
     hostDetails = { rootMarkers: config.rootMarkers, fallbackNames: config.fallbackNames };
   } else {
     hostHome = await existingDirectory(resolve(env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude")))
       || resolve(env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"));
-    projectRoot = env.AGENTSPINE_ROOT ? await canonicalPath(env.AGENTSPINE_ROOT) : await findRoot(canonicalCwd, [".git"]);
+    if (env.AGENTSPINE_ROOT) projectRoot = await canonicalPath(env.AGENTSPINE_ROOT);
+    else ({ root: projectRoot, resolution: rootResolution } = await findRoot(canonicalCwd, [".git"]));
     const result = await claudeSources({ cwd: canonicalCwd, projectRoot, configDir: hostHome, input, env, registry, deadline, memoryHooks });
     sources = result.sources;
     hostDetails = { memoryRoot: result.memoryRoot, memoryProvenance: result.memoryProvenance,
       memoryDiagnostics: result.memoryDiagnostics };
   }
-  if (projectRoot !== homedir() && projectRoot !== dirname(hostHome)) {
+  const knownHomeRoots = await homeRoots(env);
+  const skippedHomeTree = knownHomeRoots.some((root) => samePath(root, projectRoot));
+  const skippedFallbackHomeTree = skippedHomeTree && rootResolution === "cwd-fallback";
+  if (!skippedHomeTree) {
     sources.push(...await boundedMarkdownTree(projectRoot, "agentspine:project", host, "project", 3000, deadline,
       { projectBoundary: true, maxFiles: MAX_PROJECT_FILES, maxDirectoryEntries: MAX_PROJECT_DIRECTORY_ENTRIES }));
   }
@@ -429,7 +457,9 @@ export async function resolveHostSourceCatalog({ host, cwd = process.cwd(), inpu
     scopes: Object.fromEntries(["user", "project", "project-memory"].map((scope) => [scope, documents.filter((item) => item.sourceScope === scope).length])),
     reason: documents.length ? null : "No regular, non-symlink host-native Markdown source exists in the checked scope.",
     personalContinuityLoaded: documents.some((item) => item.sourceScope === "user") || Boolean(activeUserState),
-    broadHomeScan: false, registryRevision: registry.revision,
+    broadHomeScan: false, projectTreeScan: skippedFallbackHomeTree ? "skipped-unmarked-home"
+      : skippedHomeTree ? "skipped-home-root" : "bounded",
+    rootResolution, registryRevision: registry.revision,
     ...(host === "claude" ? {
       memoryBound: Boolean(hostDetails.memoryRoot),
       memoryRootDigest: hostDetails.memoryRoot ? digest(hostDetails.memoryRoot).slice(0, 16) : null,
@@ -442,6 +472,7 @@ export async function resolveHostSourceCatalog({ host, cwd = process.cwd(), inpu
   };
   const catalog = {
     schema: "agentspine.catalog/v1", generatedAt: new Date().toISOString(), root: projectRoot,
+    scanPolicy: catalogScanPolicy(projectRoot, env),
     preservation: "source-files-are-read-only", documents, conflicts: [], sourceRegistry: diagnostics,
     summary: { total: documents.length, protected: documents.filter((item) => item.protected).length, conflicts: 0,
       byLayer: Object.fromEntries([...new Set(documents.map((item) => item.layer))].sort().map((layer) => [layer, documents.filter((item) => item.layer === layer).length])) }

package/agent-spine-plugin/src/mcp.js

@@ -10,7 +10,7 @@ import {
 } from "./lib/attention.js";
 import {
   addLearningEvidence, configureLearning, deleteLearning, evaluateLearning,
-  learningContext, proposeLearning, reviewLearning, rollbackLearning
+  learningContext, learningOutcomeStatus, proposeLearning, reviewLearning, rollbackLearning
 } from "./lib/learning.js";
 import { checkDelegation, createTask, taskContext, updateTask } from "./lib/coordination.js";
 import { sharedContext } from "./lib/sharing.js";
@@ -46,6 +46,8 @@ const tools = [
         root: { type: "string" }, cwd: { type: "string" },
         host: { type: "string", enum: ["codex", "claude", "generic"] },
         entityId: { anyOf: [{ type: "string" }, { type: "null" }] },
+        userId: { anyOf: [{ type: "string" }, { type: "null" }] },
+        tenantId: { anyOf: [{ type: "string" }, { type: "null" }] },
         groupId: { anyOf: [{ type: "string" }, { type: "null" }] },
         projectId: { anyOf: [{ type: "string" }, { type: "null" }] },
         currentTaskId: { anyOf: [{ type: "string" }, { type: "null" }] },
@@ -240,10 +242,18 @@ const tools = [
       type: "object", required: ["kind", "claim", "evidence"],
       properties: {
         root: { type: "string" }, id: { type: "string" },
-        kind: { type: "string", enum: ["preference", "no-go", "goal", "correction", "personal-fact", "project-fact", "reference"] },
+        kind: { type: "string", enum: ["preference", "no-go", "goal", "correction", "personal-fact", "project-fact", "reference", "behavior"] },
         claim: { type: "string", maxLength: 1000 }, subjectId: { anyOf: [{ type: "string" }, { type: "null" }] },
         privacy: { type: "string", enum: ["private", "shared", "group"] },
         groupId: { anyOf: [{ type: "string" }, { type: "null" }] },
+        scope: {
+          type: "object", additionalProperties: false,
+          properties: {
+            personaId: { anyOf: [{ type: "string" }, { type: "null" }] }, userId: { anyOf: [{ type: "string" }, { type: "null" }] },
+            tenantId: { anyOf: [{ type: "string" }, { type: "null" }] }, projectId: { anyOf: [{ type: "string" }, { type: "null" }] },
+            groupId: { anyOf: [{ type: "string" }, { type: "null" }] }, taskId: { anyOf: [{ type: "string" }, { type: "null" }] }
+          }
+        },
         supersedesId: { anyOf: [{ type: "string" }, { type: "null" }] },
         evidence: { "$ref": "#/$defs/evidence" }
       },
@@ -297,11 +307,40 @@ const tools = [
       properties: {
         root: { type: "string" }, includePrivate: { type: "boolean" },
         groupId: { anyOf: [{ type: "string" }, { type: "null" }] },
-        kinds: { type: "array", items: { type: "string", enum: ["preference", "no-go", "goal", "correction", "personal-fact", "project-fact", "reference"] } },
+        scope: {
+          type: "object", additionalProperties: false,
+          properties: {
+            personaId: { anyOf: [{ type: "string" }, { type: "null" }] }, userId: { anyOf: [{ type: "string" }, { type: "null" }] },
+            tenantId: { anyOf: [{ type: "string" }, { type: "null" }] }, projectId: { anyOf: [{ type: "string" }, { type: "null" }] },
+            groupId: { anyOf: [{ type: "string" }, { type: "null" }] }, taskId: { anyOf: [{ type: "string" }, { type: "null" }] }
+          }
+        },
+        kinds: { type: "array", items: { type: "string", enum: ["preference", "no-go", "goal", "correction", "personal-fact", "project-fact", "reference", "behavior"] } },
         subjectIds: { type: "array", items: { type: "string" } }, maxItems: { type: "integer", minimum: 0, maximum: 50 }
       }
     }
   },
+  {
+    name: "learning_outcome_status",
+    description: "Read outcome receipt counts, contradiction state, and canary health for learned context. This read-only view is context-only and cannot record evidence, promote learning, or grant authority.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        root: { type: "string" },
+        scope: {
+          type: "object", additionalProperties: false,
+          properties: {
+            personaId: { anyOf: [{ type: "string" }, { type: "null" }] },
+            userId: { anyOf: [{ type: "string" }, { type: "null" }] },
+            tenantId: { anyOf: [{ type: "string" }, { type: "null" }] },
+            projectId: { anyOf: [{ type: "string" }, { type: "null" }] },
+            groupId: { anyOf: [{ type: "string" }, { type: "null" }] },
+            taskId: { anyOf: [{ type: "string" }, { type: "null" }] }
+          }
+        }
+      }
+    }
+  },
   {
     name: "evaluate_learning",
     description: "Evaluate pending candidates against the opt-in low-risk auto-promotion policy. Auto-promotion is disabled by default and limited to project facts and references.",
@@ -326,7 +365,13 @@ const tools = [
           type: "object", additionalProperties: false,
           properties: {
             autoPromote: { type: "boolean" }, minConfidence: { type: "number", minimum: 0.5, maximum: 1 },
-            minEvidence: { type: "integer", minimum: 1, maximum: 10 }, maxContextItems: { type: "integer", minimum: 1, maximum: 50 }
+            minEvidence: { type: "integer", minimum: 1, maximum: 10 }, maxContextItems: { type: "integer", minimum: 1, maximum: 50 },
+            minOutcomeReceipts: { type: "integer", minimum: 2, maximum: 10 },
+            minImprovement: { type: "number", minimum: 0, maximum: 1 },
+            regressionTolerance: { type: "number", minimum: 0, maximum: 1 },
+            outcomeMaxAgeDays: { type: "integer", minimum: 1, maximum: 365 },
+            canaryReceipts: { type: "integer", minimum: 1, maximum: 10 },
+            canaryTtlDays: { type: "integer", minimum: 1, maximum: 90 }
           }
         }
       }
@@ -459,6 +504,7 @@ async function callTool(name, args = {}) {
   if (name === "add_learning_evidence") return textResult(await addLearningEvidence({ ...args, root }));
   if (name === "review_learning") return textResult(await reviewLearning({ ...args, root }));
   if (name === "learning_context") return textResult(await learningContext({ ...args, root }));
+  if (name === "learning_outcome_status") return textResult(await learningOutcomeStatus({ ...args, root }));
   if (name === "evaluate_learning") return textResult(await evaluateLearning({ ...args, root }));
   if (name === "rollback_learning") return textResult(await rollbackLearning({ ...args, root }));
   if (name === "configure_learning") return textResult(await configureLearning({ ...args, root }));

package/agent-spine-plugin/src/version.js

@@ -1 +1 @@
-export const VERSION = "0.10.1";
+export const VERSION = "0.11.4";

package/bin/telegram-approval-relay.cjs

@@ -68,6 +68,8 @@ function resolveTelegramApprovalTarget(allowFrom, configuredChatId) {
     : [];
   const configured = String(configuredChatId ?? '').trim();
   if (configured.length > 0) return allowed.includes(configured) ? configured : null;
+  const privateChats = allowed.filter((value) => /^[1-9]\d*$/u.test(value));
+  if (privateChats.length === 1) return privateChats[0];
   return allowed.length === 1 ? allowed[0] : null;
 }