chainlesschain 0.165.6 → 0.165.9

package/src/lib/session-message-fabric.js

@@ -12,7 +12,12 @@
 import fs from "node:fs";
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
-import { ensureDir, getHomeDir } from "./paths.js";
+import { ensureDir } from "./paths.js";
+import {
+  ensureTrustedSessionLifecycleScope,
+  resolveTrustedSessionLifecycleScope,
+  sessionLifecycleFabricDirectory,
+} from "./session-lifecycle-scope.js";
 import { withFileLock } from "./with-file-lock.js";
 
 export const SESSION_MESSAGE_FABRIC_SCHEMA =
@@ -31,6 +36,7 @@ export const SESSION_MESSAGE_RECEIPT_STATUSES = Object.freeze([
   "held",
   "refused",
   "full",
+  "rate_limited",
   "expired",
 ]);
 
@@ -38,6 +44,8 @@ export const SESSION_MESSAGE_FABRIC_LIMITS = Object.freeze({
   maxMessageBytes: 256 * 1024,
   maxPendingPerRecipient: 100,
   maxReceiptHistory: 5_000,
+  maxMessagesPerSenderWindow: 120,
+  senderRateWindowMs: 60_000,
   defaultTtlMs: 24 * 60 * 60 * 1000,
   maxTtlMs: 7 * 24 * 60 * 60 * 1000,
 });
@@ -153,6 +161,9 @@ function emptyState(now) {
     channels: [],
     messages: [],
     receipts: [],
+    // Per-sender fixed windows are durable so a new CLI process cannot evade
+    // the same-host admission limit by reopening the fabric state file.
+    rateBuckets: [],
   };
   return { ...state, digest: digestValue(state) };
 }
@@ -326,6 +337,41 @@ function updateReceipt(state, message, status, reason, now) {
   return receipt;
 }
 
+function pruneRateBuckets(state, now, windowMs) {
+  if (!Array.isArray(state.rateBuckets) || state.rateBuckets.length === 0) {
+    return false;
+  }
+  const before = state.rateBuckets.length;
+  state.rateBuckets = state.rateBuckets.filter(
+    (bucket) => now < bucket.windowStartedAt + windowMs,
+  );
+  return state.rateBuckets.length !== before;
+}
+
+function consumeSenderRate(state, senderAuthority, now, limit, windowMs) {
+  state.rateBuckets ??= [];
+  let bucket = state.rateBuckets.find(
+    (entry) => entry.senderAuthority === senderAuthority,
+  );
+  if (!bucket || now >= bucket.windowStartedAt + windowMs) {
+    if (!bucket) {
+      bucket = { senderAuthority, windowStartedAt: now, count: 0 };
+      state.rateBuckets.push(bucket);
+    } else {
+      bucket.windowStartedAt = now;
+      bucket.count = 0;
+    }
+  }
+  if (bucket.count >= limit) {
+    return {
+      allowed: false,
+      retryAfterMs: Math.max(1, bucket.windowStartedAt + windowMs - now),
+    };
+  }
+  bucket.count += 1;
+  return { allowed: true, retryAfterMs: 0 };
+}
+
 function trimReceiptHistory(state, limit) {
   if (state.receipts.length <= limit) return false;
   const protectedIds = new Set(
@@ -368,12 +414,18 @@ function compactSettledMessages(state) {
 }
 
 function applyExpectedMessage(state, channel, message, recipient, now) {
-  if (recipient.policy === "hold") {
-    updateReceipt(state, message, "held", "policy_hold", now);
-    return false;
-  }
   if (recipient.policy === "refuse") {
     updateReceipt(state, message, "refused", "policy_refuse", now);
+  } else if (recipient.policy === "hold") {
+    updateReceipt(state, message, "held", "policy_hold", now);
+    return false;
+  } else if (recipient.online !== true) {
+    // Durable admission is not delivery.  In particular, an offline target
+    // must never produce a success-looking `delivered` receipt merely because
+    // this host appended the payload to its local queue.  Reconnect promotes
+    // the exact retained sequence through the same policy gate.
+    updateReceipt(state, message, "held", "recipient_offline", now);
+    return false;
   } else {
     const receipt = updateReceipt(state, message, "delivered", null, now);
     message.deliveredAt = now;
@@ -455,6 +507,7 @@ function validateState(state) {
     !Array.isArray(state.channels) ||
     !Array.isArray(state.messages) ||
     !Array.isArray(state.receipts) ||
+    (state.rateBuckets != null && !Array.isArray(state.rateBuckets)) ||
     typeof state.digest !== "string"
   ) {
     fail("invalid envelope");
@@ -520,29 +573,56 @@ function validateState(state) {
       fail("invalid receipt");
     }
   }
+  const bucketAuthorities = new Set();
+  for (const bucket of state.rateBuckets || []) {
+    if (
+      typeof bucket?.senderAuthority !== "string" ||
+      bucketAuthorities.has(bucket.senderAuthority) ||
+      !Number.isSafeInteger(bucket.windowStartedAt) ||
+      bucket.windowStartedAt < 0 ||
+      !Number.isSafeInteger(bucket.count) ||
+      bucket.count < 1
+    ) {
+      fail("invalid rate bucket");
+    }
+    bucketAuthorities.add(bucket.senderAuthority);
+  }
   return state;
 }
 
-export function defaultSessionMessageFabricPath() {
-  return path.join(getHomeDir(), "session-message-fabric", "state.json");
+export function defaultSessionMessageFabricPath(options = {}) {
+  return resolveTrustedSessionLifecycleScope(options).messageFabricStatePath;
 }
 
 export class SessionMessageFabric {
-  constructor({
-    statePath = defaultSessionMessageFabricPath(),
-    now = () => Date.now(),
-    createId = randomUUID,
-    lock = withFileLock,
-    lockTimeoutMs = 10_000,
-    maxMessageBytes = SESSION_MESSAGE_FABRIC_LIMITS.maxMessageBytes,
-    maxPendingPerRecipient = SESSION_MESSAGE_FABRIC_LIMITS.maxPendingPerRecipient,
-    maxReceiptHistory = SESSION_MESSAGE_FABRIC_LIMITS.maxReceiptHistory,
-    defaultTtlMs = SESSION_MESSAGE_FABRIC_LIMITS.defaultTtlMs,
-    maxTtlMs = SESSION_MESSAGE_FABRIC_LIMITS.maxTtlMs,
-  } = {}) {
+  constructor(options = {}) {
+    const {
+      statePath: configuredStatePath,
+      launchEnv,
+      cwd,
+      now = () => Date.now(),
+      createId = randomUUID,
+      lock = withFileLock,
+      lockTimeoutMs = 10_000,
+      maxMessageBytes = SESSION_MESSAGE_FABRIC_LIMITS.maxMessageBytes,
+      maxPendingPerRecipient = SESSION_MESSAGE_FABRIC_LIMITS.maxPendingPerRecipient,
+      maxReceiptHistory = SESSION_MESSAGE_FABRIC_LIMITS.maxReceiptHistory,
+      maxMessagesPerSenderWindow = SESSION_MESSAGE_FABRIC_LIMITS.maxMessagesPerSenderWindow,
+      senderRateWindowMs = SESSION_MESSAGE_FABRIC_LIMITS.senderRateWindowMs,
+      defaultTtlMs = SESSION_MESSAGE_FABRIC_LIMITS.defaultTtlMs,
+      maxTtlMs = SESSION_MESSAGE_FABRIC_LIMITS.maxTtlMs,
+    } = options;
+    const usesDefaultStatePath = configuredStatePath === undefined;
+    const lifecycleScope = usesDefaultStatePath
+      ? resolveTrustedSessionLifecycleScope({ launchEnv, cwd })
+      : null;
+    const statePath = usesDefaultStatePath
+      ? lifecycleScope.messageFabricStatePath
+      : configuredStatePath;
     this.statePath = path.resolve(statePath);
+    this._lifecycleScope = lifecycleScope;
     this._secureDefaultDirectory =
-      this.statePath === path.resolve(defaultSessionMessageFabricPath());
+      usesDefaultStatePath && lifecycleScope.kind === "legacy";
     this._now = now;
     this._createId = createId;
     this._lock = lock;
@@ -560,6 +640,14 @@ export class SessionMessageFabric {
         maxReceiptHistory,
         SESSION_MESSAGE_FABRIC_LIMITS.maxReceiptHistory,
       ),
+      maxMessagesPerSenderWindow: positiveInteger(
+        maxMessagesPerSenderWindow,
+        SESSION_MESSAGE_FABRIC_LIMITS.maxMessagesPerSenderWindow,
+      ),
+      senderRateWindowMs: positiveInteger(
+        senderRateWindowMs,
+        SESSION_MESSAGE_FABRIC_LIMITS.senderRateWindowMs,
+      ),
       defaultTtlMs: positiveInteger(
         defaultTtlMs,
         SESSION_MESSAGE_FABRIC_LIMITS.defaultTtlMs,
@@ -573,6 +661,14 @@ export class SessionMessageFabric {
 
   _ensureDirectory() {
     const directory = path.dirname(this.statePath);
+    if (this._lifecycleScope?.kind === "project") {
+      ensureTrustedSessionLifecycleScope(this._lifecycleScope, {
+        extraDirectories: [
+          sessionLifecycleFabricDirectory(this._lifecycleScope),
+        ],
+      });
+      return;
+    }
     if (this._secureDefaultDirectory) {
       ensureDir(directory);
       return;
@@ -667,13 +763,24 @@ export class SessionMessageFabric {
           }
           const now = this._now();
           const swept = sweepExpired(state, now);
+          const prunedRateBuckets = pruneRateBuckets(
+            state,
+            now,
+            this._limits.senderRateWindowMs,
+          );
           const outcome = mutator(state, now) || { value: undefined };
           const compacted = compactSettledMessages(state);
           const trimmed = trimReceiptHistory(
             state,
             this._limits.maxReceiptHistory,
           );
-          if (swept || compacted || trimmed || outcome.changed === true) {
+          if (
+            swept ||
+            prunedRateBuckets ||
+            compacted ||
+            trimmed ||
+            outcome.changed === true
+          ) {
             state.revision += 1;
             state.updatedAt = now;
             state.digest = digestValue(stateWithoutDigest(state));
@@ -757,6 +864,13 @@ export class SessionMessageFabric {
         };
         state.endpoints.push(endpoint);
       }
+      for (const channel of state.channels.filter(
+        (entry) =>
+          entry.recipientAuthority === endpoint.authorityId &&
+          entry.recipientEpoch === endpoint.epoch,
+      )) {
+        promoteChannel(state, channel, now);
+      }
       return {
         changed: true,
         value: { ...clone(endpoint), address: endpointAddress(endpoint) },
@@ -783,6 +897,13 @@ export class SessionMessageFabric {
       const endpoint = requireEndpoint(state, selector);
       endpoint.online = true;
       endpoint.updatedAt = now;
+      for (const channel of state.channels.filter(
+        (entry) =>
+          entry.recipientAuthority === endpoint.authorityId &&
+          entry.recipientEpoch === endpoint.epoch,
+      )) {
+        promoteChannel(state, channel, now);
+      }
       return {
         changed: true,
         value: { ...clone(endpoint), address: endpointAddress(endpoint) },
@@ -913,6 +1034,32 @@ export class SessionMessageFabric {
         }
         return { value: clone(duplicate) };
       }
+      const rate = consumeSenderRate(
+        state,
+        sender.authorityId,
+        now,
+        this._limits.maxMessagesPerSenderWindow,
+        this._limits.senderRateWindowMs,
+      );
+      if (!rate.allowed) {
+        const receipt = {
+          messageId: id,
+          senderAuthority: sender.authorityId,
+          recipientAuthority: recipient?.authorityId || null,
+          recipientEpoch: recipient?.epoch || null,
+          sequence: requestedSequence,
+          payloadDigest,
+          status: "rate_limited",
+          reason: "sender_rate_limit",
+          retryAfterMs: rate.retryAfterMs,
+          createdAt: now,
+          updatedAt: now,
+          idleNotifiedAt: null,
+          readAt: null,
+        };
+        state.receipts.push(receipt);
+        return { changed: true, value: clone(receipt) };
+      }
       if (!recipient) {
         const receipt = {
           messageId: id,

package/src/lib/session-projection.js

@@ -84,6 +84,29 @@ function asText(value) {
   return typeof value === "string" && value.trim() ? value.trim() : null;
 }
 
+function boundedText(value, maxChars = 240) {
+  let text = null;
+  if (typeof value === "string") text = value;
+  else if (value && typeof value === "object") {
+    text =
+      value.summary ||
+      value.title ||
+      value.question ||
+      value.text ||
+      value.answer ||
+      null;
+  }
+  if (typeof text !== "string") return null;
+  const normalized = text
+    .replace(/[\u0000-\u001f\u007f]+/gu, " ")
+    .replace(/\s+/gu, " ")
+    .trim();
+  if (!normalized) return null;
+  return normalized.length <= maxChars
+    ? normalized
+    : `${normalized.slice(0, Math.max(0, maxChars - 1))}…`;
+}
+
 function asCount(value) {
   const number = Number(value);
   return Number.isFinite(number) && number > 0 ? Math.floor(number) : 0;
@@ -646,6 +669,178 @@ function messagingSummary(sessionIds, fabric) {
   };
 }
 
+function pendingInteractionCount(source) {
+  if (Array.isArray(source?.pendingInteractions)) {
+    return Math.min(1_000, source.pendingInteractions.length);
+  }
+  return Math.min(1_000, asCount(source?.pendingInteractions));
+}
+
+function liveToolSummary(source) {
+  const candidate =
+    source?.liveTool || source?.currentTool || source?.recent?.call || null;
+  const name = boundedText(candidate?.name || candidate?.tool || candidate, 96);
+  if (!name) return null;
+  return {
+    name,
+    status: boundedText(candidate?.status || source?.toolStatus, 48),
+  };
+}
+
+function focusSummary(source, state) {
+  const pendingQuestion = boundedText(source?.pendingQuestion, 240);
+  const todos = Array.isArray(source?.todos) ? source.todos : [];
+  const latestTodo = boundedText(
+    source?.latestTodo || source?.todo?.latest || todos.at(-1),
+    240,
+  );
+  const settledAnswer = boundedText(
+    source?.settledAnswer || source?.lastAnswer || source?.answerSummary,
+    240,
+  );
+  const liveTool = liveToolSummary(source);
+  return {
+    active: ["working", "needs_input", "blocked"].includes(state),
+    liveTool,
+    latestTodo,
+    pendingQuestion,
+    settledAnswer,
+  };
+}
+
+function locationSummary(source, kind) {
+  const hint = String(
+    source?.executionLocation?.kind ||
+      source?.executionLocation ||
+      source?.location?.kind ||
+      source?.location ||
+      source?.origin ||
+      "",
+  )
+    .trim()
+    .toLowerCase();
+  const locationKind =
+    source?.cloud === true || hint === "cloud"
+      ? "cloud"
+      : kind === "remote"
+        ? "remote"
+        : "local";
+  const connection = String(source?.connection || source?.connectivity || "")
+    .trim()
+    .toLowerCase();
+  const offline =
+    source?.offline === true ||
+    source?.online === false ||
+    ["offline", "disconnected", "unreachable"].includes(connection) ||
+    (kind === "remote" && source?.alive !== true);
+  const online =
+    !offline &&
+    (source?.online === true ||
+      ["online", "connected"].includes(connection) ||
+      (kind === "remote" && source?.alive === true) ||
+      locationKind === "cloud");
+  return {
+    kind: locationKind,
+    status: offline ? "offline" : online ? "online" : "local",
+  };
+}
+
+function groupingSummary(workbench, error) {
+  if (error) {
+    return {
+      authority: "cli",
+      connected: false,
+      revision: null,
+      generation: 0,
+      reason: String(error).slice(0, 240),
+      items: [],
+      assignments: [],
+    };
+  }
+  if (workbench == null) {
+    const items = [];
+    const assignments = [];
+    return {
+      authority: "cli",
+      connected: true,
+      revision: projectionRevision({
+        schema: "chainlesschain.session-workbench-state/v1",
+        generation: 0,
+        groups: [],
+        memberships: {},
+      }),
+      generation: 0,
+      items,
+      assignments,
+    };
+  }
+  if (
+    typeof workbench !== "object" ||
+    workbench.authority !== "cli" ||
+    workbench.connected !== true ||
+    typeof workbench.revision !== "string" ||
+    !Number.isSafeInteger(workbench.generation) ||
+    workbench.generation < 0 ||
+    !Array.isArray(workbench.items) ||
+    workbench.items.length > 128 ||
+    !Array.isArray(workbench.assignments) ||
+    workbench.assignments.length > 4096
+  ) {
+    return groupingSummary(null, "session group projection is malformed");
+  }
+  const ids = new Set();
+  const items = [];
+  for (const raw of workbench.items) {
+    const id = asText(raw?.id);
+    const name = boundedText(raw?.name, 80);
+    const order = Number(raw?.order);
+    if (
+      !id ||
+      !/^group-[a-zA-Z0-9_-]+$/u.test(id) ||
+      !name ||
+      !Number.isSafeInteger(order) ||
+      order < 0 ||
+      ids.has(id)
+    ) {
+      return groupingSummary(null, "session group projection is malformed");
+    }
+    ids.add(id);
+    items.push({ id, name, order });
+  }
+  items.sort(
+    (left, right) =>
+      left.order - right.order || left.name.localeCompare(right.name),
+  );
+  const assignments = [];
+  const seenSessions = new Set();
+  for (const raw of workbench.assignments) {
+    const sessionId = asText(raw?.sessionId);
+    const groupId = asText(raw?.groupId);
+    if (
+      !sessionId ||
+      sessionId.length > 512 ||
+      !groupId ||
+      !ids.has(groupId) ||
+      seenSessions.has(sessionId)
+    ) {
+      return groupingSummary(null, "session group projection is malformed");
+    }
+    seenSessions.add(sessionId);
+    assignments.push({ sessionId, groupId });
+  }
+  assignments.sort((left, right) =>
+    left.sessionId.localeCompare(right.sessionId),
+  );
+  return {
+    authority: "cli",
+    connected: true,
+    revision: workbench.revision,
+    generation: workbench.generation,
+    items,
+    assignments,
+  };
+}
+
 function lastEventFor(source, state) {
   const at =
     toIso(source?.lastEvent?.at) ||
@@ -663,7 +858,7 @@ function lastEventFor(source, state) {
 function projectOne(
   kind,
   source,
-  { artifacts, prLinks, sessionMessageFabric },
+  { artifacts, prLinks, sessionMessageFabric, groupAssignments },
 ) {
   let sourceId;
   if (kind === "remote") {
@@ -707,6 +902,11 @@ function projectOne(
     sourceId,
     linkedSessionId,
   );
+  const approval = approvalSummary(source, state);
+  const messaging = messagingSummary(linkedSessionIds, sessionMessageFabric);
+  const focus = focusSummary(source, state);
+  const groupId =
+    groupAssignments.get(canonicalSessionId(kind, sourceId)) || null;
   const projected = {
     id: canonicalSessionId(kind, sourceId),
     sourceId,
@@ -735,8 +935,19 @@ function projectOne(
       kind === "dynamic_workflow"
         ? { count: asCount(source?.artifacts?.count), latest: null }
         : artifactSummary(linkedSessionIds, artifacts),
-    approval: approvalSummary(source, state),
-    messaging: messagingSummary(linkedSessionIds, sessionMessageFabric),
+    approval,
+    messaging,
+    groupId,
+    attention: {
+      unread: messaging.unread,
+      needsApproval: approval.pending,
+      pendingInteractions: Math.min(
+        1_000,
+        pendingInteractionCount(source) + (focus.pendingQuestion ? 1 : 0),
+      ),
+    },
+    focus,
+    location: locationSummary(source, kind),
     pr: prSummary(linkedSessionIds, prLinks),
     workflow: dynamicWorkflowSummary(source),
     lastEvent: lastEventFor(source, state),
@@ -763,10 +974,23 @@ export function buildSessionProjection({
   artifacts = [],
   prLinks = {},
   sessionMessageFabric = null,
+  sessionWorkbench = null,
   sourceErrors = {},
   generatedAt = new Date().toISOString(),
 } = {}) {
-  const context = { artifacts, prLinks, sessionMessageFabric };
+  const groups = groupingSummary(
+    sessionWorkbench,
+    sourceErrors.sessionWorkbench,
+  );
+  const groupAssignments = new Map(
+    groups.assignments.map((entry) => [entry.sessionId, entry.groupId]),
+  );
+  const context = {
+    artifacts,
+    prLinks,
+    sessionMessageFabric,
+    groupAssignments,
+  };
   const sessions = [
     ...(Array.isArray(local) ? local : []).map((source) =>
       projectOne("local", source, context),
@@ -828,6 +1052,11 @@ export function buildSessionProjection({
         : 0,
       sourceErrors.sessionMessageFabric,
     ),
+    sessionWorkbench: sourceStatus(
+      groups.connected ? groups.items.length : 0,
+      sourceErrors.sessionWorkbench ||
+        (groups.connected ? null : groups.reason),
+    ),
   };
   const revision = projectionRevision({
     schema: SESSION_PROJECTION_SCHEMA,
@@ -836,6 +1065,7 @@ export function buildSessionProjection({
       id: session.id,
       revision: session.revision,
     })),
+    groupRevision: groups.revision,
   });
   return {
     schema: SESSION_PROJECTION_SCHEMA,
@@ -845,6 +1075,7 @@ export function buildSessionProjection({
     generatedAt: toIso(generatedAt) || new Date().toISOString(),
     revision,
     sources,
+    groups,
     sessions,
   };
 }
@@ -962,6 +1193,15 @@ export function disconnectedSessionProjection(reasonText = "CLI unavailable") {
     revision: projectionRevision({ connected: false, reason }),
     reason,
     sources: {},
+    groups: {
+      authority: "cli",
+      connected: false,
+      revision: null,
+      generation: 0,
+      reason,
+      items: [],
+      assignments: [],
+    },
     sessions: [],
   };
 }

package/src/lib/session-store-guard.js

@@ -11,9 +11,11 @@
 
 import { resolve, relative, isAbsolute, join } from "node:path";
 import { getHomeDir } from "./paths.js";
+import { resolveClaudeProjectStorageDir } from "./claude-project-storage-layout.js";
 
 export function sessionStoreDir() {
-  return join(getHomeDir(), "sessions");
+  const homeDir = getHomeDir();
+  return resolveClaudeProjectStorageDir(homeDir) || join(homeDir, "sessions");
 }
 
 /**