clay-server 4.0.0-beta.16 → 4.0.0-beta.17

package/lib/daemon-projects.js

@@ -7,6 +7,7 @@
 var fs = require("fs");
 var { scanWorktrees, isWorktree } = require("./worktree");
 var { daemonSync } = require("./daemon-sync");
+var logContext = require("./project-log-context");
 
 // --- Worktree tracking state ---
 var worktreeRegistry = {}; // parentSlug -> [wtSlug, ...]
@@ -28,7 +29,7 @@ function isWorktreeSlug(slug) {
  * @param {string} parentIcon - icon of parent project
  * @param {string} parentOwnerId - owner user ID
  */
-function scanAndRegisterWorktrees(relay, parentPath, parentSlug, parentIcon, parentOwnerId) {
+function scanAndRegisterWorktrees(relay, parentPath, parentSlug, parentIcon, parentOwnerId, projectKnowledgeId) {
   if (isWorktree(parentPath)) return;
   var worktrees = scanWorktrees(parentPath);
   if (worktrees.length === 0) return;
@@ -41,13 +42,14 @@ function scanAndRegisterWorktrees(relay, parentPath, parentSlug, parentIcon, par
       if (worktreeRegistry[parentSlug][j] === wtSlug) { alreadyRegistered = true; break; }
     }
     if (alreadyRegistered) continue;
-    var wtMeta = { parentSlug: parentSlug, branch: wt.branch || wt.dirName, external: wt.external };
+    var context = logContext.resolveWorktreeContext(wt.path, projectKnowledgeId, { branch: wt.branch || wt.dirName });
+    var wtMeta = Object.assign({ parentSlug: parentSlug, external: wt.external, projectKnowledgeId: projectKnowledgeId }, context);
     relay.addProject(wt.path, wtSlug, wt.branch || wt.dirName, parentIcon, parentOwnerId, wtMeta);
     worktreeRegistry[parentSlug].push(wtSlug);
     console.log("[daemon] Registered worktree:", wtSlug, "->", wt.path, wt.external ? "(external)" : "(inside project folder)");
   }
   daemonSync.register(getWorktreeSyncKey(parentSlug), function () {
-    rescanWorktrees(relay, parentPath, parentSlug, parentIcon, parentOwnerId);
+    rescanWorktrees(relay, parentPath, parentSlug, parentIcon, parentOwnerId, null, projectKnowledgeId);
   });
 }
 
@@ -60,7 +62,7 @@ function scanAndRegisterWorktrees(relay, parentPath, parentSlug, parentIcon, par
  * @param {string} parentOwnerId - owner user ID
  * @param {object} [config] - daemon config (optional, for broadcasting project count)
  */
-function rescanWorktrees(relay, parentPath, parentSlug, parentIcon, parentOwnerId, config) {
+function rescanWorktrees(relay, parentPath, parentSlug, parentIcon, parentOwnerId, config, projectKnowledgeId) {
   if (worktreeScanning[parentSlug]) return;
   worktreeScanning[parentSlug] = true;
   try {
@@ -79,7 +81,8 @@ function rescanWorktrees(relay, parentPath, parentSlug, parentIcon, parentOwnerI
         if (existingSlugs[ei] === wtSlug) { found = true; break; }
       }
       if (!found) {
-        var wtMeta = { parentSlug: parentSlug, branch: wt.branch || wt.dirName, external: wt.external };
+        var context = logContext.resolveWorktreeContext(wt.path, projectKnowledgeId, { branch: wt.branch || wt.dirName });
+        var wtMeta = Object.assign({ parentSlug: parentSlug, external: wt.external, projectKnowledgeId: projectKnowledgeId }, context);
         relay.addProject(wt.path, wtSlug, wt.branch || wt.dirName, parentIcon, parentOwnerId, wtMeta);
         if (!worktreeRegistry[parentSlug]) worktreeRegistry[parentSlug] = [];
         worktreeRegistry[parentSlug].push(wtSlug);
@@ -91,6 +94,7 @@ function rescanWorktrees(relay, parentPath, parentSlug, parentIcon, parentOwnerI
       var sSlug = existingSlugs[si];
       var dirName = sSlug.split("--").slice(1).join("--");
       if (!discoveredNames[dirName]) {
+        if (relay.setProjectLogContextState) relay.setProjectLogContextState(sSlug, "archived");
         relay.removeProject(sSlug);
         existingSlugs.splice(si, 1);
         console.log("[daemon] Rescan: removed stale worktree:", sSlug);
@@ -112,6 +116,7 @@ function rescanWorktrees(relay, parentPath, parentSlug, parentIcon, parentOwnerI
 function cleanupWorktreesForParent(relay, parentSlug) {
   var wtSlugs = worktreeRegistry[parentSlug] || [];
   for (var i = 0; i < wtSlugs.length; i++) {
+    if (relay.setProjectLogContextState) relay.setProjectLogContextState(wtSlugs[i], "archived");
     relay.removeProject(wtSlugs[i]);
     console.log("[daemon] Cascade removed worktree:", wtSlugs[i]);
   }

package/lib/daemon.js

@@ -36,6 +36,7 @@ var { createWorktree, removeWorktree, isWorktree } = require("./worktree");
 var mates = require("./mates");
 var mateKnowledgeMigration = require("./mate-knowledge-migration");
 var { isWorktreeSlug, scanAndRegisterWorktrees, rescanWorktrees, cleanupWorktreesForParent, getFilteredRemovedProjects, registerWorktreeSlug, unregisterWorktreeSlug } = require("./daemon-projects");
+var projectLogContext = require("./project-log-context");
 
 var daemonVersion = require("../package.json").version;
 var configFile = process.env.CLAY_CONFIG || process.env.CLAUDE_RELAY_CONFIG || require("./config").configPath();
@@ -65,6 +66,11 @@ try {
   console.error("[daemon] ensureMultiUser threw (continuing):", e && e.message);
 }
 
+if (projectLogContext.initializeProjectKnowledge(config)) {
+  saveConfig(config);
+  console.log("[daemon] Assigned stable knowledge identities to existing projects");
+}
+
 // --- OS users mode: check required system dependencies ---
 // Supplementary-group inheritance (issue #367): default on so sessions behave
 // like a normal login; operators can disable via config / the settings toggle.
@@ -153,6 +159,20 @@ var lanIp = (function () {
 // --- Create multi-project server ---
 var listenHost = config.host || "0.0.0.0";
 
+function rememberedProjectKnowledgeId(projectPath) {
+  var removed = config.removedProjects || [];
+  for (var i = removed.length - 1; i >= 0; i--) {
+    if (removed[i].path === projectPath && projectLogContext.validId(removed[i].projectKnowledgeId)) {
+      return removed[i].projectKnowledgeId;
+    }
+  }
+  return projectLogContext.createProjectKnowledgeId();
+}
+
+function projectRuntimeOptions(project) {
+  return { projectKnowledgeId: project.projectKnowledgeId };
+}
+
 var relay = createServer({
   tlsOptions: tlsOptions,
   caPath: caRoot,
@@ -173,13 +193,14 @@ var relay = createServer({
     }
     var slugs = config.projects.map(function (p) { return p.slug; });
     var slug = generateSlug(absPath, slugs);
-    relay.addProject(absPath, slug, null, null, wsUser ? wsUser.id : null);
     var projectEntry = { path: absPath, slug: slug, addedAt: Date.now(), visibility: "private" };
+    projectEntry.projectKnowledgeId = rememberedProjectKnowledgeId(absPath);
     // The user who adds a project always becomes the owner
     if (wsUser && wsUser.id) {
       projectEntry.ownerId = wsUser.id;
     }
     config.projects.push(projectEntry);
+    relay.addProject(absPath, slug, null, null, wsUser ? wsUser.id : null, null, projectRuntimeOptions(projectEntry));
     // Remove from removedProjects if present
     if (config.removedProjects) {
       config.removedProjects = config.removedProjects.filter(function (rp) { return rp.path !== absPath; });
@@ -198,7 +219,7 @@ var relay = createServer({
       }
     }
     // Discover and register worktrees for the new project
-    scanAndRegisterWorktrees(relay, absPath, slug, null, wsUser && wsUser.id && wsUser.role !== "admin" ? wsUser.id : null);
+    scanAndRegisterWorktrees(relay, absPath, slug, null, wsUser && wsUser.id && wsUser.role !== "admin" ? wsUser.id : null, projectEntry.projectKnowledgeId);
     // Broadcast updated project list to all clients
     relay.broadcastAll({
       type: "projects_updated",
@@ -255,10 +276,11 @@ var relay = createServer({
     }
     // Register project - creator always becomes owner, default private
     var projectEntry = { path: targetDir, slug: slug, addedAt: Date.now(), visibility: "private" };
+    projectEntry.projectKnowledgeId = projectLogContext.createProjectKnowledgeId();
     if (wsUser && wsUser.id) {
       projectEntry.ownerId = wsUser.id;
     }
-    relay.addProject(targetDir, slug, null, null, wsUser ? wsUser.id : null);
+    relay.addProject(targetDir, slug, null, null, wsUser ? wsUser.id : null, null, projectRuntimeOptions(projectEntry));
     config.projects.push(projectEntry);
     saveConfig(config);
     try { syncClayrc(config.projects); } catch (e) {}
@@ -345,10 +367,11 @@ var relay = createServer({
       // Register project - creator always becomes owner
       // Creator always becomes owner, default private
       var projectEntry = { path: targetDir, slug: slug, addedAt: Date.now(), visibility: "private" };
+      projectEntry.projectKnowledgeId = projectLogContext.createProjectKnowledgeId();
       if (wsUser && wsUser.id) {
         projectEntry.ownerId = wsUser.id;
       }
-      relay.addProject(targetDir, slug);
+      relay.addProject(targetDir, slug, null, null, wsUser ? wsUser.id : null, null, projectRuntimeOptions(projectEntry));
       config.projects.push(projectEntry);
       saveConfig(config);
       try { syncClayrc(config.projects); } catch (e) {}
@@ -380,11 +403,14 @@ var relay = createServer({
         if (config.projects[pi].slug === wtParent) { parentProject = config.projects[pi]; break; }
       }
       if (parentProject) {
+        var wtPath = path.join(parentProject.path, wtDirName);
+        var contextStatus = projectLogContext.isMerged(parentProject.path, wtPath) ? "merged" : "archived";
         var rmResult = removeWorktree(parentProject.path, wtDirName);
         if (!rmResult.ok) {
           console.log("[daemon] Failed to remove worktree:", slug, rmResult.error);
           return { ok: false, error: rmResult.error };
         }
+        relay.setProjectLogContextState(slug, contextStatus);
       }
       relay.removeProject(slug);
       unregisterWorktreeSlug(wtParent, slug);
@@ -410,6 +436,7 @@ var relay = createServer({
       title: found.title || null,
       icon: found.icon || null,
       userId: userId || null,
+      projectKnowledgeId: found.projectKnowledgeId || null,
       removedAt: Date.now(),
     });
     // Cap at 20 entries (oldest first)
@@ -984,11 +1011,16 @@ var relay = createServer({
     }
     if (!parent) return { ok: false, error: "Parent project not found" };
     if (isWorktree(parent.path)) return { ok: false, error: "Cannot create worktrees from a worktree project" };
+    var baseCommit = projectLogContext.commit(parent.path, baseBranch || "HEAD");
     var result = createWorktree(parent.path, branchName, dirName, baseBranch);
     if (!result.ok) return result;
     // Register the new worktree as ephemeral project
     var wtSlug = parentSlug + "--" + dirName;
-    var wtMeta = { parentSlug: parentSlug, branch: branchName, external: false };
+    var context = projectLogContext.resolveWorktreeContext(result.path, parent.projectKnowledgeId, {
+      branch: branchName,
+      baseCommit: baseCommit,
+    });
+    var wtMeta = Object.assign({ parentSlug: parentSlug, external: false, projectKnowledgeId: parent.projectKnowledgeId }, context);
     relay.addProject(result.path, wtSlug, branchName, parent.icon, parent.ownerId, wtMeta);
     registerWorktreeSlug(parentSlug, wtSlug);
     console.log("[daemon] Created worktree:", wtSlug, "->", result.path);
@@ -1074,13 +1106,15 @@ var ipc = createIPCServer(socketPath(), function (msg) {
       }
       var slugs = config.projects.map(function (p) { return p.slug; });
       var slug = generateSlug(absPath, slugs);
-      relay.addProject(absPath, slug);
-      config.projects.push({ path: absPath, slug: slug, addedAt: Date.now(), visibility: "private" });
+      var projectEntry = { path: absPath, slug: slug, addedAt: Date.now(), visibility: "private" };
+      projectEntry.projectKnowledgeId = rememberedProjectKnowledgeId(absPath);
+      relay.addProject(absPath, slug, null, null, null, null, projectRuntimeOptions(projectEntry));
+      config.projects.push(projectEntry);
       saveConfig(config);
       try { syncClayrc(config.projects); } catch (e) {}
       console.log("[daemon] Added project:", slug, "→", absPath);
       // Discover and register worktrees for the new project
-      scanAndRegisterWorktrees(relay, absPath, slug, null, null);
+      scanAndRegisterWorktrees(relay, absPath, slug, null, null, projectEntry.projectKnowledgeId);
       relay.broadcastAll({
         type: "projects_updated",
         projects: relay.getProjects(),
@@ -1102,6 +1136,23 @@ var ipc = createIPCServer(socketPath(), function (msg) {
         }
       }
       if (!target) return { ok: false, error: "project not found" };
+      var removedProject = null;
+      for (var ri = 0; ri < config.projects.length; ri++) {
+        if (config.projects[ri].slug === target) { removedProject = config.projects[ri]; break; }
+      }
+      if (removedProject) {
+        if (!config.removedProjects) config.removedProjects = [];
+        config.removedProjects.push({
+          path: removedProject.path,
+          title: removedProject.title || null,
+          icon: removedProject.icon || null,
+          projectKnowledgeId: removedProject.projectKnowledgeId || null,
+          removedAt: Date.now(),
+        });
+        if (config.removedProjects.length > 20) {
+          config.removedProjects = config.removedProjects.slice(config.removedProjects.length - 20);
+        }
+      }
       relay.removeProject(target);
       config.projects = config.projects.filter(function (p) { return p.slug !== target; });
       saveConfig(config);
@@ -1292,9 +1343,9 @@ for (var i = 0; i < projects.length; i++) {
   var p = projects[i];
   if (fs.existsSync(p.path)) {
     console.log("[daemon] Adding project:", p.slug, "→", p.path);
-    relay.addProject(p.path, p.slug, p.title, p.icon, p.ownerId);
+    relay.addProject(p.path, p.slug, p.title, p.icon, p.ownerId, null, projectRuntimeOptions(p));
     // Discover and register worktrees for this project
-    scanAndRegisterWorktrees(relay, p.path, p.slug, p.icon, p.ownerId);
+    scanAndRegisterWorktrees(relay, p.path, p.slug, p.icon, p.ownerId, p.projectKnowledgeId);
   } else {
     console.log("[daemon] Skipping missing project:", p.path);
   }

package/lib/project-log-context.js

@@ -0,0 +1,171 @@
+// Stable project knowledge and Git worktree change-set identities.
+//
+// Existing projects freeze their current path-derived scope so every opaque
+// log ref remains valid. New projects receive a path-independent id. A linked
+// worktree stores its generated change-set marker in Git's administrative
+// directory, which survives daemon restarts and branch renames but disappears
+// with the worktree itself; the durable log records retain the id afterward.
+
+var crypto = require("crypto");
+var fs = require("fs");
+var path = require("path");
+var execFileSync = require("child_process").execFileSync;
+var logsRoot = require("./project-logs-root");
+var utils = require("./utils");
+
+var ID_PATTERN = /^[A-Za-z0-9_-]{1,120}$/;
+
+function newId(prefix) {
+  return prefix + "_" + crypto.randomBytes(16).toString("base64url");
+}
+
+function validId(value, prefix) {
+  return typeof value === "string" && ID_PATTERN.test(value) && (!prefix || value.indexOf(prefix + "_") === 0);
+}
+
+function legacyKnowledgeId(cwd) {
+  return utils.encodeCwd(logsRoot.resolveProjectRoot(cwd));
+}
+
+function ensureProjectKnowledgeId(project) {
+  if (!project || typeof project !== "object") return false;
+  if (validId(project.projectKnowledgeId)) return false;
+  project.projectKnowledgeId = project.path ? legacyKnowledgeId(project.path) : newId("pk");
+  return true;
+}
+
+function initializeProjectKnowledge(config) {
+  var changed = false;
+  var projects = config && Array.isArray(config.projects) ? config.projects : [];
+  for (var i = 0; i < projects.length; i++) {
+    if (ensureProjectKnowledgeId(projects[i])) changed = true;
+  }
+  return changed;
+}
+
+function createProjectKnowledgeId() {
+  return newId("pk");
+}
+
+function git(cwd, args) {
+  return execFileSync("git", args, {
+    cwd: cwd,
+    encoding: "utf8",
+    timeout: 5000,
+    stdio: ["pipe", "pipe", "pipe"],
+  }).trim();
+}
+
+function commit(cwd, ref) {
+  try { return git(cwd, ["rev-parse", ref || "HEAD"]); }
+  catch (e) { return null; }
+}
+
+function markerPath(cwd) {
+  try {
+    var gitDir = git(cwd, ["rev-parse", "--git-dir"]);
+    return path.join(path.resolve(cwd, gitDir), "clay-change-set.json");
+  } catch (e) {
+    return null;
+  }
+}
+
+function readMarker(filePath, knowledgeId) {
+  if (!filePath) return null;
+  try {
+    var parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    if (!parsed || parsed.projectKnowledgeId !== knowledgeId || !validId(parsed.changeSetId, "cs")) return null;
+    return parsed;
+  } catch (e) {
+    return null;
+  }
+}
+
+function deterministicFallback(knowledgeId, cwd) {
+  var digest = crypto.createHash("sha256").update(knowledgeId + "\u0000" + logsRoot.canonicalPath(cwd)).digest("base64url");
+  return "cs_" + digest.substring(0, 22);
+}
+
+function resolveWorktreeContext(cwd, knowledgeId, details) {
+  var input = details || {};
+  var filePath = markerPath(cwd);
+  var marker = readMarker(filePath, knowledgeId);
+  if (!marker) {
+    marker = {
+      projectKnowledgeId: knowledgeId,
+      changeSetId: newId("cs"),
+      baseCommit: input.baseCommit || null,
+      createdAt: Date.now(),
+    };
+    if (filePath) {
+      try {
+        fs.writeFileSync(filePath, JSON.stringify(marker, null, 2) + "\n", { flag: "wx", mode: 0o600 });
+      } catch (e) {
+        marker = readMarker(filePath, knowledgeId) || marker;
+      }
+    }
+  }
+  if (!filePath || !readMarker(filePath, knowledgeId)) {
+    marker.changeSetId = deterministicFallback(knowledgeId, cwd);
+  }
+  return {
+    kind: "worktree",
+    changeSetId: marker.changeSetId,
+    branch: input.branch || null,
+    baseCommit: marker.baseCommit || input.baseCommit || null,
+    headCommit: commit(cwd, "HEAD"),
+    status: "active",
+  };
+}
+
+function isMerged(parentCwd, worktreeCwd) {
+  var head = commit(worktreeCwd, "HEAD");
+  if (!head) return false;
+  try {
+    execFileSync("git", ["merge-base", "--is-ancestor", head, "HEAD"], {
+      cwd: parentCwd,
+      timeout: 5000,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+function cleanCommit(value) {
+  return typeof value === "string" && /^[0-9a-f]{7,64}$/i.test(value) ? value : null;
+}
+
+function cleanBranch(value) {
+  if (typeof value !== "string") return null;
+  var cleaned = value.trim().substring(0, 200);
+  return cleaned && cleaned.indexOf("\n") === -1 && cleaned.indexOf("\r") === -1 ? cleaned : null;
+}
+
+function normalizeRecordContext(value) {
+  if (!value || value.kind !== "worktree" || !validId(value.changeSetId, "cs")) {
+    return { kind: "project", changeSetId: null, branch: null, baseCommit: null, headCommit: null, status: "active" };
+  }
+  return {
+    kind: "worktree",
+    changeSetId: value.changeSetId,
+    branch: cleanBranch(value.branch),
+    baseCommit: cleanCommit(value.baseCommit),
+    headCommit: cleanCommit(value.headCommit),
+    status: value.status === "merged" || value.status === "archived" ? value.status : "active",
+  };
+}
+
+module.exports = {
+  ID_PATTERN: ID_PATTERN,
+  validId: validId,
+  legacyKnowledgeId: legacyKnowledgeId,
+  ensureProjectKnowledgeId: ensureProjectKnowledgeId,
+  initializeProjectKnowledge: initializeProjectKnowledge,
+  createProjectKnowledgeId: createProjectKnowledgeId,
+  resolveWorktreeContext: resolveWorktreeContext,
+  commit: commit,
+  isMerged: isMerged,
+  normalizeRecordContext: normalizeRecordContext,
+};

package/lib/project-log-feedback-delivery.js

@@ -1,6 +1,6 @@
-// Deliver new Project Log comments to the exact live session responsible for
-// the canonical entry. Comments remain durable in the ledger when that session
-// is gone; this module never guesses another session or creates one.
+// Deliver new Project Log comments to the session responsible for the
+// canonical entry. A busy Driver gets an isolated hidden reviewer so feedback
+// never waits behind unrelated work in the visible conversation.
 
 function attachProjectLogFeedbackDelivery(ctx) {
   var sm = ctx.sm;
@@ -8,8 +8,7 @@ function attachProjectLogFeedbackDelivery(ctx) {
   var onProcessingChanged = ctx.onProcessingChanged || function () {};
   var getLinuxUserForSession = ctx.getLinuxUserForSession || function () { return null; };
 
-  function findAuthorSession(entry) {
-    var author = entry && entry.updatedBy;
+  function sessionForAuthor(author) {
     if (!author || author.type !== "session" || !author.sessionKey) return null;
     var match = null;
     sm.sessions.forEach(function (session) {
@@ -22,6 +21,48 @@ function attachProjectLogFeedbackDelivery(ctx) {
     return match;
   }
 
+  function findAuthorSession(entry) {
+    return sessionForAuthor(entry && entry.updatedBy) || sessionForAuthor(entry && entry.createdBy);
+  }
+
+  function startImmediateReviewer(source, entry, text, sdk) {
+    if (!sm.createSessionRaw || !sm.deleteSessionQuiet) return false;
+    var reviewer = sm.createSessionRaw({
+      ownerId: source.ownerId || null,
+      sessionVisibility: "private",
+      vendor: source.vendor || null,
+      model: source.model || null,
+      effort: source.effort || null,
+      permissionMode: source.permissionMode || null,
+    });
+    reviewer.hidden = true;
+    reviewer.title = "Project Log review";
+    reviewer.singleTurn = true;
+    reviewer.projectLogReview = { ref: entry.ref };
+    reviewer.isProcessing = true;
+    reviewer.sentToolResults = {};
+    reviewer.onQueryComplete = function () {
+      setImmediate(function () { sm.deleteSessionQuiet(reviewer.localId); });
+    };
+    sm.sendAndRecord(reviewer, {
+      type: "user_message",
+      text: text,
+      _internal: true,
+      projectLogFeedback: true,
+      projectLogRef: entry.ref,
+    });
+    Promise.resolve(sdk.startQuery(reviewer, text, null, getLinuxUserForSession(reviewer))).catch(function (error) {
+      reviewer.isProcessing = false;
+      sm.sendAndRecord(reviewer, {
+        type: "error",
+        text: "Could not review Project Log feedback: " + (error.message || String(error)),
+        _internal: true,
+      });
+      sm.deleteSessionQuiet(reviewer.localId);
+    });
+    return true;
+  }
+
   function feedbackPrompt(entry) {
     return "[Project Log feedback]\n" +
       "A user added a comment to " + entry.ref + ". Review the pending feedback now with list_log_feedback, " +
@@ -37,6 +78,7 @@ function attachProjectLogFeedbackDelivery(ctx) {
     var sdk = getSdk();
     if (!session || !sdk) return false;
     var text = feedbackPrompt(entry);
+    if (session.isProcessing && startImmediateReviewer(session, entry, text, sdk)) return true;
     sm.sendAndRecord(session, {
       type: "user_message",
       text: text,

package/lib/project-logs-context-state.js

@@ -0,0 +1,42 @@
+// Append-only lifecycle projection for worktree-scoped Project Log entries.
+
+var recordStore = require("./knowledge-record-store");
+var logContext = require("./project-log-context");
+
+function attachContextState(store, scopeId) {
+  function states() {
+    var out = {};
+    var records = store.all();
+    for (var i = 0; i < records.length; i++) {
+      var record = records[i];
+      if (record.op !== "context-state" || !record.changeSetId) continue;
+      if (record.status !== "archived" && record.status !== "merged" && record.status !== "active") continue;
+      out[record.changeSetId] = record.status;
+    }
+    return out;
+  }
+
+  function set(context, status) {
+    var normalized = logContext.normalizeRecordContext(context);
+    if (!normalized.changeSetId) return false;
+    if (status !== "active" && status !== "archived" && status !== "merged") {
+      throw new Error("Invalid Project Log change-set status.");
+    }
+    if (states()[normalized.changeSetId] === status) return false;
+    store.append({
+      id: recordStore.newRecordId(),
+      rootId: "context-" + normalized.changeSetId,
+      op: "context-state",
+      scope: scopeId,
+      changeSetId: normalized.changeSetId,
+      status: status,
+      context: normalized,
+      at: Date.now(),
+    });
+    return true;
+  }
+
+  return { states: states, set: set };
+}
+
+module.exports = { attachContextState: attachContextState };

package/lib/project-logs-mcp-server.js

@@ -78,6 +78,7 @@ var CATEGORY_DESCRIPTION = "Record category: a short lowercase hyphen-separated
 var PRIORITY_DESCRIPTION = "How much this outranks routine work: " + logsSchema.PRIORITIES.join(", ") + ". Defaults to normal. Priority is independent of category, so an urgent decision is both.";
 var SUMMARY_DESCRIPTION = "One or two sentences combining the user's requested outcome with the current result or status. This is what a new Driver sees in the ledger, so it must stand alone. For a learning entry, identify the concept the user engaged with plainly enough that the row itself teaches it.";
 var REF_DESCRIPTION = "Opaque log reference returned by list_logs, search_logs, or create_log.";
+var CONTEXT_DESCRIPTION = "Optional logical scope: current includes project-wide entries plus this worktree's change set, project shows only project-wide entries, and all includes archived and merged worktree changes. Defaults to current in a worktree and project otherwise.";
 
 function textResult(value) {
   return Promise.resolve({ content: [{ type: "text", text: JSON.stringify(value) }] });
@@ -114,6 +115,7 @@ function projectTools(bound) {
         kind: { type: "string", description: "Optional category filter, matched exactly against this project's vocabulary. The response lists the categories currently in use." },
         priority: { type: "string", enum: logsSchema.PRIORITIES, description: "Optional priority filter." },
         tag: { type: "string", description: "Optional single tag filter." },
+        contextMode: { type: "string", enum: ["current", "project", "all"], description: CONTEXT_DESCRIPTION },
         cursor: { type: "string", description: "Opaque pagination cursor from a previous response." },
         limit: { type: "number", description: "Page size, from 1 to " + logsStore.MAX_PAGE + "." },
       }),
@@ -126,6 +128,7 @@ function projectTools(bound) {
         query: { type: "string", description: "Search query." },
         kind: { type: "string", description: "Optional category filter, matched exactly against this project's vocabulary. The response lists the categories currently in use." },
         priority: { type: "string", enum: logsSchema.PRIORITIES, description: "Optional priority filter." },
+        contextMode: { type: "string", enum: ["current", "project", "all"], description: CONTEXT_DESCRIPTION },
         cursor: { type: "string", description: "Opaque pagination cursor from a previous response." },
         limit: { type: "number", description: "Page size, from 1 to " + logsStore.MAX_PAGE + "." },
       }, ["query"]),
@@ -239,6 +242,7 @@ function globalTools(bound) {
         kind: { type: "string", description: "Optional category filter, matched exactly against this project's vocabulary. The response lists the categories currently in use." },
         priority: { type: "string", enum: logsSchema.PRIORITIES, description: "Optional priority filter." },
         tag: { type: "string", description: "Optional single tag filter." },
+        contextMode: { type: "string", enum: ["project", "all"], description: CONTEXT_DESCRIPTION },
         cursor: { type: "string", description: "Opaque pagination cursor from a previous response." },
         limit: { type: "number", description: "Page size, from 1 to " + logsStore.MAX_PAGE + "." },
       }, ["projectSlug"]),
@@ -252,6 +256,7 @@ function globalTools(bound) {
         query: { type: "string", description: "Search query." },
         kind: { type: "string", description: "Optional category filter, matched exactly against this project's vocabulary. The response lists the categories currently in use." },
         priority: { type: "string", enum: logsSchema.PRIORITIES, description: "Optional priority filter." },
+        contextMode: { type: "string", enum: ["project", "all"], description: CONTEXT_DESCRIPTION },
         cursor: { type: "string", description: "Opaque pagination cursor from a previous response." },
         limit: { type: "number", description: "Page size, from 1 to " + logsStore.MAX_PAGE + "." },
       }, ["projectSlug", "query"]),

package/lib/project-logs-query.js

@@ -62,6 +62,19 @@ function page(items, args) {
   };
 }
 
+function contextMode(options) {
+  var value = options && options.contextMode;
+  return value === "all" || value === "current" || value === "project" ? value : "all";
+}
+
+function matchesContext(entry, options) {
+  var mode = contextMode(options);
+  var changeSetId = entry && entry.context && entry.context.changeSetId;
+  if (mode === "all") return true;
+  if (mode === "project") return !changeSetId;
+  return !changeSetId || changeSetId === options.currentChangeSetId;
+}
+
 function listEntries(entries, args, cleanLine, validateKind) {
   var options = args || {};
   var kind = options.kind ? validateKind(options.kind, null) : null;
@@ -73,6 +86,7 @@ function listEntries(entries, args, cleanLine, validateKind) {
     if (kind && entry.category !== kind) return false;
     if (priority && entry.priority !== priority) return false;
     if (tag && entry.tags.indexOf(tag) === -1) return false;
+    if (!matchesContext(entry, options)) return false;
     return true;
   });
   var result = page(filtered, options);
@@ -116,6 +130,7 @@ function summarize(entry) {
     // How many comments still await Driver review. A count only: the ledger
     // never carries comment bodies.
     pendingFeedbackCount: entry.pendingFeedbackCount || 0,
+    context: entry.context || null,
   };
 }
 
@@ -128,6 +143,7 @@ function searchEntries(entries, args, cleanLine, validateKind) {
   var candidates = entries.filter(function (entry) {
     if (kind && entry.category !== kind) return false;
     if (priority && entry.priority !== priority) return false;
+    if (!matchesContext(entry, options)) return false;
     return true;
   });
 
@@ -161,6 +177,8 @@ module.exports = {
   encodeCursor: encodeCursor,
   decodeCursor: decodeCursor,
   page: page,
+  contextMode: contextMode,
+  matchesContext: matchesContext,
   summarize: summarize,
   listEntries: listEntries,
   searchEntries: searchEntries,

package/lib/project-logs-root.js

@@ -60,8 +60,16 @@ function scopeIdForRoot(root) {
   return "project/" + utils.encodeCwd(root);
 }
 
+function scopeIdForKnowledgeId(knowledgeId) {
+  if (typeof knowledgeId !== "string" || !/^[A-Za-z0-9_-]{1,120}$/.test(knowledgeId)) {
+    throw new Error("Invalid project knowledge id.");
+  }
+  return "project/" + knowledgeId;
+}
+
 module.exports = {
   resolveProjectRoot: resolveProjectRoot,
   scopeIdForRoot: scopeIdForRoot,
+  scopeIdForKnowledgeId: scopeIdForKnowledgeId,
   canonicalPath: canonicalPath,
 };