blun-king-cli 9.1.567 → 9.1.569

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

@@ -0,0 +1,269 @@
+import { runAudit } from "./audit.js";
+import {
+  attentionContext, configureAttention, deleteAttention,
+  recordActivity, resolveAttention, upsertAttention
+} from "./attention.js";
+import { sessionBriefing } from "./briefing.js";
+import { deliveryKnowledgeQuery } from "./delivery-knowledge.js";
+import { advisoryDeliveryUse } from "./hook-briefing-use.js";
+import { recordDeliveryBriefingUse, recordDeliveryKnowledgeUse,
+  verifyDeliveryAgentUse } from "./delivery-agent-usage.js";
+import { scanAndSave, verifyCatalog } from "./catalog.js";
+import { checkDelegation, createTask, taskContext, updateTask } from "./coordination.js";
+import { readDocument, resolveContext } from "./context.js";
+import { recordDeliveryPremortem } from "./delivery-premortem.js";
+import { recoverDeliveryPremortem } from "./delivery-premortem-correction.js";
+import { completeDelivery } from "./mcp-delivery-completion.js";
+import {
+  annotateDocument, linkDocuments, linkEntities,
+  relationshipContext, upsertEntity
+} from "./graph.js";
+import {
+  addLearningEvidence, configureLearning, deleteLearning, evaluateLearning,
+  learningContext, learningOutcomeStatus, proposeLearning, reviewLearning, rollbackLearning
+} from "./learning.js";
+import { sharedContext } from "./sharing.js";
+import { recordWorldAssertion, worldContext } from "./world-model.js";
+import { indexSessionTimeline, searchSessionTimeline } from "./session-timeline.js";
+import { gatewayEnvironmentContext } from "./hook-context.js";
+import {
+  timelineInvocationInput, timelineInvocationRequest
+} from "./mcp-timeline-tools.js";
+import { sessionTimelineBinding } from "./session-timeline-contract.js";
+import { timelineTransportDigest } from "./session-timeline-transport.js";
+import { runtimeHostForTimeline, timelineHostHome } from "./session-timeline-provider.js";
+import { boundBriefingArguments, rejectInternalSourceArguments, resolveMcpSources } from "./mcp-source-context.js";
+import { evaluateAutonomyAction, projectPortfolioContext, recordProjectObservation } from "./autonomy.js";
+
+function textResult(value, isError = false) {
+  return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], isError };
+}
+
+function timelineTransport(input, root, environment) {
+  const { scope } = input;
+  const host = input.request.host || "claude";
+  return { scope, host, transportDigest: timelineTransportDigest({ root,
+    binding: sessionTimelineBinding({ host, sessionId: input.request.sessionId, scope }), environment }) };
+}
+
+function absent(value) { return value === undefined || value === null || value === ""; }
+
+// The MCP process can outlive a host turn.  A group claim that appears after a
+// private permit was issued must therefore suppress consumption here as well
+// as in PreToolUse; tool arguments cannot clear an authenticated environment.
+function runtimeTimelineGroup(environment, input) {
+  try {
+    const gateway = gatewayEnvironmentContext(environment);
+    return Boolean(input?.groupClaim) || !absent(environment?.AGENTSPINE_GROUP_ID) || !absent(gateway?.groupId);
+  } catch {
+    return true;
+  }
+}
+
+function runtimeGatewayMatchesTimeline(environment, scope, host) {
+  let gateway;
+  try { gateway = gatewayEnvironmentContext(environment); }
+  catch { return false; }
+  if (!gateway) return true;
+  if (!absent(gateway.groupId)) return false;
+  const claims = [
+    [gateway.host, runtimeHostForTimeline(host)], [gateway.entityId, scope.entityId], [gateway.projectId, scope.projectId],
+    [gateway.taskId, scope.currentTaskId], [gateway.goalId, scope.goalId], [gateway.goalStepId, scope.goalStepId]
+  ];
+  if (!claims.every(([actual, expected]) => actual === expected)) return false;
+  // Gateway context predates these two claims.  In an authenticated gateway
+  // process, accepting an unverifiable user or tenant would let a stale private
+  // permit cross a newly selected identity, so their canonical env claims are
+  // deliberately mandatory until the gateway context carries them itself.
+  return environment?.AGENTSPINE_USER_ID === scope.userId
+    && environment?.AGENTSPINE_TENANT_ID === scope.tenantId;
+}
+
+function unavailableTimelineInvocation(reason) {
+  return { status: "unavailable", reason, authority: "context-only" };
+}
+
+async function callTool(name, args = {}, environment = process.env) {
+  const root = args.root || process.cwd();
+  if (name === "scan") return textResult(await scanAndSave(root));
+  if (name === "resolve_context") {
+    rejectInternalSourceArguments(args);
+    const sources = await resolveMcpSources({ root, cwd: args.cwd || root, host: args.host });
+    return textResult(await resolveContext({
+      root,
+      cwd: args.cwd || root,
+      host: sources.host,
+      maxBytes: args.maxBytes ?? 65536,
+      includeContent: args.includeContent ?? true,
+      catalog: sources.catalog
+    }));
+  }
+  if (name === "session_briefing") {
+    const scoped = await boundBriefingArguments({ ...args, root });
+    const sources = await resolveMcpSources({ ...scoped, required: Boolean(args.requirementId) });
+    const briefing = await sessionBriefing({ ...scoped, host: sources.host,
+      catalog: sources.catalog, userStateRoot: sources.userStateRoot, sourceDiagnostics: sources.diagnostics });
+    if (!args.requirementId) return textResult(briefing);
+    const receipt = await recordDeliveryBriefingUse({ root,
+      requirementId: args.requirementId, input: args, result: briefing });
+    return textResult({ ...briefing, deliveryUseReceipt: advisoryDeliveryUse(receipt) });
+  }
+  if (name === "delivery_knowledge_query") {
+    rejectInternalSourceArguments(args);
+    const knowledge = await deliveryKnowledgeQuery({ ...args, root });
+    if (knowledge.blocked) return textResult(knowledge, true);
+    const receipt = await recordDeliveryKnowledgeUse({ root,
+      requirementId: args.requirementId, input: args, result: knowledge });
+    return textResult({ ...knowledge, deliveryUseReceipt: advisoryDeliveryUse(receipt) });
+  }
+  if (name === "read_document") {
+    rejectInternalSourceArguments(args);
+    const sources = await resolveMcpSources({ root, host: args.host });
+    return textResult(await readDocument({
+      root, path: args.path, offset: args.offset ?? 0, length: args.length ?? 65536,
+      catalog: sources.catalog
+    }));
+  }
+  if (name === "verify") return textResult(await verifyCatalog(root));
+  if (name === "link_documents") return textResult(await linkDocuments({ ...args, root }));
+  if (name === "annotate_document") return textResult(await annotateDocument({ ...args, root }));
+  if (name === "upsert_entity") return textResult(await upsertEntity({ ...args, root }));
+  if (name === "link_entities") return textResult(await linkEntities({ ...args, root }));
+  if (name === "relationship_context") return textResult(await relationshipContext({ ...args, root }));
+  if (name === "upsert_attention") return textResult(await upsertAttention({ ...args, root }));
+  if (name === "record_activity") return textResult(await recordActivity({ ...args, root }));
+  if (name === "attention_context") return textResult(await attentionContext({ ...args, root }));
+  if (name === "resolve_attention") return textResult(await resolveAttention({ ...args, root }));
+  if (name === "configure_attention") return textResult(await configureAttention({ ...args, root }));
+  if (name === "delete_attention") return textResult(await deleteAttention({ ...args, root }));
+  if (name === "propose_learning") return textResult(await proposeLearning({ ...args, root }));
+  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 }));
+  if (name === "delete_learning") return textResult(await deleteLearning({ ...args, root }));
+  if (name === "check_delegation") return textResult(await checkDelegation({ ...args, root }));
+  if (name === "create_task") return textResult(await createTask({ ...args, root }));
+  if (name === "update_task") return textResult(await updateTask({ ...args, root }));
+  if (name === "task_context") return textResult(await taskContext({ ...args, root }));
+  if (name === "shared_context") return textResult(await sharedContext({ ...args, root }));
+  if (name === "record_world_assertion") return textResult(await recordWorldAssertion({ ...args, root }));
+  if (name === "world_context") return textResult(await worldContext({ ...args, root }));
+  if (name === "project_portfolio") return textResult(await projectPortfolioContext({ ...args, root }));
+  if (name === "record_project_observation") return textResult(await recordProjectObservation({ ...args, root }));
+  if (name === "evaluate_autonomy_action") return textResult(await evaluateAutonomyAction({ ...args, root }));
+  if (name === "session_timeline_index") {
+    const input = timelineInvocationInput(args);
+    if (runtimeTimelineGroup(environment, input)) return textResult(unavailableTimelineInvocation("timeline-group-suppressed"));
+    if (!input.valid) return textResult(unavailableTimelineInvocation(input.reason || "timeline-scope-invalid"));
+    const timeline = timelineTransport(input, root, environment);
+    if (!runtimeGatewayMatchesTimeline(environment, timeline.scope, timeline.host)) {
+      return textResult(unavailableTimelineInvocation("timeline-gateway-binding-mismatch"));
+    }
+    const invocationRequest = timelineInvocationRequest("index", args, root);
+    if (!invocationRequest) return textResult(unavailableTimelineInvocation("timeline-invocation-unavailable"));
+    return textResult(await indexSessionTimeline({ root, host: timeline.host, sessionId: input.request.sessionId, scope: timeline.scope,
+      maxBytes: args.maxBytes, enrollmentDigest: input.request.enrollmentDigest,
+      hostHome: timelineHostHome(timeline.host, environment), transportDigest: timeline.transportDigest, invocationRequest }));
+  }
+  if (name === "session_timeline_search") {
+    const input = timelineInvocationInput(args);
+    if (runtimeTimelineGroup(environment, input)) return textResult(unavailableTimelineInvocation("timeline-group-suppressed"));
+    if (!input.valid) return textResult(unavailableTimelineInvocation(input.reason || "timeline-scope-invalid"));
+    const timeline = timelineTransport(input, root, environment);
+    if (!runtimeGatewayMatchesTimeline(environment, timeline.scope, timeline.host)) {
+      return textResult(unavailableTimelineInvocation("timeline-gateway-binding-mismatch"));
+    }
+    const invocationRequest = timelineInvocationRequest("search", args, root);
+    if (!invocationRequest) return textResult(unavailableTimelineInvocation("timeline-invocation-unavailable"));
+    return textResult(await searchSessionTimeline({ root, host: timeline.host, sessionId: input.request.sessionId, scope: timeline.scope,
+      at: args.at, query: args.query, windowSeconds: args.windowSeconds, includePriorSessions: args.includePriorSessions,
+      enrollmentDigest: input.request.enrollmentDigest,
+      hostHome: timelineHostHome(timeline.host, environment), transportDigest: timeline.transportDigest,
+      invocationRequest }));
+  }
+  if (name === "audit") return textResult(await runAudit(root));
+  if (name === "complete_delivery") {
+    const completed = await completeDelivery(args);
+    return textResult(completed, completed.blocked || completed.status === "degraded");
+  }
+  if (name === "record_delivery_premortem") {
+    if (typeof args.root !== "string" || !args.root) {
+      throw new Error("record_delivery_premortem requires the exact project root");
+    }
+    const usage = await verifyDeliveryAgentUse({ root: args.root,
+      requirementId: args.requirementId });
+    if (usage.status === "mismatch") return textResult(usage, true);
+    if (usage.blocked || usage.status === "degraded") return textResult({ status: "unverified",
+      blocked: false, items: args.items, agentSpineUse: advisoryDeliveryUse(usage),
+      completionVerified: false, automaticRetry: false });
+    const premortem = await recordDeliveryPremortem({
+      root: args.root,
+      requirementId: args.requirementId,
+      items: args.items
+    });
+    return textResult({ ...premortem, agentSpineUse: usage }, premortem.blocked);
+  }
+  if (name === "recover_delivery_premortem") {
+    if (typeof args.root !== "string" || !args.root) {
+      throw new Error("recover_delivery_premortem requires the exact project root");
+    }
+    const recovery = await recoverDeliveryPremortem({ root: args.root,
+      predecessorRequirementId: args.predecessorRequirementId,
+      taskId: args.taskId || null });
+    return textResult(recovery, recovery.blocked);
+  }
+  throw new Error(`Unknown tool: ${name}`);
+}
+
+async function dispatch(message, tools, version, environment) {
+  const { id, method, params = {} } = message;
+  if (method === "initialize") {
+    return {
+      jsonrpc: "2.0", id,
+      result: {
+        protocolVersion: params.protocolVersion || "2025-06-18",
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: "agent-spine", version }
+      }
+    };
+  }
+  if (method === "ping") return { jsonrpc: "2.0", id, result: {} };
+  if (method === "tools/list") return { jsonrpc: "2.0", id, result: { tools } };
+  if (method === "tools/call") {
+    try {
+      return { jsonrpc: "2.0", id, result: await callTool(params.name, params.arguments, environment) };
+    } catch (error) {
+      return { jsonrpc: "2.0", id, result: textResult({ error: error.message }, true) };
+    }
+  }
+  if (method?.startsWith("notifications/")) return null;
+  return { jsonrpc: "2.0", id, error: { code: -32601, message: `Method not found: ${method}` } };
+}
+
+export function startMcpProtocol({ input, output, tools, version, environment = process.env }) {
+  input.setEncoding("utf8");
+  let buffer = "";
+  let queue = Promise.resolve();
+  input.on("data", (chunk) => {
+    buffer += chunk;
+    let newline;
+    while ((newline = buffer.indexOf("\n")) >= 0) {
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      if (!line) continue;
+      queue = queue.then(async () => {
+        let response;
+        try {
+          response = await dispatch(JSON.parse(line), tools, version, environment);
+        } catch (error) {
+          response = { jsonrpc: "2.0", id: null, error: { code: -32700, message: error.message } };
+        }
+        if (response) output.write(`${JSON.stringify(response)}\n`);
+      });
+    }
+  });
+}

package/agent-spine-plugin/src/lib/mcp-source-context.js

@@ -0,0 +1,51 @@
+import { canonicalPath, isInside } from "./paths.js";
+import { resolveHostSourceCatalog } from "./source-roots.js";
+import { inspectPremortemState } from "./delivery-premortem.js";
+
+const INTERNAL = new Set(["catalog", "userStateRoot", "sourceDiagnostics", "sourceRegistry",
+  "env", "input", "memoryHooks", "resolvedSources"]);
+
+export function rejectInternalSourceArguments(args) {
+  for (const key of INTERNAL) {
+    if (Object.hasOwn(args, key)) throw new Error(`unsupported internal source argument: ${key}`);
+  }
+}
+
+export async function boundBriefingArguments(args) {
+  rejectInternalSourceArguments(args);
+  if (!args.requirementId) return args;
+  const current = await inspectPremortemState({ root: args.root, requirementId: args.requirementId });
+  if (current.blocked || current.status === "degraded" || !current.binding) {
+    throw new Error("delivery source binding is unavailable; no briefing receipt issued");
+  }
+  const result = { ...args };
+  for (const [key, field] of [["host", "host"], ["entityId", "entityId"],
+    ["projectId", "projectId"], ["groupId", "groupId"], ["currentTaskId", "taskId"]]) {
+    const expected = current.binding[field];
+    if (Object.hasOwn(args, key) && args[key] !== expected) {
+      throw new Error(`delivery source ${key} does not match its requirement`);
+    }
+    result[key] = expected;
+  }
+  return result;
+}
+
+export async function resolveMcpSources({ root, cwd = root,
+  host = process.env.AGENTSPINE_HOST || "generic", entityId = null,
+  groupId = null, projectId = null, currentTaskId = null, required = false }) {
+  const canonicalRoot = await canonicalPath(root);
+  const canonicalCwd = await canonicalPath(cwd);
+  if (!isInside(canonicalRoot, canonicalCwd)) throw new Error("MCP cwd must remain inside its root");
+  // Only the process environment and the locally read registry select sources.
+  // No MCP-provided catalog, registry, profile, or state location enters here.
+  const sources = await resolveHostSourceCatalog({ host, cwd: canonicalCwd,
+    input: { agent_spine_scope: { entity_id: entityId, group_id: groupId,
+      project_id: projectId, task_id: currentTaskId } } });
+  if (sources.projectRoot !== canonicalRoot) {
+    throw new Error("MCP root differs from the resolved host project root");
+  }
+  if (required && (sources.diagnostics.incomplete || sources.diagnostics.skipped.length)) {
+    throw new Error("MCP source discovery is incomplete; no delivery receipt issued");
+  }
+  return sources;
+}

package/agent-spine-plugin/src/lib/mcp-timeline-tools.js

@@ -0,0 +1,164 @@
+import { TIMELINE_HOSTS } from "./session-timeline-provider.js";
+
+const stableId = {
+  type: "string",
+  pattern: "^[A-Za-z0-9][A-Za-z0-9:_.@/-]{0,127}$"
+};
+
+const optionalId = { anyOf: [stableId, { type: "null" }] };
+
+// Hosts qualify MCP tools differently. These prefixes must stay exact: a
+// foreign MCP server can expose an identically named tool but must never
+// receive a timeline invocation permit.
+export const AGENTSPINE_TIMELINE_TOOL_PREFIX = "mcp__plugin_agent-spine_agent-spine__";
+export const BLUN_TIMELINE_TOOL_PREFIX = "mcp__agent-spine__";
+export const KING_PLUGIN_TIMELINE_TOOL_PREFIX = "mcp__plugin-agent-spine_agent-spine__";
+
+const TIMELINE_TOOL_PREFIXES = [
+  AGENTSPINE_TIMELINE_TOOL_PREFIX,
+  BLUN_TIMELINE_TOOL_PREFIX,
+  KING_PLUGIN_TIMELINE_TOOL_PREFIX
+];
+
+const SCOPE_FIELDS = [
+  ["entityId", ["entityId", "entity_id"]],
+  ["userId", ["userId", "user_id"]],
+  ["tenantId", ["tenantId", "tenant_id"]],
+  ["projectId", ["projectId", "project_id"]],
+  ["groupId", ["groupId", "group_id"]],
+  ["currentTaskId", ["taskId", "task_id", "currentTaskId", "current_task_id"]],
+  ["goalId", ["goalId", "goal_id"]],
+  ["goalStepId", ["goalStepId", "goal_step_id"]],
+  ["timelineVisibility", ["timelineVisibility", "timeline_visibility"]]
+];
+
+const REQUEST_FIELDS = [
+  ["host", ["host"]],
+  ["sessionId", ["sessionId", "session_id"]],
+  ["enrollmentDigest", ["enrollmentDigest", "enrollment_digest"]]
+];
+
+function owns(value, key) {
+  return Boolean(value) && Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function plainObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value)
+    && Object.getPrototypeOf(value) === Object.prototype;
+}
+
+function absent(value) { return value === undefined || value === null || value === ""; }
+
+function containers(args) {
+  if (!plainObject(args)) return { valid: false, reason: "timeline-scope-invalid", values: [] };
+  if (!owns(args, "agent_spine_scope") || args.agent_spine_scope === null) {
+    return { valid: true, reason: null, values: [args] };
+  }
+  if (!plainObject(args.agent_spine_scope)) {
+    return { valid: false, reason: "timeline-scope-invalid", values: [args] };
+  }
+  return { valid: true, reason: null, values: [args, args.agent_spine_scope] };
+}
+
+function claim(values, aliases) {
+  const supplied = values.flatMap((value) => aliases.filter((key) => owns(value, key)).map((key) => value[key]));
+  const present = supplied.filter((value) => !absent(value));
+  if (!present.length) return { valid: true, value: null, present: false };
+  if (present.some((value) => typeof value !== "string") || !present.every((value) => value === present[0])) {
+    return { valid: false, value: null, present: true };
+  }
+  return { valid: true, value: present[0], present: true };
+}
+
+function validId(value) {
+  return value === null || (typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9:_.@/-]{0,127}$/.test(value));
+}
+
+function resolvedClaims(args) {
+  const nested = containers(args);
+  const values = nested.values;
+  const result = { valid: nested.valid, reason: nested.reason, groupClaim: false, scope: {}, request: {} };
+  for (const [field, aliases] of [...SCOPE_FIELDS, ...REQUEST_FIELDS]) {
+    const resolved = claim(values, aliases);
+    if (field === "groupId") result.groupClaim = resolved.present;
+    if (!resolved.valid || (field === "host" && resolved.value !== null && !TIMELINE_HOSTS.includes(resolved.value))
+      || (field !== "timelineVisibility" && !validId(resolved.value))
+      || (field === "timelineVisibility" && resolved.value !== null && resolved.value !== "private-verified")
+      || (field === "enrollmentDigest" && resolved.value !== null && !/^[a-f0-9]{64}$/.test(resolved.value))) {
+      result.valid = false;
+      result.reason ||= "timeline-scope-conflict";
+    }
+    if (SCOPE_FIELDS.some(([name]) => name === field)) result.scope[field] = resolved.value;
+    else result.request[field] = resolved.value;
+  }
+  return result;
+}
+
+// Direct stdio callers can bypass the MCP schema. Merge the flat and nested
+// representations only when every present claim agrees. In particular, a
+// nested group claim stays visible when a top-level argument tries to clear
+// it with null, so no existing private permit crosses into a group turn.
+export function timelineInvocationInput(args = {}) {
+  return resolvedClaims(args);
+}
+
+export function timelineScope(args = {}) {
+  return resolvedClaims(args).scope;
+}
+
+export function timelineToolKind(name) {
+  const qualified = String(name || "");
+  if (TIMELINE_TOOL_PREFIXES.some((prefix) => qualified === `${prefix}session_timeline_index`)) return "index";
+  if (TIMELINE_TOOL_PREFIXES.some((prefix) => qualified === `${prefix}session_timeline_search`)) return "search";
+  return null;
+}
+
+export function timelineInvocationRequest(tool, args, root) {
+  const input = resolvedClaims(args);
+  if (!input.valid || input.groupClaim || !input.request.sessionId) return null;
+  const scope = input.scope;
+  const request = { root, tool, sessionId: input.request.sessionId, entityId: scope.entityId, userId: scope.userId,
+    tenantId: scope.tenantId, projectId: scope.projectId, groupId: scope.groupId, taskId: scope.currentTaskId,
+    goalId: scope.goalId, goalStepId: scope.goalStepId, timelineVisibility: scope.timelineVisibility,
+    enrollmentDigest: input.request.enrollmentDigest };
+  if (tool === "index") return { ...request, maxBytes: args.maxBytes ?? 4 * 1024 * 1024 };
+  return { ...request, at: args.at ?? null, query: args.query ?? null,
+    windowSeconds: args.windowSeconds === undefined ? 0 : args.windowSeconds,
+    includePriorSessions: args.includePriorSessions === true };
+}
+
+const scopeProperties = {
+  host: { enum: TIMELINE_HOSTS },
+  entityId: stableId, userId: stableId, tenantId: stableId, projectId: stableId,
+  taskId: stableId, goalId: optionalId, goalStepId: optionalId
+};
+
+export const sessionTimelineTools = [
+  {
+    name: "session_timeline_index",
+    description: "Index bounded evidence from one explicitly enrolled immutable provider transcript snapshot. Claude, Codex and King use separate format adapters; changed sources require a renewed host receipt and this tool never copies a transcript or grants authority.",
+    inputSchema: {
+      type: "object", additionalProperties: false,
+      required: [],
+      properties: { root: { type: "string", minLength: 1 }, sessionId: stableId, ...scopeProperties,
+        enrollmentDigest: { type: "string", pattern: "^[a-f0-9]{64}$" },
+        timelineVisibility: { const: "private-verified" }, groupId: { anyOf: [stableId, { type: "null" }] },
+        maxBytes: { type: "integer", minimum: 65536, maximum: 16777216 } }
+    }
+  },
+  {
+    name: "session_timeline_search",
+    description: "Search the current or a same-task prior explicitly enrolled immutable Claude, Codex or King source for redacted objective evidence by exact UTC time or at least two concrete terms. Prior-session search opens only one indexed source and never grants authority.",
+    inputSchema: {
+      type: "object", additionalProperties: false,
+      required: [],
+      anyOf: [{ required: ["at"] }, { required: ["query"] }],
+      properties: { root: { type: "string", minLength: 1 }, sessionId: stableId, ...scopeProperties,
+        enrollmentDigest: { type: "string", pattern: "^[a-f0-9]{64}$" },
+        timelineVisibility: { const: "private-verified" }, groupId: { anyOf: [stableId, { type: "null" }] },
+        at: { type: "string", format: "date-time" }, query: { type: "string", minLength: 3, maxLength: 512 },
+        windowSeconds: { type: "integer", minimum: 0, maximum: 900 },
+        includePriorSessions: { type: "boolean" } }
+    }
+  }
+];

package/agent-spine-plugin/src/lib/mcp-world-tools.js

@@ -0,0 +1,52 @@
+const stableId = {
+  type: "string",
+  pattern: "^[a-z][a-z0-9-]{0,31}:[A-Za-z0-9][A-Za-z0-9._/-]{0,190}$"
+};
+
+const nullableStableId = { anyOf: [stableId, { type: "null" }] };
+
+export const worldModelTools = [
+  {
+    name: "record_world_assertion",
+    description: "Persist one provenance-bound world, user, relationship, or team assertion outside source files. Optional typed knowledge distinguishes facts, user preferences, decisions, task state, and error lessons. Measurements and explicit user feedback become context-only facts; model output remains a proposal. Authority predicates and secret-shaped structured knowledge are rejected.",
+    inputSchema: {
+      type: "object", additionalProperties: false,
+      required: ["id", "subjectId", "predicate", "value", "evidenceKind", "evidenceId", "evidenceDigest", "observedAt"],
+      properties: {
+        root: { type: "string" }, id: stableId, subjectId: stableId,
+        predicate: { type: "string", pattern: "^[a-z][a-z0-9.-]{0,127}$" },
+        value: {},
+        evidenceKind: { type: "string", enum: ["objective-measurement", "explicit-user-feedback", "model-suggestion"] },
+        evidenceId: stableId,
+        evidenceDigest: { type: "string", pattern: "^[a-f0-9]{64}$" },
+        knowledgeKind: {
+          type: "string",
+          enum: ["fact", "user-preference", "decision", "task-state", "error-lesson"]
+        },
+        sessionRef: { type: "string", pattern: "^session-ref:[a-f0-9]{32}$" },
+        messageRef: stableId,
+        observedAt: { type: "string", format: "date-time" },
+        expiresAt: { anyOf: [{ type: "string", format: "date-time" }, { type: "null" }] },
+        projectId: nullableStableId, groupId: nullableStableId,
+        privacy: { type: "string", enum: ["private", "shared", "group"] },
+        supersedes: { type: "array", maxItems: 50, uniqueItems: true, items: stableId },
+        reason: { type: "string", maxLength: 500 }
+      }
+    }
+  },
+  {
+    name: "world_context",
+    description: "Read privacy-filtered world context. Conflicts, expiry, and suggestions remain separate; continuationTaskId adds bounded, sourced task-relevant knowledge.",
+    inputSchema: {
+      type: "object", additionalProperties: false,
+      properties: {
+        root: { type: "string" }, subjectId: nullableStableId,
+        projectId: nullableStableId, groupId: nullableStableId,
+        includePrivate: { type: "boolean" }, includeKnowledgeHistory: { type: "boolean" },
+        continuationTaskId: nullableStableId,
+        maxItems: { type: "integer", minimum: 1, maximum: 500 },
+        now: { type: "string", format: "date-time" }
+      }
+    }
+  }
+];

package/agent-spine-plugin/src/lib/owned-file-lock.js

@@ -35,9 +35,10 @@ function sameFile(left, right) {
     && left.mtimeMs === right.mtimeMs && left.ctimeMs === right.ctimeMs;
 }
 
-async function removeStaleLock(path, staleAfterMs) {
+async function removeStaleLock(path, staleAfterMs, assertPath = null) {
   let before;
   try {
+    await assertPath?.();
     before = await stat(path);
   } catch (error) {
     if (isTransientLockMetadataError(error)) return false;
@@ -47,6 +48,7 @@ async function removeStaleLock(path, staleAfterMs) {
   await readOwner(path);
   let after;
   try {
+    await assertPath?.();
     after = await stat(path);
   } catch (error) {
     if (isTransientLockMetadataError(error)) return false;
@@ -54,7 +56,9 @@ async function removeStaleLock(path, staleAfterMs) {
   }
   if (!sameFile(before, after) || Date.now() - after.mtimeMs <= staleAfterMs) return false;
   try {
+    await assertPath?.();
     await unlink(path);
+    await assertPath?.();
     return true;
   } catch (error) {
     if (isFileLockContention(error) || isTransientLockMetadataError(error)) return false;
@@ -66,7 +70,8 @@ export async function withOwnedFileLock(path, task, {
   staleAfterMs = 15000,
   heartbeatIntervalMs = 1000,
   retryDelayMs = 25,
-  maxAttempts = 80
+  maxAttempts = 80,
+  assertPath = null
 } = {}) {
   if (typeof task !== "function") throw new Error("owned file lock requires a task");
   if (!Number.isInteger(staleAfterMs) || staleAfterMs < 50
@@ -78,13 +83,16 @@ export async function withOwnedFileLock(path, task, {
   }
   const token = randomUUID();
   const acquiredAt = new Date().toISOString();
-  let acquired = false;
+  let acquired = false; let recovered = false;
   for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
-    let handle;
+    let handle; let created = false;
     try {
+      await assertPath?.();
       handle = await open(path, "wx", 0o600);
+      created = true;
       const payload = `${JSON.stringify(lockPayload(token, acquiredAt, staleAfterMs))}\n`;
       await handle.writeFile(payload, "utf8");
+      await assertPath?.();
       acquired = true;
       break;
     } catch (error) {
@@ -92,13 +100,16 @@ export async function withOwnedFileLock(path, task, {
         if (handle) {
           await handle.close();
           handle = null;
-          await unlink(path).catch((cleanupError) => {
+          try {
+            await assertPath?.();
+            if (created) await unlink(path);
+          } catch (cleanupError) {
             if (cleanupError.code !== "ENOENT") error.cleanupError = cleanupError;
-          });
+          }
         }
         throw error;
       }
-      await removeStaleLock(path, staleAfterMs);
+      recovered ||= await removeStaleLock(path, staleAfterMs, assertPath);
       if (attempt + 1 < maxAttempts) await delay(retryDelayMs);
     } finally {
       await handle?.close();
@@ -110,7 +121,9 @@ export async function withOwnedFileLock(path, task, {
   let heartbeat = Promise.resolve();
   const assertOwned = async () => {
     if (ownershipError) throw ownershipError;
+    await assertPath?.();
     const owner = await readOwner(path);
+    await assertPath?.();
     if (!owner || owner.token !== token) {
       ownershipError = new Error("state lock ownership was lost; mutation aborted");
       throw ownershipError;
@@ -120,6 +133,7 @@ export async function withOwnedFileLock(path, task, {
     await assertOwned();
     const now = new Date();
     await utimes(path, now, now);
+    await assertPath?.();
   };
   const timer = setInterval(() => {
     heartbeat = heartbeat.then(renew).catch((error) => { ownershipError ||= error; });
@@ -127,15 +141,21 @@ export async function withOwnedFileLock(path, task, {
   timer.unref?.();
 
   try {
-    const result = await task({ token, acquiredAt, assertOwned });
+    const result = await task({ token, acquiredAt, recovered, assertOwned });
     await assertOwned();
     return result;
   } finally {
     clearInterval(timer);
     await heartbeat;
-    const owner = await readOwner(path).catch(() => null);
+    const owner = await (async () => {
+      await assertPath?.();
+      return readOwner(path);
+    })().catch(() => null);
     if (owner?.token === token) {
-      await unlink(path).catch((error) => {
+      await (async () => {
+        await assertPath?.();
+        await unlink(path);
+      })().catch((error) => {
         if (error.code !== "ENOENT") throw error;
       });
     }