sentinelayer-cli 0.30.1 → 0.30.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.30.1",
+  "version": "0.30.3",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/commands/session.js

@@ -32,6 +32,7 @@ import {
   registerAgent,
   unregisterAgent,
 } from "../session/agent-registry.js";
+import { inferSessionAgentIdentity } from "../session/agent-identity.js";
 import { startSenti, stopSenti } from "../session/daemon.js";
 import {
   getDaemonStatus,
@@ -42,7 +43,9 @@ import {
 import { listRuntimeRuns } from "../session/runtime-bridge.js";
 import {
   listFileLocks,
+  lockFile,
   releaseFileLocksForAgent,
+  unlockFile,
 } from "../session/file-locks.js";
 import {
   injectSessionGuides,
@@ -1605,20 +1608,30 @@ async function publishListenerPresenceEvent({
   agentId,
   agentModel = "cli",
   displayName = "",
+  provider = "",
+  clientKind = "cli",
   listenerId,
   lifecycle = {},
 } = {}) {
   const normalizedType = normalizeString(lifecycle.type) || "heartbeat";
   const eventName = listenerLifecycleEventName(normalizedType);
+  const identity = inferSessionAgentIdentity({
+    agentId,
+    model: agentModel,
+    displayName,
+    provider,
+    clientKind,
+  });
   const event = createAgentEvent({
     event: eventName,
     sessionId,
     agent: {
       id: agentId,
-      model: normalizeString(agentModel) || "cli",
+      model: normalizeString(identity.model) || "cli",
       role: "listener",
-      displayName: normalizeString(displayName) || agentId,
-      clientKind: "cli",
+      displayName: normalizeString(identity.displayName) || agentId,
+      provider: normalizeString(identity.provider) || undefined,
+      clientKind: normalizeString(identity.clientKind) || "cli",
     },
     eventId: `session-listener-${listenerId}-${normalizedType}-${lifecycle.pollCount ?? 0}`,
     idempotencyToken: `session-listener:${listenerId}:${normalizedType}:${lifecycle.pollCount ?? 0}`,
@@ -1674,20 +1687,30 @@ export function buildSessionCoachingEvent({
   agentId,
   agentModel = "cli",
   displayName = "",
+  provider = "",
+  clientKind = "cli",
   listenerId = "",
   tick = 0,
   tips = SESSION_LIVE_SUCCESS_TIPS,
 } = {}) {
   const tipList = Array.isArray(tips) && tips.length ? tips : SESSION_LIVE_SUCCESS_TIPS;
+  const identity = inferSessionAgentIdentity({
+    agentId,
+    model: agentModel,
+    displayName,
+    provider,
+    clientKind,
+  });
   return createAgentEvent({
     event: "session_coaching",
     sessionId,
     agent: {
       id: agentId,
-      model: normalizeString(agentModel) || "cli",
+      model: normalizeString(identity.model) || "cli",
       role: "listener",
-      displayName: normalizeString(displayName) || agentId,
-      clientKind: "cli",
+      displayName: normalizeString(identity.displayName) || agentId,
+      provider: normalizeString(identity.provider) || undefined,
+      clientKind: normalizeString(identity.clientKind) || "cli",
     },
     eventId: `session-coaching-${listenerId || agentId}-${tick}`,
     idempotencyToken: `session-coaching:${listenerId || agentId}:${tick}`,
@@ -1705,20 +1728,30 @@ function buildListenerCatchupEvent({
   agentId,
   agentModel = "cli",
   displayName = "",
+  provider = "",
+  clientKind = "cli",
   listenerId,
   catchup = {},
 } = {}) {
   const message = formatListenerCatchupNotice(catchup);
   const pollCount = Number(catchup.pollCount || 0);
+  const identity = inferSessionAgentIdentity({
+    agentId,
+    model: agentModel,
+    displayName,
+    provider,
+    clientKind,
+  });
   return createAgentEvent({
     event: "session_listen_catchup",
     sessionId,
     agent: {
       id: agentId,
-      model: normalizeString(agentModel) || "cli",
+      model: normalizeString(identity.model) || "cli",
       role: "listener",
-      displayName: normalizeString(displayName) || agentId,
-      clientKind: "cli",
+      displayName: normalizeString(identity.displayName) || agentId,
+      provider: normalizeString(identity.provider) || undefined,
+      clientKind: normalizeString(identity.clientKind) || "cli",
     },
     eventId: `session-listener-${listenerId}-catchup-${pollCount}`,
     idempotencyToken: `session-listener:${listenerId}:catchup:${pollCount}`,
@@ -1957,6 +1990,9 @@ async function ensureSessionSayAgentRegistered(
   const registered = await rememberAgentIdentity(sessionId, {
     agentId,
     model: normalizeString(agent.model) || "cli",
+    displayName: normalizeString(agent.displayName),
+    provider: normalizeString(agent.provider),
+    clientKind: normalizeString(agent.clientKind) || "cli",
     role: sessionSayRegistryRole(agent.role),
     targetPath,
   });
@@ -1993,12 +2029,24 @@ async function resolveSessionAgentEnvelope(
   const resolvedRole = normalizeString(role) || normalizeString(registeredAgent?.role);
   const resolvedDisplayName =
     normalizeString(displayName) || normalizeString(registeredAgent?.displayName);
+  const identity = inferSessionAgentIdentity({
+    agentId: normalizedAgentId,
+    model: resolvedModel,
+    displayName: resolvedDisplayName,
+    provider: registeredAgent?.provider,
+    clientKind: normalizeString(clientKind) || normalizeString(registeredAgent?.clientKind) || "cli",
+  });
   const envelope = {
     id: normalizedAgentId,
-    model: resolvedModel || undefined,
+    model: normalizeString(identity.model) || resolvedModel || undefined,
     role: resolvedRole || undefined,
-    displayName: resolvedDisplayName || undefined,
-    clientKind: normalizeString(clientKind) || undefined,
+    displayName: normalizeString(identity.displayName) || resolvedDisplayName || undefined,
+    provider: normalizeString(identity.provider) || undefined,
+    clientKind:
+      normalizeString(identity.clientKind) ||
+      normalizeString(clientKind) ||
+      normalizeString(registeredAgent?.clientKind) ||
+      undefined,
   };
   return Object.fromEntries(Object.entries(envelope).filter(([, value]) => value !== undefined));
 }
@@ -2014,30 +2062,6 @@ export function buildSessionLockDirective(verb, file, intent = "") {
   return normalizedIntent ? `lock: ${normalizedFile} - ${normalizedIntent}` : `lock: ${normalizedFile}`;
 }
 
-// Posts a coordination directive (e.g. "lock: <file> - <intent>") as a session
-// message so the session daemon processes it into the authoritative file-lock
-// registry. Used by `session lock`/`unlock` as ergonomic sugar over the
-// say-convention; locks are advisory + daemon-enforced with TTL auto-release,
-// so this is a best-effort post.
-async function postSessionDirectiveMessage(sessionId, message, {
-  agentId,
-  targetPath = process.cwd(),
-} = {}) {
-  const clientMessageId = `cli-${randomUUID()}`;
-  const agent = await resolveSessionAgentEnvelope(sessionId, agentId, { targetPath });
-  await ensureSessionSayAgentRegistered(sessionId, agent, { targetPath });
-  const event = createAgentEvent({
-    event: "session_message",
-    agent,
-    sessionId,
-    payload: { message, channel: "session", clientMessageId },
-  });
-  event.eventId = clientMessageId;
-  event.idempotencyToken = clientMessageId;
-  const result = await syncSessionEventToApi(sessionId, event, { targetPath });
-  return { event, result };
-}
-
 async function runWithConcurrency(items = [], concurrency = 1, worker = async () => null) {
   const normalizedItems = Array.isArray(items) ? items : [];
   const normalizedConcurrency = Math.max(
@@ -3043,6 +3067,8 @@ export function registerSessionCommand(program) {
         targetPath,
         agentId: resolvedAgentId,
         model,
+        displayName: normalizeString(acceptedOnboarding?.displayName),
+        clientKind: "cli",
         role,
         trackProcessExit: false,
         awaitRemoteSync: hasConcreteAgentIdentity,
@@ -3081,6 +3107,9 @@ export function registerSessionCommand(program) {
         agentId: joined.agentId,
         role: joined.role,
         model: joined.model,
+        displayName: joined.displayName || null,
+        provider: joined.provider || null,
+        clientKind: joined.clientKind || null,
         status: joined.status,
         joinedAt: joined.joinedAt,
         materializedLocalSession: localSession.materialized,
@@ -3327,12 +3356,19 @@ export function registerSessionCommand(program) {
       if (to) {
         eventPayload.to = to;
       }
+      const agentIdentity = inferSessionAgentIdentity({
+        agentId,
+        model: options.model,
+        displayName: options.displayName,
+        clientKind: "cli",
+      });
       const agent = {
         id: agentId,
-        model: normalizeString(options.model) || "cli",
-        displayName: normalizeString(options.displayName) || undefined,
+        model: normalizeString(agentIdentity.model) || "cli",
+        displayName: normalizeString(agentIdentity.displayName) || undefined,
+        provider: normalizeString(agentIdentity.provider) || undefined,
         role: normalizeString(options.role) || "coder",
-        clientKind: "cli",
+        clientKind: normalizeString(agentIdentity.clientKind) || "cli",
       };
       const event = createAgentEvent({
         event: "session_message",
@@ -3672,7 +3708,7 @@ export function registerSessionCommand(program) {
       return payload;
     });
 
-  const runLockDirectiveCommand = async (verb, sessionId, files, options, command) => {
+  const runFileLockCommand = async (verb, sessionId, files, options, command) => {
     const normalizedSessionId = normalizeString(sessionId);
     if (!normalizedSessionId) {
       throw new Error("session id is required.");
@@ -3698,20 +3734,68 @@ export function registerSessionCommand(program) {
       );
     }
     const intent = normalizeString(options.intent);
+    const results = [];
     const processed = [];
+    const skipped = [];
+    const failed = [];
     for (const file of fileList) {
-      const directive = buildSessionLockDirective(verb, file, intent);
-      await postSessionDirectiveMessage(normalizedSessionId, directive, {
-        agentId: identity.agentId,
+      if (verb === "lock") {
+        const result = await lockFile(normalizedSessionId, identity.agentId, file, {
+          intent,
+          targetPath,
+          awaitRemoteSync: true,
+        });
+        const record = {
+          file: result.file || file,
+          locked: Boolean(result.locked),
+          reason: result.reason || (result.locked ? "locked" : "held_by_other_agent"),
+          heldBy: result.heldBy || null,
+          since: result.since || null,
+        };
+        results.push(record);
+        if (result.locked) {
+          processed.push(record.file);
+        } else {
+          failed.push(record);
+        }
+        continue;
+      }
+
+      const result = await unlockFile(normalizedSessionId, identity.agentId, file, {
+        reason: intent || "manual_release",
         targetPath,
+        awaitRemoteSync: true,
       });
-      processed.push(file);
+      const record = {
+        file: result.file || file,
+        unlocked: Boolean(result.unlocked),
+        reason: result.reason || (result.unlocked ? "unlocked" : "not_locked"),
+        heldBy: result.heldBy || null,
+        since: result.since || null,
+      };
+      results.push(record);
+      if (result.unlocked) {
+        processed.push(record.file);
+      } else if (record.reason === "not_locked") {
+        skipped.push(record);
+      } else {
+        failed.push(record);
+      }
+    }
+
+    if (failed.length > 0) {
+      const summary = failed
+        .map((item) => `${item.file}${item.heldBy ? ` held by ${item.heldBy}` : ""}`)
+        .join(", ");
+      throw new Error(`session ${verb} failed for ${summary}`);
     }
     const payload = {
       command: `session ${verb}`,
       sessionId: normalizedSessionId,
       agentId: identity.agentId,
       files: processed,
+      results,
+      skipped,
     };
     if (shouldEmitJson(options, command)) {
       console.log(JSON.stringify(payload, null, 2));
@@ -3735,7 +3819,7 @@ export function registerSessionCommand(program) {
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
     .action(async (sessionId, files, options, command) => {
-      await runLockDirectiveCommand("lock", sessionId, files, options, command);
+      await runFileLockCommand("lock", sessionId, files, options, command);
     });
 
   session
@@ -3746,7 +3830,7 @@ export function registerSessionCommand(program) {
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
     .action(async (sessionId, files, options, command) => {
-      await runLockDirectiveCommand("unlock", sessionId, files, options, command);
+      await runFileLockCommand("unlock", sessionId, files, options, command);
     });
 
   session
@@ -3966,8 +4050,16 @@ export function registerSessionCommand(program) {
         "presence-interval",
         60,
       );
-      const agentModel = normalizeString(options.model) || "cli";
-      const displayName = normalizeString(options.displayName) || agentId;
+      const listenerIdentity = inferSessionAgentIdentity({
+        agentId,
+        model: options.model,
+        displayName: options.displayName,
+        clientKind: "cli",
+      });
+      const agentModel = normalizeString(listenerIdentity.model) || "cli";
+      const displayName = normalizeString(listenerIdentity.displayName) || agentId;
+      const provider = normalizeString(listenerIdentity.provider);
+      const clientKind = normalizeString(listenerIdentity.clientKind) || "cli";
       const limit = parsePositiveInteger(options.limit, "limit", 200);
       const emitFormat = normalizeString(options.emit).toLowerCase() || "ndjson";
       if (!["ndjson", "text"].includes(emitFormat)) {
@@ -4059,6 +4151,8 @@ export function registerSessionCommand(program) {
                 agentId,
                 agentModel,
                 displayName,
+                provider,
+                clientKind,
                 listenerId,
                 tick: coachingTick++,
               }),
@@ -4129,6 +4223,8 @@ export function registerSessionCommand(program) {
                     agentId,
                     agentModel,
                     displayName,
+                    provider,
+                    clientKind,
                     listenerId,
                     catchup,
                   }),
@@ -4231,6 +4327,8 @@ export function registerSessionCommand(program) {
               agentId,
               agentModel,
               displayName,
+              provider,
+              clientKind,
               listenerId,
               lifecycle,
             });

package/src/session/agent-identity.js

@@ -0,0 +1,119 @@
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function normalizeLookup(value) {
+  return normalizeString(value).toLowerCase();
+}
+
+function titleFromIdentifier(value) {
+  const parts = normalizeString(value)
+    .replace(/[_-]+/g, " ")
+    .split(/\s+/)
+    .map((part) => part.trim())
+    .filter(Boolean);
+  if (!parts.length) return "";
+  return parts
+    .map((part) => {
+      if (/^[0-9]+$/.test(part)) return part;
+      return `${part.charAt(0).toUpperCase()}${part.slice(1)}`;
+    })
+    .join(" ");
+}
+
+function isWeakModel(value) {
+  const normalized = normalizeLookup(value);
+  return !normalized || ["anonymous", "cli", "unknown", "unreported"].includes(normalized);
+}
+
+function inferFamily(agentId, model) {
+  const haystack = `${agentId} ${model}`.toLowerCase();
+  if (haystack.includes("claude") || haystack.includes("sonnet") || haystack.includes("opus")) {
+    return "claude";
+  }
+  if (haystack.includes("codex") || haystack.includes("gpt-") || haystack.includes("openai")) {
+    return "codex";
+  }
+  if (haystack.includes("gemini") || haystack.includes("google")) return "gemini";
+  if (haystack.includes("grok") || haystack.includes("xai")) return "grok";
+  if (haystack.includes("senti") || haystack.includes("sentinelayer")) return "senti";
+  return "";
+}
+
+function inferModel(family) {
+  if (family === "codex") return "gpt-5-codex";
+  if (family === "claude") return "claude";
+  if (family === "gemini") return "gemini";
+  if (family === "grok") return "grok";
+  if (family === "senti") return "gpt-5.4-mini";
+  return "";
+}
+
+function inferProvider(family, model) {
+  const normalizedModel = normalizeLookup(model);
+  if (family === "claude" || normalizedModel.includes("claude")) return "anthropic";
+  if (family === "codex" || normalizedModel.includes("gpt") || normalizedModel.includes("openai")) {
+    return "openai";
+  }
+  if (family === "gemini" || normalizedModel.includes("gemini")) return "google";
+  if (family === "grok" || normalizedModel.includes("grok")) return "xai";
+  if (family === "senti") return "sentinelayer";
+  return "";
+}
+
+function inferClientKind(family) {
+  if (family === "codex") return "codex";
+  if (family === "claude") return "claude";
+  if (family === "gemini") return "gemini";
+  if (family === "grok") return "grok";
+  if (family === "senti") return "senti";
+  return "";
+}
+
+function inferDisplayName(agentId, family) {
+  const normalizedId = normalizeLookup(agentId);
+  if (normalizedId === "senti") return "Senti";
+  if (normalizedId.includes("claude-verifier")) return "Claude Verifier";
+  if (normalizedId.startsWith("claude")) return "Claude";
+  if (normalizedId.startsWith("codex")) return "Codex";
+  if (normalizedId.startsWith("gemini")) return "Gemini";
+  if (normalizedId.startsWith("grok")) return "Grok";
+  if (family) return titleFromIdentifier(family);
+  return titleFromIdentifier(agentId);
+}
+
+export function inferSessionAgentIdentity(input = {}) {
+  const source =
+    input && typeof input === "object" && !Array.isArray(input)
+      ? input
+      : {};
+  const {
+    agentId = "",
+    model = "",
+    displayName = "",
+    provider = "",
+    clientKind = "",
+  } = source;
+  const normalizedAgentId = normalizeString(agentId);
+  const explicitModel = normalizeString(model);
+  const family = inferFamily(normalizedAgentId, explicitModel);
+  const resolvedModel = isWeakModel(explicitModel)
+    ? inferModel(family) || explicitModel || "unknown"
+    : explicitModel;
+  const resolvedProvider = normalizeString(provider) || inferProvider(family, resolvedModel);
+  const resolvedClientKind = normalizeString(clientKind) || inferClientKind(family) || "cli";
+  const resolvedDisplayName =
+    normalizeString(displayName) || inferDisplayName(normalizedAgentId, family);
+
+  return Object.fromEntries(
+    Object.entries({
+      agentId: normalizedAgentId,
+      model: resolvedModel,
+      displayName: resolvedDisplayName,
+      provider: resolvedProvider,
+      clientKind: resolvedClientKind,
+    }).filter(([, value]) => normalizeString(value)),
+  );
+}
+
+export { titleFromIdentifier };

package/src/session/agent-registry.js

@@ -5,6 +5,7 @@ import process from "node:process";
 
 import { STUCK_THRESHOLDS } from "../agents/jules/pulse.js";
 import { createAgentEvent } from "../events/schema.js";
+import { inferSessionAgentIdentity } from "./agent-identity.js";
 import { resolveSessionPaths } from "./paths.js";
 import { emitContextBriefing } from "./recap.js";
 import {
@@ -120,6 +121,9 @@ function normalizeAgentSnapshot(snapshot = {}, nowIso = new Date().toISOString()
     sessionId: normalizeString(snapshot.sessionId),
     agentId: normalizeString(snapshot.agentId),
     model: normalizeString(snapshot.model) || "unknown",
+    displayName: normalizeString(snapshot.displayName) || "",
+    provider: normalizeString(snapshot.provider) || "",
+    clientKind: normalizeString(snapshot.clientKind) || "",
     role: normalizeRole(snapshot.role || "observer"),
     status: normalizeStatus(snapshot.status, "idle"),
     detail: normalizeString(snapshot.detail) || "",
@@ -149,13 +153,30 @@ async function readAgentSnapshot(snapshotPath) {
   }
 }
 
-async function writeAgentSnapshot(snapshotPath, snapshot) {
+const _snapshotWriteQueues = new Map();
+
+async function writeAgentSnapshotFile(snapshotPath, snapshot) {
   await fsp.mkdir(path.dirname(snapshotPath), { recursive: true });
-  const tmpPath = `${snapshotPath}.${process.pid}.${Date.now()}.tmp`;
+  const tmpPath = `${snapshotPath}.${process.pid}.${Date.now()}.${randomBytes(4).toString("hex")}.tmp`;
   await fsp.writeFile(tmpPath, `${JSON.stringify(snapshot, null, 2)}\n`, "utf-8");
   await fsp.rename(tmpPath, snapshotPath);
 }
 
+async function writeAgentSnapshot(snapshotPath, snapshot) {
+  const previous = _snapshotWriteQueues.get(snapshotPath) || Promise.resolve();
+  const write = previous
+    .catch(() => {})
+    .then(() => writeAgentSnapshotFile(snapshotPath, snapshot));
+  _snapshotWriteQueues.set(snapshotPath, write);
+  try {
+    await write;
+  } finally {
+    if (_snapshotWriteQueues.get(snapshotPath) === write) {
+      _snapshotWriteQueues.delete(snapshotPath);
+    }
+  }
+}
+
 async function emitAgentEvent(
   sessionId,
   event,
@@ -164,7 +185,14 @@ async function emitAgentEvent(
 ) {
   const envelope = createAgentEvent({
     event,
-    agentId: payload.agentId,
+    agent: {
+      id: payload.agentId,
+      model: payload.model,
+      displayName: payload.displayName,
+      provider: payload.provider,
+      role: payload.role,
+      clientKind: payload.clientKind,
+    },
     sessionId,
     payload,
   });
@@ -198,13 +226,15 @@ function isActiveAgentSnapshot(snapshot) {
   return true;
 }
 
-function chooseAgentRefreshModel(value, existingModel) {
+function chooseAgentRefreshModel(value, existingModel, sourceValue = value) {
   const candidate = normalizeString(value);
   const existing = normalizeString(existingModel);
+  const source = normalizeString(sourceValue).toLowerCase();
+  const sourceIsWeak = !source || ["anonymous", "cli", "unknown", "unreported"].includes(source);
   if (!candidate) {
     return existing || "unknown";
   }
-  if (existing && ["cli", "unknown"].includes(candidate.toLowerCase())) {
+  if (existing && (sourceIsWeak || ["cli", "unknown"].includes(candidate.toLowerCase()))) {
     return existing;
   }
   return candidate;
@@ -222,6 +252,19 @@ function chooseAgentRefreshRole(value, existingRole) {
   return candidate;
 }
 
+function chooseAgentRefreshMetadata(value, existingValue, sourceValue = value) {
+  const candidate = normalizeString(value);
+  const existing = normalizeString(existingValue);
+  const source = normalizeString(sourceValue);
+  if (!candidate) {
+    return existing;
+  }
+  if (existing && !source) {
+    return existing;
+  }
+  return candidate;
+}
+
 // In-process registry of agents registered by *this* CLI process. The
 // dashboard treats any participant without a terminal agent_leave /
 // agent_killed / session_killed event as "active". When a CLI exits via
@@ -283,6 +326,9 @@ export async function registerAgent(
   {
     agentId = "",
     model = "",
+    displayName = "",
+    provider = "",
+    clientKind = "",
     role = "observer",
     targetPath = process.cwd(),
     trackProcessExit = true,
@@ -311,6 +357,14 @@ export async function registerAgent(
     }
   }
 
+  const identity = inferSessionAgentIdentity({
+    agentId: resolvedAgentId,
+    model,
+    displayName,
+    provider,
+    clientKind,
+  });
+
   const snapshotPath = buildAgentSnapshotPath(paths, resolvedAgentId);
   const existing = await readAgentSnapshot(snapshotPath);
 
@@ -320,7 +374,10 @@ export async function registerAgent(
         ...existing,
         sessionId: paths.sessionId,
         agentId: resolvedAgentId,
-        model: chooseAgentRefreshModel(model, existing.model),
+        model: chooseAgentRefreshModel(identity.model, existing.model, model),
+        displayName: chooseAgentRefreshMetadata(identity.displayName, existing.displayName, displayName),
+        provider: chooseAgentRefreshMetadata(identity.provider, existing.provider, provider),
+        clientKind: chooseAgentRefreshMetadata(identity.clientKind, existing.clientKind, clientKind),
         role: chooseAgentRefreshRole(role, existing.role),
         status: normalizeString(existing.status) || "idle",
         detail: normalizeString(existing.detail) || "",
@@ -350,7 +407,10 @@ export async function registerAgent(
     {
       sessionId: paths.sessionId,
       agentId: resolvedAgentId,
-      model: normalizeString(model) || "unknown",
+      model: normalizeString(identity.model) || "unknown",
+      displayName: normalizeString(identity.displayName),
+      provider: normalizeString(identity.provider),
+      clientKind: normalizeString(identity.clientKind),
       role,
       status: "idle",
       detail: "",
@@ -369,6 +429,9 @@ export async function registerAgent(
   await emitAgentEvent(paths.sessionId, "agent_join", {
     agentId: snapshot.agentId,
     model: snapshot.model,
+    displayName: snapshot.displayName,
+    provider: snapshot.provider,
+    clientKind: snapshot.clientKind,
     role: snapshot.role,
     status: snapshot.status,
   }, { targetPath, awaitRemoteSync });
@@ -412,6 +475,9 @@ export async function rememberAgentIdentity(
   {
     agentId = "",
     model = "",
+    displayName = "",
+    provider = "",
+    clientKind = "",
     role = "observer",
     targetPath = process.cwd(),
   } = {}
@@ -422,6 +488,13 @@ export async function rememberAgentIdentity(
   if (!resolvedAgentId) {
     throw new Error("agentId is required.");
   }
+  const identity = inferSessionAgentIdentity({
+    agentId: resolvedAgentId,
+    model,
+    displayName,
+    provider,
+    clientKind,
+  });
 
   const snapshotPath = buildAgentSnapshotPath(paths, resolvedAgentId);
   const existing = await readAgentSnapshot(snapshotPath);
@@ -430,7 +503,10 @@ export async function rememberAgentIdentity(
       ...(existing || {}),
       sessionId: paths.sessionId,
       agentId: resolvedAgentId,
-      model: normalizeString(model) || normalizeString(existing?.model) || "unknown",
+      model: chooseAgentRefreshModel(identity.model, existing?.model, model),
+      displayName: chooseAgentRefreshMetadata(identity.displayName, existing?.displayName, displayName),
+      provider: chooseAgentRefreshMetadata(identity.provider, existing?.provider, provider),
+      clientKind: chooseAgentRefreshMetadata(identity.clientKind, existing?.clientKind, clientKind),
       role: normalizeString(role) || normalizeString(existing?.role) || "observer",
       status: normalizeString(existing?.status) || "idle",
       detail: normalizeString(existing?.detail) || "",
@@ -536,6 +612,9 @@ export async function unregisterAgent(
     reason: normalizedReason,
     role: snapshot.role,
     model: snapshot.model,
+    displayName: snapshot.displayName,
+    provider: snapshot.provider,
+    clientKind: snapshot.clientKind,
   }, { targetPath });
   // Already left explicitly — don't double-emit on process exit.
   _untrackLocalAgent(paths.sessionId, snapshot.agentId);

package/src/session/file-locks.js

@@ -260,6 +260,8 @@ async function appendLockEvent(
   {
     targetPath = process.cwd(),
     nowIso = new Date().toISOString(),
+    syncRemote = true,
+    awaitRemoteSync = false,
   } = {}
 ) {
   return appendToStream(
@@ -273,6 +275,8 @@ async function appendLockEvent(
     }),
     {
       targetPath,
+      syncRemote,
+      awaitRemoteSync,
     }
   );
 }
@@ -371,6 +375,8 @@ export async function lockFile(
     ttlSeconds = DEFAULT_FILE_LOCK_TTL_SECONDS,
     targetPath = process.cwd(),
     nowIso = new Date().toISOString(),
+    syncRemote = true,
+    awaitRemoteSync = false,
   } = {}
 ) {
   const normalizedAgentId = normalizeAgentId(agentId);
@@ -437,6 +443,8 @@ export async function lockFile(
       {
         targetPath,
         nowIso: normalizedNow,
+        syncRemote,
+        awaitRemoteSync,
       }
     );
     return {
@@ -462,6 +470,8 @@ export async function unlockFile(
     targetPath = process.cwd(),
     nowIso = new Date().toISOString(),
     actorAgentId = null,
+    syncRemote = true,
+    awaitRemoteSync = false,
   } = {}
 ) {
   const normalizedAgentId = normalizeAgentId(agentId);
@@ -527,6 +537,8 @@ export async function unlockFile(
     {
       targetPath,
       nowIso: normalizedNow,
+      syncRemote,
+      awaitRemoteSync,
     }
   );