blun-king-cli 9.1.520 → 9.1.525

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

@@ -1,4 +1,4 @@
-import { buildCatalog } from "./catalog.js";
+import { buildCatalog, catalogForStateRoot } from "./catalog.js";
 import { resolveContext } from "./context.js";
 import { relationshipContext } from "./graph.js";
 import { learningContext } from "./learning.js";
@@ -107,7 +107,7 @@ async function settleReads(promises) {
  */
 export async function sessionBriefing({
   root = process.cwd(), cwd = root, host = "generic", entityId = null,
-  groupId = null, projectId = null, currentTaskId = null,
+  userId = null, tenantId = null, groupId = null, projectId = null, currentTaskId = null,
   includePrivate = false, focusActive = true, includeSourceContent = true,
   maxBytes = 16384, now = new Date(), catalog: providedCatalog = null, userStateRoot = null,
   sourceDiagnostics = null, prompt = null
@@ -123,13 +123,18 @@ export async function sessionBriefing({
     catalog
   });
   const portableRelationship = Boolean(entityId && userStateRoot && userStateRoot !== catalog.root);
+  const userCatalog = userStateRoot && userStateRoot !== catalog.root
+    ? catalogForStateRoot(catalog, userStateRoot) : catalog;
+  const learningScope = {
+    personaId: entityId, userId, tenantId, projectId, groupId, taskId: currentTaskId
+  };
   const relationship = entityId
     ? await relationshipContext(userStateRoot && userStateRoot !== catalog.root
-      ? { root: userStateRoot, entityId, includePrivate, groupId }
+      ? { root: userStateRoot, entityId, includePrivate, groupId, catalog: userCatalog }
       : { root: catalog.root, entityId, includePrivate, groupId, catalog })
     : null;
   const [learned, attention, tasks, shared, userLearned, personas, gateway] = await settleReads([
-    learningContext({ root: catalog.root, includePrivate, groupId, maxItems: 50, catalog }),
+    learningContext({ root: catalog.root, includePrivate, groupId, scope: learningScope, maxItems: 50, catalog, now }),
     attentionContext({
       root: catalog.root, includePrivate, entityId, groupId, projectId, currentTaskId,
       focusActive, markPresented: false, maxItems: 20, now, catalog
@@ -137,7 +142,8 @@ export async function sessionBriefing({
     taskContext({ root: catalog.root, includePrivate, groupId, projectId, includeClosed: false, maxItems: 100, catalog }),
     sharedContext({ root: catalog.root, includePrivate, groupId, maxItems: 50, catalog }),
     userStateRoot && userStateRoot !== catalog.root
-      ? learningContext({ root: userStateRoot, includePrivate, groupId, maxItems: 50 })
+      ? learningContext({ root: userStateRoot, includePrivate, groupId, scope: learningScope, maxItems: 50, now,
+        catalog: userCatalog })
       : Promise.resolve({ items: [] }),
     loadPersonaRuntime(catalog.root, catalog),
     loadGatewayRuntime(catalog.root, catalog)
@@ -157,11 +163,17 @@ export async function sessionBriefing({
     root: catalog.root,
     cwd: sources.cwd,
     host,
-    scope: { entityId, groupId, projectId, includePrivate },
+    scope: { entityId, userId, tenantId, groupId, projectId, includePrivate },
     focus: { active: Boolean(focusActive), currentTaskId },
     sources: { documents: [], diagnostics: sourceDiagnostics },
     tasks: [],
-    relationship: relationship ? { entity: null, relatedEntities: [], edges: [] } : null,
+    relationship: relationship ? {
+      status: relationship.status || "loaded",
+      reason: relationship.reason || null,
+      entity: null,
+      relatedEntities: [],
+      edges: []
+    } : null,
     voiceBrief: {
       schema: "agentspine.voice-brief/v1",
       personaId: entityId,
@@ -231,7 +243,7 @@ export async function sessionBriefing({
     if (binding?.sourceBinding && !tryAdd(result, result.voiceBrief.personaSources, binding.sourceBinding)) countOmitted(result, "voice");
   }
 
-  if (relationship) {
+  if (relationship && relationship.status !== "degraded") {
     if (!trySet(result, result.relationship, "entity", relationship.entity)) countOmitted(result, "relationships");
     if (!registeredPersona && !trySet(result, result.voiceBrief, "displayName", relationship.entity.displayName || null)) countOmitted(result, "voice");
     const language = typeof relationship.entity.attributes?.language === "string"

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

@@ -2,12 +2,36 @@ import { randomUUID } from "node:crypto";
 import { open, readFile, stat, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
-import { canonicalPath, projectStateDir } from "./paths.js";
+import { canonicalPath, comparablePath, isInside, projectStateDir, stateRoot } from "./paths.js";
 import { discoverDocuments } from "./documents.js";
 import { isFileLockContention, replaceFileWithRetry } from "./filesystem-retry.js";
 
 export const CATALOG_SCHEMA = "agentspine.catalog/v1";
 
+export function catalogScanPolicy(root, env = process.env) {
+  return {
+    stateRoot: isInside(comparablePath(root), comparablePath(stateRoot(env))) ? "excluded" : "outside",
+    authority: "scanner-boundary-only"
+  };
+}
+
+export function catalogForStateRoot(catalog, root) {
+  if (!catalog || catalog.schema !== CATALOG_SCHEMA || typeof root !== "string" || !root) {
+    throw new Error("a resolved catalog and state root are required");
+  }
+  if (catalog.root === root) return catalog;
+  return {
+    schema: CATALOG_SCHEMA,
+    generatedAt: catalog.generatedAt,
+    root,
+    scanPolicy: catalogScanPolicy(root),
+    preservation: "source-files-are-read-only",
+    documents: [],
+    conflicts: [],
+    summary: { total: 0, protected: 0, conflicts: 0, byLayer: {} }
+  };
+}
+
 function catalogConflicts(documents) {
   const byPath = new Map(documents.map((document) => [document.relativePath, document]));
   const conflicts = [];
@@ -41,9 +65,9 @@ function catalogConflicts(documents) {
   return conflicts.sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
 }
 
-export async function buildCatalog(inputRoot = process.cwd()) {
+export async function buildCatalog(inputRoot = process.cwd(), { env = process.env } = {}) {
   const root = await canonicalPath(inputRoot);
-  const documents = await discoverDocuments(root);
+  const documents = await discoverDocuments(root, { excludeRoots: [stateRoot(env)] });
   const conflicts = catalogConflicts(documents);
   const byLayer = Object.fromEntries(
     [...new Set(documents.map((document) => document.layer))]
@@ -54,6 +78,7 @@ export async function buildCatalog(inputRoot = process.cwd()) {
     schema: CATALOG_SCHEMA,
     generatedAt: new Date().toISOString(),
     root,
+    scanPolicy: catalogScanPolicy(root, env),
     preservation: "source-files-are-read-only",
     documents,
     conflicts,

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

@@ -531,7 +531,7 @@ function activeBinding(policy, event) {
 
 export async function claimChannelEvent({
   root = process.cwd(), agentId, projectId, groupId = null, provider, workerId,
-  eventId = null, leaseSeconds = 120, now = new Date()
+  eventId = null, leaseSeconds = 120, now = new Date(), catalog: providedCatalog = null
 }) {
   agentId = stableId(agentId, "agentId");
   projectId = stableId(projectId, "projectId");
@@ -541,7 +541,7 @@ export async function claimChannelEvent({
   eventId = stableId(eventId, "eventId", { nullable: true });
   const seconds = Number(leaseSeconds);
   if (!Number.isInteger(seconds) || seconds < 15 || seconds > 900) throw new Error("leaseSeconds must be an integer between 15 and 900");
-  const paths = await pathsFor(root);
+  const paths = await pathsFor(root, providedCatalog);
   return withChannelLock(paths, async () => {
     const [policy, runtime, { graph }] = await Promise.all([
       readJson(paths.channelPolicyPath, paths.catalog.root, normalizePolicy, emptyPolicy),

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

@@ -137,8 +137,8 @@ export async function inspectContinuity(root = process.cwd(), providedCatalog =
   }
 }
 
-async function mutate(root, task) {
-  const catalog = await buildCatalog(root);
+async function mutate(root, task, providedCatalog = null) {
+  const catalog = providedCatalog || await buildCatalog(root);
   const { continuityPath } = await loadContinuity(catalog.root, catalog);
   return withLock(continuityPath, catalog.root, (state) => task(state, catalog, continuityPath));
 }
@@ -209,9 +209,12 @@ function assertSafeSignal(signal, prompt, scope) {
 
 export async function captureContinuityPrompt({
   root = process.cwd(), prompt, entityId = null, groupId = null, projectId = null,
-  eventId = null, now = new Date(), userStateRoot = null
+  eventId = null, now = new Date(), userStateRoot = null, catalog: providedCatalog = null,
+  userCatalog: providedUserCatalog = null
 }) {
-  const { continuity, catalog } = await loadContinuity(userStateRoot || root);
+  const storageCatalog = userStateRoot && userStateRoot !== root
+    ? providedUserCatalog : providedCatalog;
+  const { continuity, catalog } = await loadContinuity(userStateRoot || root, storageCatalog);
   if (!continuity.config.enabled) return { enabled: false, captured: false, reason: "opt-in-disabled", authority: "context-only" };
   if (typeof prompt !== "string" || Buffer.byteLength(prompt) > continuity.config.maxPromptBytes) {
     throw new Error("prompt payload is missing or exceeds the configured byte limit");
@@ -222,8 +225,9 @@ export async function captureContinuityPrompt({
   const subjectId = detected.kind === "project-fact" ? projectId : entityId || projectId;
   if (!subjectId || !ID_RE.test(subjectId)) throw new Error("automatic learning requires an exact known person or project identity");
   if (groupId !== null && !ID_RE.test(groupId)) throw new Error("groupId is invalid");
-  const storageCatalog = storageRoot === catalog.root ? catalog : await buildCatalog(storageRoot);
-  const { graph } = await loadGraph(storageCatalog.root, storageCatalog);
+  const targetCatalog = storageRoot === catalog.root ? catalog
+    : providedCatalog || await buildCatalog(storageRoot);
+  const { graph } = await loadGraph(targetCatalog.root, targetCatalog);
   const subject = graph.entities.find((item) => item.id === subjectId);
   if (!subject) throw new Error(`automatic learning requires a known canonical identity: ${subjectId}`);
   if (subjectId === projectId && subject.kind !== "project") throw new Error("projectId must identify a project");
@@ -248,7 +252,7 @@ export async function captureContinuityPrompt({
     });
     state.history.push({ kind: "signal-observed", eventKey, learningId, subjectId, observedAt: at, authority: "context-only" });
     return { duplicate: false, disabled: false, config: state.config, continuityPath, catalog };
-  });
+  }, targetCatalog);
   if (recorded.disabled) return { enabled: false, captured: false, reason: "opt-in-disabled", authority: "context-only" };
 
   const evidence = {
@@ -258,26 +262,27 @@ export async function captureContinuityPrompt({
     confidence: detected.confidence,
     observedAt: at
   };
-  let existing = (await loadLearning(storageRoot)).learning.candidates.find((item) => item.id === learningId);
+  let existing = (await loadLearning(storageRoot, targetCatalog)).learning.candidates.find((item) => item.id === learningId);
   if (!existing) {
     try {
       await proposeLearning({
         root: storageRoot, id: learningId, kind: detected.kind, claim: detected.claim, subjectId,
-        privacy: subjectId === projectId ? "shared" : "private", groupId: null, evidence, now: at
+        privacy: subjectId === projectId ? "shared" : "private", groupId: null, evidence, now: at,
+        catalog: targetCatalog
       });
     } catch (error) {
       if (!/candidate IDs are immutable/.test(error.message)) throw error;
     }
-    existing = (await loadLearning(storageRoot)).learning.candidates.find((item) => item.id === learningId);
+    existing = (await loadLearning(storageRoot, targetCatalog)).learning.candidates.find((item) => item.id === learningId);
   }
   if (existing?.status === "candidate" && !existing.evidence.some((item) => item.id === evidence.id)) {
     try {
-      await addLearningEvidence({ root: storageRoot, id: learningId, evidence, now: at });
+      await addLearningEvidence({ root: storageRoot, id: learningId, evidence, now: at, catalog: targetCatalog });
     } catch (error) {
       if (!/duplicate evidence id|unreviewed candidate/.test(error.message)) throw error;
     }
   }
-  const refreshed = (await loadLearning(storageRoot)).learning.candidates.find((item) => item.id === learningId);
+  const refreshed = (await loadLearning(storageRoot, targetCatalog)).learning.candidates.find((item) => item.id === learningId);
   let accepted = refreshed?.status === "accepted";
   if (!accepted && refreshed?.status === "candidate") {
     const distinct = new Set(refreshed.evidence.map((item) => item.id)).size;
@@ -286,7 +291,7 @@ export async function captureContinuityPrompt({
       && detected.directness >= recorded.config.minDirectness
       && distinct >= requiredEvidence) {
       await acceptContinuityLearning({
-        root: storageRoot, id: learningId, now: at,
+        root: storageRoot, id: learningId, now: at, catalog: targetCatalog,
         proof: {
           mode: "automatic-continuity-low-risk", localOptIn: true,
           minConfidence: recorded.config.minConfidence,

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

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { lstat, opendir, readFile, realpath, stat } from "node:fs/promises";
-import { basename, dirname, extname, join, relative, resolve } from "node:path";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 
 const SKIP_DIRS = new Set([
   ".git", ".hg", ".svn", ".next", ".nuxt", ".turbo", ".venv",
@@ -132,7 +132,12 @@ export function extractMarkdownLinks(text, filePath, root) {
   return [...links].sort();
 }
 
-async function walk(directory, found) {
+function isInside(parent, child) {
+  const value = relative(parent, child);
+  return value === "" || (!isAbsolute(value) && !value.startsWith(`..${sep}`) && value !== "..");
+}
+
+async function walk(directory, found, excludedRoots) {
   const entries = [];
   for await (const entry of await opendir(directory)) entries.push(entry);
   entries.sort((a, b) => a.name.localeCompare(b.name));
@@ -140,16 +145,29 @@ async function walk(directory, found) {
     if (entry.isSymbolicLink()) continue;
     const fullPath = join(directory, entry.name);
     if (entry.isDirectory()) {
-      if (!SKIP_DIRS.has(entry.name)) await walk(fullPath, found);
+      if (!SKIP_DIRS.has(entry.name) && !excludedRoots.some((root) => isInside(root, fullPath))) {
+        await walk(fullPath, found, excludedRoots);
+      }
     } else if (entry.isFile() && extname(entry.name).toLowerCase() === ".md") {
       found.push(fullPath);
     }
   }
 }
 
-export async function discoverDocuments(root) {
+export async function discoverDocuments(root, { excludeRoots = [] } = {}) {
   const files = [];
-  await walk(root, files);
+  // Canonicalize existing exclusion roots just like the scanned root. On macOS
+  // temporary directories commonly cross /var -> /private/var, while Windows
+  // may expose the same directory through differently cased/normalized paths.
+  // Comparing only resolved spellings would therefore walk the private state
+  // directory even though it is the configured exclusion boundary.
+  const excludedRoots = (await Promise.all(excludeRoots.map(async (path) => {
+    try { return await realpath(resolve(path)); } catch (error) {
+      if (error.code === "ENOENT") return resolve(path);
+      throw error;
+    }
+  }))).filter((path) => isInside(root, path));
+  await walk(root, files, excludedRoots);
   const documents = new Array(files.length);
   let cursor = 0;
   async function worker() {

package/agent-spine-plugin/src/lib/feed-transport.js

@@ -15,7 +15,7 @@ import {
 import {
   httpsObjectUrl, putHttpsSnapshot, validateHttpsObjectBase
 } from "./object-transport.js";
-import { isInside, projectStateDir } from "./paths.js";
+import { projectStateDir, statePathIsScanExcluded } from "./paths.js";
 
 const SCHEMA = "agentspine.feed/v1";
 const STATE_SCHEMA = "agentspine.feed-state/v1";
@@ -358,7 +358,9 @@ function validateState(state, root) {
 async function feedStatePaths(root) {
   const catalog = await buildCatalog(root);
   const directory = await projectStateDir(catalog.root);
-  if (isInside(catalog.root, directory)) throw new Error("HTTPS feed state must remain outside the scanned project");
+  if (!statePathIsScanExcluded(catalog, directory)) {
+    throw new Error("HTTPS feed state must remain outside the scanned project or in an excluded home-state root");
+  }
   return { root: catalog.root, path: join(directory, "feed-state.json") };
 }
 

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

@@ -1,7 +1,7 @@
 import { readFile, rename, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { buildCatalog } from "./catalog.js";
-import { projectStateDir } from "./paths.js";
+import { canonicalPath, projectStateDir } from "./paths.js";
 
 const RELATIONS = new Set([
   "loads", "belongs-to", "explains", "supports", "related",
@@ -100,6 +100,21 @@ export async function loadGraph(root, providedCatalog = null) {
   }
 }
 
+async function loadRelationshipGraph(root, providedCatalog = null, { signal = null } = {}) {
+  const canonicalRoot = providedCatalog?.root || await canonicalPath(root);
+  const directory = await projectStateDir(canonicalRoot);
+  const path = join(directory, "graph.json");
+  try {
+    const metadata = await stat(path);
+    if (metadata.size > 5 * 1024 * 1024) throw new Error("relationship graph exceeds the 5 MiB read limit");
+    const content = await readFile(path, { encoding: "utf8", signal });
+    return { graph: normalizeGraph(JSON.parse(content), canonicalRoot), graphPath: path };
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    return { graph: emptyGraph(canonicalRoot), graphPath: path };
+  }
+}
+
 async function saveGraph(graph, path) {
   const temporary = `${path}.${process.pid}.tmp`;
   const content = `${JSON.stringify(graph, null, 2)}\n`;
@@ -159,13 +174,13 @@ export async function annotateDocument({ root = process.cwd(), path, layer, reas
 
 export async function upsertEntity({
   root = process.cwd(), id, kind, displayName = "", aliases = [],
-  attributes = {}, sourceDocument = null, confidence = 0.5, privacy = "private"
+  attributes = {}, sourceDocument = null, confidence = 0.5, privacy = "private", catalog: providedCatalog = null
 }) {
   if (!id || !/^[A-Za-z0-9][A-Za-z0-9:_.@/-]{0,127}$/.test(id)) throw new Error("id must be a stable, whitespace-free identifier");
   if (!ENTITY_KINDS.has(kind)) throw new Error(`unsupported entity kind: ${kind}`);
   if (!["private", "shared", "group"].includes(privacy)) throw new Error(`unsupported privacy scope: ${privacy}`);
   if (!attributes || Array.isArray(attributes) || typeof attributes !== "object") throw new Error("attributes must be an object");
-  const { graph, graphPath, catalog } = await loadGraph(root);
+  const { graph, graphPath, catalog } = await loadGraph(root, providedCatalog);
   if (sourceDocument !== null) {
     sourceDocument = normalizeRelativePath(sourceDocument, "sourceDocument");
     if (!catalog.documents.some((document) => document.relativePath === sourceDocument)) {
@@ -192,10 +207,11 @@ export async function upsertEntity({
   return { entity, graphPath };
 }
 
-export async function linkEntities({ root = process.cwd(), from, to, relation = "related", reason = "", confidence = 0.5, privacy = "private" }) {
+export async function linkEntities({ root = process.cwd(), from, to, relation = "related", reason = "", confidence = 0.5,
+  privacy = "private", catalog: providedCatalog = null }) {
   if (!ENTITY_RELATIONS.has(relation)) throw new Error(`unsupported entity relation: ${relation}`);
   if (!["private", "shared", "group"].includes(privacy)) throw new Error(`unsupported privacy scope: ${privacy}`);
-  const { graph, graphPath } = await loadGraph(root);
+  const { graph, graphPath } = await loadGraph(root, providedCatalog);
   const known = new Set(graph.entities.map((entity) => entity.id));
   if (!known.has(from)) throw new Error(`unknown source entity: ${from}`);
   if (!known.has(to)) throw new Error(`unknown target entity: ${to}`);
@@ -218,9 +234,9 @@ export async function linkEntities({ root = process.cwd(), from, to, relation =
   return { edge, graphPath };
 }
 
-export async function unlinkEntities({ root = process.cwd(), from, to, relation = "related" }) {
+export async function unlinkEntities({ root = process.cwd(), from, to, relation = "related", catalog: providedCatalog = null }) {
   if (!ENTITY_RELATIONS.has(relation)) throw new Error(`unsupported entity relation: ${relation}`);
-  const { graph, graphPath } = await loadGraph(root);
+  const { graph, graphPath } = await loadGraph(root, providedCatalog);
   const previous = graph.entityEdges.find((item) => item.from === from && item.to === to && item.relation === relation);
   if (!previous) return { removed: null, duplicate: true, graphPath };
   preservePrevious(graph, "entity-edge", previous);
@@ -241,9 +257,9 @@ function relationshipAudience(graph, groupId) {
 
 async function assembleRelationshipContext({
   root = process.cwd(), entityId, includePrivate = false, groupId = null, catalog: providedCatalog = null
-}, loadGraphImpl) {
+}, loadGraphImpl, signal) {
   if (!entityId) throw new Error("entityId is required");
-  const { graph } = await loadGraphImpl(root, providedCatalog);
+  const { graph } = await loadGraphImpl(root, providedCatalog, { signal });
   if (groupId !== null) {
     const group = graph.entities.find((item) => item.id === groupId && item.kind === "group");
     if (!group) throw new Error(`unknown group entity: ${groupId}`);
@@ -289,14 +305,33 @@ async function assembleRelationshipContext({
   };
 }
 
-export async function relationshipContext(options = {}, { loadGraphImpl = loadGraph, timeoutMs = 5000 } = {}) {
+export async function relationshipContext(options = {}, { loadGraphImpl = loadRelationshipGraph, timeoutMs = 5000 } = {}) {
+  const controller = new AbortController();
   let timer;
+  const timeoutError = new Error(`relationship context exceeded its ${timeoutMs} ms local read limit`);
   const deadline = new Promise((_resolve, reject) => {
-    timer = setTimeout(() => reject(new Error(`relationship context exceeded its ${timeoutMs} ms local read limit`)), timeoutMs);
+    timer = setTimeout(() => {
+      reject(timeoutError);
+      controller.abort();
+    }, timeoutMs);
   });
   try {
-    return await Promise.race([assembleRelationshipContext(options, loadGraphImpl), deadline]);
+    return await Promise.race([assembleRelationshipContext(options, loadGraphImpl, controller.signal), deadline]);
+  } catch (error) {
+    if (error !== timeoutError) throw error;
+    return {
+      status: "degraded",
+      reason: "local-state-timeout",
+      timeoutMs,
+      entity: null,
+      relatedEntities: [],
+      edges: [],
+      history: [],
+      groupId: options.groupId ?? null,
+      authority: "context-only"
+    };
   } finally {
     clearTimeout(timer);
+    controller.abort();
   }
 }