sentinelayer-cli 0.9.2 → 0.9.4

package/package.json

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

package/src/commands/session.js

@@ -44,9 +44,11 @@ import {
   createSession,
   DEFAULT_TTL_SECONDS,
   getSession,
+  isSessionCacheExpired,
   listActiveSessions,
   listAllSessions,
   recordSessionProvisionedIdentities,
+  refreshSessionCacheForRemoteActivity,
   updateSessionTitle,
 } from "../session/store.js";
 import { appendToStream, readStream, tailStream } from "../session/stream.js";
@@ -330,11 +332,44 @@ function formatRelativeAge(isoTimestamp) {
 
 async function ensureLocalSessionForRemoteCommand(
   sessionId,
-  { targetPath, title = "", skipRemoteProbe = false } = {},
+  { targetPath, title = "", skipRemoteProbe = false, remoteSession = null } = {},
 ) {
   const existing = await getSession(sessionId, { targetPath });
   if (existing) {
-    return { materialized: false, session: existing };
+    if (!isSessionCacheExpired(existing)) {
+      return { materialized: false, refreshed: false, session: existing };
+    }
+    const existingStatus = normalizeString(existing.status).toLowerCase();
+    const locallyClosedByStatus = existingStatus === "expired" || existingStatus === "archived";
+    if (locallyClosedByStatus && !skipRemoteProbe) {
+      throw new Error(
+        `Session '${sessionId}' is ${existingStatus} locally; run \`sl session join ${sessionId}\` to verify remote access before posting.`,
+      );
+    }
+
+    let access = { accessible: Boolean(skipRemoteProbe), reason: "" };
+    if (!skipRemoteProbe) {
+      access = await probeSessionAccess(sessionId, { targetPath }).catch((error) => ({
+        accessible: false,
+        reason: normalizeString(error?.message) || "probe_failed",
+      }));
+    }
+    if (!access?.accessible) {
+      throw new Error(
+        `Session '${sessionId}' is expired locally and remote access failed (${access?.reason || "unknown"}).`,
+      );
+    }
+
+    const refreshed = await refreshSessionCacheForRemoteActivity(sessionId, {
+      targetPath,
+      title,
+      lastInteractionAt:
+        normalizeString(remoteSession?.lastInteractionAt) ||
+        normalizeString(remoteSession?.lastActivityAt) ||
+        normalizeString(remoteSession?.updatedAt) ||
+        normalizeString(remoteSession?.createdAt),
+    });
+    return { materialized: false, refreshed: Boolean(refreshed), session: refreshed || existing };
   }
   // `skipRemoteProbe` is set by callers that have already verified the session
   // via `verifyRemoteSession` (the singleton GET) — re-probing the legacy
@@ -356,7 +391,7 @@ async function ensureLocalSessionForRemoteCommand(
     sessionId,
     title: normalizeString(title) || `remote-${String(sessionId).slice(0, 8)}`,
   });
-  return { materialized: true, session: created };
+  return { materialized: true, refreshed: false, session: created };
 }
 
 async function ensureWorkspaceSession({
@@ -470,56 +505,16 @@ function normalizeAgentId(value, fallbackValue = "cli-user") {
   return normalized || fallbackValue;
 }
 
-// Derive a stable, human-friendly fallback agent id from the active auth
-// session — `human-<github_username>` if logged in via GitHub, else
-// `human-<email-localpart>` as a last resort. We resolve this lazily and
-// cache per process so repeated `sl session say` calls don't churn auth.
-//
-// Carter's complaint: "we aren't auto naming these agents per joining,
-// we need to figure out a fingerprint for them somehow.. maybe at joining
-// we ask for name?" — auth-derived names are the cleanest deterministic
-// fingerprint we already have. Fall through to "cli-user" only if the
-// CLI is genuinely unauthenticated (CI fixture, fresh checkout).
-let _cachedAuthAgentId = undefined; // undefined = not yet resolved
-async function _resolveAuthAgentId(targetPath) {
-  if (_cachedAuthAgentId !== undefined) return _cachedAuthAgentId;
-  try {
-    const auth = await resolveActiveAuthSession({
-      cwd: targetPath || process.cwd(),
-      env: process.env,
-      autoRotate: false,
-    });
-    const username = normalizeString(auth?.user?.githubUsername).toLowerCase();
-    if (username) {
-      _cachedAuthAgentId = `human-${username.replace(/[^a-z0-9._-]+/g, "-")}`;
-      return _cachedAuthAgentId;
-    }
-    const email = normalizeString(auth?.user?.email).toLowerCase();
-    if (email) {
-      const local = email.split("@")[0].replace(/[^a-z0-9._-]+/g, "-");
-      if (local) {
-        _cachedAuthAgentId = `human-${local}`;
-        return _cachedAuthAgentId;
-      }
-    }
-  } catch {
-    /* unauthenticated → fall through */
-  }
-  _cachedAuthAgentId = "";
-  return "";
+// Preserve the literal default identity for `session say`. This command is
+// often used by agents as a low-friction relay; silently rewriting the default
+// `cli-user` to the authenticated human makes a forgotten --agent flag look
+// like the workspace owner authored the message.
+export function resolveSessionSayAgentId(value) {
+  return normalizeAgentId(value, "cli-user");
 }
 
-// Wrapper that prefers the auth-derived id over the literal `cli-user`
-// placeholder when the caller didn't pass --name/--agent. Callers that
-// supplied a name keep round-tripping verbatim.
-async function defaultAgentId(value, targetPath) {
-  const explicit = normalizeString(value);
-  if (explicit && explicit.toLowerCase() !== "cli-user") {
-    return normalizeAgentId(value, "cli-user");
-  }
-  const authId = await _resolveAuthAgentId(targetPath);
-  if (authId) return authId;
-  return normalizeAgentId(value, "cli-user");
+async function defaultAgentId(value, _targetPath) {
+  return resolveSessionSayAgentId(value);
 }
 
 async function runWithConcurrency(items = [], concurrency = 1, worker = async () => null) {
@@ -933,6 +928,7 @@ export function registerSessionCommand(program) {
           targetPath,
           title: normalizeString(remoteSession.title),
           skipRemoteProbe: true,
+          remoteSession,
         });
         const payload = {
           command: "session ensure",
@@ -942,6 +938,7 @@ export function registerSessionCommand(program) {
           resumed: true,
           attached: true,
           materializedLocalSession: localSession.materialized,
+          refreshedLocalSession: Boolean(localSession.refreshed),
           verificationSource: verification.source,
           dashboardUrl: buildDashboardUrl(explicitSessionId),
         };
@@ -1145,6 +1142,7 @@ export function registerSessionCommand(program) {
         targetPath,
         title: normalizeString(remoteSession.title),
         skipRemoteProbe: true,
+        remoteSession,
       });
 
       const explicitAgent = normalizeString(options.agent);
@@ -1195,6 +1193,7 @@ export function registerSessionCommand(program) {
         status: joined.status,
         joinedAt: joined.joinedAt,
         materializedLocalSession: localSession.materialized,
+        refreshedLocalSession: Boolean(localSession.refreshed),
         verificationSource: verification.source,
         eventCount: Number.isFinite(eventCount) ? eventCount : 0,
         agentCount: Number.isFinite(agentCount) ? agentCount : 0,
@@ -1277,6 +1276,7 @@ export function registerSessionCommand(program) {
         agentId,
         event: persisted,
         materializedLocalSession: localSession.materialized,
+        refreshedLocalSession: Boolean(localSession.refreshed),
         remoteSync: remoteSync || undefined,
       };
       if (shouldEmitJson(options, command)) {
@@ -1364,6 +1364,7 @@ export function registerSessionCommand(program) {
         agentId,
         event: persisted,
         materializedLocalSession: localSession.materialized,
+        refreshedLocalSession: Boolean(localSession.refreshed),
         remoteSync,
       };
       if (shouldEmitJson(options, command)) {

package/src/session/recap.js

@@ -13,6 +13,14 @@ const DEFAULT_RECAP_MAX_EVENTS = 100;
 const DEFAULT_RECAP_INTERVAL_MS = 300_000;
 const DEFAULT_RECAP_INACTIVITY_MS = 600_000;
 const DEFAULT_RECAP_ACTIVITY_THRESHOLD = 5;
+const DEFAULT_TASK_SUMMARY_LIMIT = 3;
+const ACTIVE_TASK_STATUSES = new Set(["PENDING", "ACCEPTED", "BLOCKED"]);
+const TASK_STATUS_KEYS = {
+  PENDING: "pending",
+  ACCEPTED: "accepted",
+  COMPLETED: "completed",
+  BLOCKED: "blocked",
+};
 
 const ACTIVE_RECAP_EMITTERS = new Map();
 
@@ -160,6 +168,117 @@ async function readPendingTasks(sessionId, { forAgentId = "", targetPath = proce
   }
 }
 
+function normalizeTaskStatus(value) {
+  const normalized = normalizeString(value).toUpperCase();
+  return Object.prototype.hasOwnProperty.call(TASK_STATUS_KEYS, normalized)
+    ? normalized
+    : "PENDING";
+}
+
+function taskOwner(task = {}) {
+  return (
+    normalizeString(task.toAgentId) ||
+    normalizeString(task.requestedToAgentId) ||
+    (normalizeString(task.roleFilter) ? `role:${normalizeString(task.roleFilter)}` : "") ||
+    "unassigned"
+  );
+}
+
+function shortTaskText(value) {
+  const text = normalizeString(value).replace(/\s+/g, " ");
+  if (text.length <= 80) {
+    return text;
+  }
+  return `${text.slice(0, 77)}...`;
+}
+
+function emptyTaskLedgerSummary() {
+  return {
+    total: 0,
+    active: 0,
+    pending: 0,
+    accepted: 0,
+    blocked: 0,
+    completed: 0,
+    owners: [],
+    recent: [],
+  };
+}
+
+function summarizeTaskLedger(tasks = [], { limit = DEFAULT_TASK_SUMMARY_LIMIT } = {}) {
+  const summary = emptyTaskLedgerSummary();
+  const owners = new Map();
+  const normalizedTasks = [];
+
+  for (const task of Array.isArray(tasks) ? tasks : []) {
+    if (!task || typeof task !== "object") {
+      continue;
+    }
+    const status = normalizeTaskStatus(task.status);
+    const statusKey = TASK_STATUS_KEYS[status];
+    const owner = taskOwner(task);
+    const priority = normalizeString(task.priority) || "when-free";
+    const taskId = normalizeString(task.taskId) || "task";
+    const updatedAt = normalizeIsoTimestamp(
+      task.updatedAt || task.completedAt || task.acceptedAt || task.createdAt,
+      new Date().toISOString(),
+    );
+    const record = {
+      taskId,
+      status,
+      priority,
+      owner,
+      task: shortTaskText(task.task),
+      updatedAt,
+    };
+    normalizedTasks.push(record);
+    summary.total += 1;
+    summary[statusKey] += 1;
+
+    if (ACTIVE_TASK_STATUSES.has(status)) {
+      summary.active += 1;
+      const ownerRecord = owners.get(owner) || {
+        agentId: owner,
+        active: 0,
+        pending: 0,
+        accepted: 0,
+        blocked: 0,
+      };
+      ownerRecord.active += 1;
+      ownerRecord[statusKey] += 1;
+      owners.set(owner, ownerRecord);
+    }
+  }
+
+  summary.owners = [...owners.values()]
+    .sort((left, right) => {
+      if (right.active !== left.active) return right.active - left.active;
+      return left.agentId.localeCompare(right.agentId);
+    })
+    .slice(0, Math.max(1, limit));
+  summary.recent = normalizedTasks
+    .sort((left, right) => toEpoch(right.updatedAt) - toEpoch(left.updatedAt))
+    .slice(0, Math.max(1, limit));
+  return summary;
+}
+
+async function readTaskLedgerSummary(
+  sessionId,
+  { targetPath = process.cwd(), limit = DEFAULT_TASK_SUMMARY_LIMIT } = {},
+) {
+  const paths = resolveSessionPaths(sessionId, { targetPath });
+  try {
+    const raw = await fsp.readFile(paths.tasksPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    return summarizeTaskLedger(parsed?.tasks || [], { limit });
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return emptyTaskLedgerSummary();
+    }
+    return emptyTaskLedgerSummary();
+  }
+}
+
 function buildElapsedMinutes(events = [], nowIso = new Date().toISOString()) {
   if (!Array.isArray(events) || events.length === 0) {
     return 0;
@@ -181,6 +300,7 @@ function buildRecapText({
   totalFindings = 0,
   activeLocks = 0,
   pendingTasks = 0,
+  taskLedger = emptyTaskLedgerSummary(),
   snippets = [],
 } = {}) {
   const agentText =
@@ -191,13 +311,78 @@ function buildRecapText({
   const lockText = `${activeLocks} file lock${activeLocks === 1 ? "" : "s"} active`;
   const pendingText =
     pendingTasks > 0 ? `You have ${pendingTasks} pending task${pendingTasks === 1 ? "" : "s"}.` : "";
+  const taskText = buildTaskLedgerText(taskLedger);
   const snippetText = snippets.length > 0 ? `Recent: ${snippets.join(" | ")}` : "";
-  return `While you were away: ${agentText}. ${findingText}. ${lockText}. ${pendingText} ${snippetText}`.replace(
+  return `While you were away: ${agentText}. ${findingText}. ${lockText}. ${pendingText} ${taskText}. ${snippetText}`.replace(
     /\s+/g,
     " "
   ).trim();
 }
 
+function buildTaskLedgerText(taskLedger = emptyTaskLedgerSummary()) {
+  const total = Number(taskLedger.total || 0);
+  if (!total) {
+    return "Tasks: none queued";
+  }
+  const active = Number(taskLedger.active || 0);
+  const counts = [
+    `${Number(taskLedger.pending || 0)} pending`,
+    `${Number(taskLedger.accepted || 0)} accepted`,
+    `${Number(taskLedger.blocked || 0)} blocked`,
+    `${Number(taskLedger.completed || 0)} done`,
+  ].join(", ");
+  const ownerText =
+    Array.isArray(taskLedger.owners) && taskLedger.owners.length > 0
+      ? `Owners: ${taskLedger.owners
+          .map((owner) => {
+            const parts = [];
+            if (owner.pending) parts.push(`${owner.pending} pending`);
+            if (owner.accepted) parts.push(`${owner.accepted} accepted`);
+            if (owner.blocked) parts.push(`${owner.blocked} blocked`);
+            return `${owner.agentId} (${parts.join("/") || `${owner.active || 0} active`})`;
+          })
+          .join("; ")}`
+      : "Owners: none active";
+  const recentText =
+    Array.isArray(taskLedger.recent) && taskLedger.recent.length > 0
+      ? `Recent tasks: ${taskLedger.recent
+          .map((task) => `${task.priority} ${task.status} ${task.owner}: ${task.task}`)
+          .join(" | ")}`
+      : "";
+  return [`Tasks: ${active} active of ${total} total (${counts})`, ownerText, recentText]
+    .filter(Boolean)
+    .join(". ");
+}
+
+// Multi-agent session etiquette + read-path rules surfaced in the
+// context_briefing payload an agent receives on first join. Web
+// renders this as markdown (see sentinelayer-web Session.tsx
+// SessionMessage), so headers/lists/inline code are intentional.
+//
+// Keep this short and operationally actionable. Anything that's
+// purely doctrinal belongs in AGENTS.md, not the per-join briefing.
+const AGENT_JOIN_RULES = [
+  "**Welcome to this session.** Quick rules so we coordinate cleanly:",
+  "",
+  "**Reading the room** — When you join, the recap above summarizes activity since the last quiet stretch. To read further back, run `sl session read --remote --tail 50 --json` (bump `--tail` if you need more). Do this BEFORE responding so you don't repeat questions or miss a lock-and-claim someone else already opened.",
+  "",
+  "**Polling cadence** — Poll new events at most once per 60s (`sl session listen` or `sl session read --remote --tail N`). More frequent than that wastes budget and can hit per-user rate limits. Less frequent than ~5min and peers may think you went idle.",
+  "",
+  "**Writing back** — You can use **markdown**: bold, italic, lists, fenced code, and `inline code`. The web dashboard renders it. Plain text also works. Keep posts terse and technical — link to the work, don't recap it.",
+  "",
+  "**Coordination** — Lock-and-claim before you start a scope another agent could be on. If you push back on someone's approach, cite the specific assumption you disagree with and the file:line evidence.",
+  "",
+  "**Stop conditions** — If the human asks you to stop, stop. If 60+ minutes of total session silence, stop polling.",
+].join("\n");
+
+function buildAgentJoinBriefingText({ recap = "", forAgent = "" } = {}) {
+  const trimmedRecap = normalizeString(recap);
+  const trimmedAgent = normalizeString(forAgent);
+  const greeting = trimmedAgent ? `**${trimmedAgent}** joined. ${trimmedRecap}` : trimmedRecap;
+  const recapBlock = greeting || "Welcome — no prior session activity to summarize yet.";
+  return `${recapBlock}\n\n---\n\n${AGENT_JOIN_RULES}`;
+}
+
 function buildPeriodicText(recap = {}) {
   const summary = recap.summary && typeof recap.summary === "object" ? recap.summary : {};
   const elapsedMinutes = Number(summary.elapsedMinutes || 0);
@@ -206,7 +391,8 @@ function buildPeriodicText(recap = {}) {
   const activeLocks = Number(summary.activeLocks || 0);
   const lastActor = normalizeString(summary.lastActorId);
   const actorText = lastActor ? `${lastActor} active` : "no active actor";
-  return `Session active for ${elapsedMinutes}m. ${activeAgents} agents. ${totalFindings} findings. ${activeLocks} locks. ${actorText}.`;
+  const taskText = buildTaskLedgerText(summary.taskLedger);
+  return `Session active for ${elapsedMinutes}m. ${activeAgents} agents. ${totalFindings} findings. ${activeLocks} locks. ${taskText}. ${actorText}.`;
 }
 
 export async function buildSessionRecap(
@@ -259,6 +445,9 @@ export async function buildSessionRecap(
     forAgentId: normalizedForAgentId,
     targetPath: normalizedTargetPath,
   });
+  const taskLedger = await readTaskLedgerSummary(normalizedSessionId, {
+    targetPath: normalizedTargetPath,
+  });
   const snippets = summarizeRecentActivity(visibleEvents, {
     forAgentId: normalizedForAgentId,
     limit: 2,
@@ -270,6 +459,7 @@ export async function buildSessionRecap(
     totalFindings: totalFindingsCount,
     activeLocks,
     pendingTasks,
+    taskLedger,
     snippets,
   });
 
@@ -288,6 +478,7 @@ export async function buildSessionRecap(
       totalFindingsCount,
       activeLocks,
       pendingTasksForAgent: pendingTasks,
+      taskLedger,
       snippets,
       elapsedMinutes,
       lastActorId: normalizeString(latestEvent?.agent?.id || latestEvent?.agentId) || null,
@@ -303,6 +494,7 @@ export async function emitContextBriefing(
     maxEvents = DEFAULT_RECAP_MAX_EVENTS,
     targetPath = process.cwd(),
     nowIso = new Date().toISOString(),
+    includeJoinRules = true,
   } = {}
 ) {
   const recap = await buildSessionRecap(sessionId, {
@@ -311,6 +503,9 @@ export async function emitContextBriefing(
     targetPath,
     nowIso,
   });
+  const briefingMessage = includeJoinRules
+    ? buildAgentJoinBriefingText({ recap: recap.text, forAgent: forAgentId })
+    : recap.text;
   const event = createAgentEvent({
     event: "context_briefing",
     agentId: SENTI_AGENT_ID,
@@ -319,7 +514,9 @@ export async function emitContextBriefing(
     ts: recap.generatedAt,
     payload: {
       forAgent: normalizeString(forAgentId) || null,
+      message: briefingMessage,
       recap: recap.text,
+      rules: includeJoinRules ? AGENT_JOIN_RULES : null,
       ephemeral: true,
       style: RECAP_STYLE,
       generatedAt: recap.generatedAt,

package/src/session/remote-hydrate.js

@@ -20,7 +20,12 @@
 
 import { listSessionsFromApi, pollHumanMessages, pollSessionEvents } from "./sync.js";
 import { appendToStream, readStream } from "./stream.js";
-import { createSession, getSession } from "./store.js";
+import {
+  createSession,
+  getSession,
+  isSessionCacheExpired,
+  refreshSessionCacheForRemoteActivity,
+} from "./store.js";
 import { readSyncCursor, writeSyncCursor } from "./sync-cursor.js";
 import {
   addSessionEventIdentityKeys,
@@ -42,10 +47,8 @@ async function readExistingRelayKeys(sessionId, { targetPath = process.cwd() } =
 
 async function ensureLocalSessionShell(sessionId, { targetPath = process.cwd() } = {}) {
   const existing = await getSession(sessionId, { targetPath });
-  if (existing) {
-    return { materialized: false, session: existing };
-  }
   let remoteStatus = "";
+  let remoteSession = null;
   const remoteList = await listSessionsFromApi({
     targetPath,
     includeArchived: true,
@@ -53,14 +56,40 @@ async function ensureLocalSessionShell(sessionId, { targetPath = process.cwd() }
   }).catch(() => null);
   if (remoteList?.ok) {
     const match = (remoteList.sessions || []).find((entry) => entry?.sessionId === sessionId);
+    remoteSession = match || null;
     remoteStatus = String(match?.archiveStatus || match?.status || "").trim().toLowerCase();
   }
+  if (existing) {
+    const existingStatus = String(existing.status || "").trim().toLowerCase();
+    const locallyClosedByStatus = existingStatus === "expired" || existingStatus === "archived";
+    const remoteAllowsRefresh =
+      ["active", "pending"].includes(remoteStatus) || (!remoteStatus && !locallyClosedByStatus);
+    if (isSessionCacheExpired(existing) && remoteAllowsRefresh) {
+      const refreshed = await refreshSessionCacheForRemoteActivity(sessionId, {
+        targetPath,
+        title: remoteSession?.title || "",
+        lastInteractionAt:
+          remoteSession?.lastInteractionAt ||
+          remoteSession?.lastActivityAt ||
+          remoteSession?.updatedAt ||
+          remoteSession?.createdAt ||
+          "",
+      });
+      return {
+        materialized: false,
+        refreshed: Boolean(refreshed),
+        session: refreshed || existing,
+        remoteStatus,
+      };
+    }
+    return { materialized: false, refreshed: false, session: existing, remoteStatus };
+  }
   const created = await createSession({
     targetPath,
     sessionId,
     title: `remote-${String(sessionId).slice(0, 8)}`,
   });
-  return { materialized: true, session: created, remoteStatus };
+  return { materialized: true, refreshed: false, session: created, remoteStatus };
 }
 
 function sourceFullyRelayed(events = [], successfulKeys = new Set()) {

package/src/session/store.js

@@ -388,7 +388,8 @@ function normalizeMetadata(raw = {}, { sessionId, targetPath, nowIso } = {}) {
 }
 
 function isExpired(metadata, nowIso = new Date().toISOString()) {
-  if (!metadata || normalizeSessionStatus(metadata.status) === SESSION_STATUS_EXPIRED) {
+  const status = normalizeSessionStatus(metadata?.status);
+  if (!metadata || status === SESSION_STATUS_EXPIRED || status === SESSION_STATUS_ARCHIVED) {
     return true;
   }
   const expiryEpoch = Date.parse(normalizeIsoTimestamp(metadata.expiresAt, nowIso));
@@ -399,6 +400,10 @@ function isExpired(metadata, nowIso = new Date().toISOString()) {
   return nowEpoch >= expiryEpoch;
 }
 
+export function isSessionCacheExpired(metadata, nowIso = new Date().toISOString()) {
+  return isExpired(metadata, nowIso);
+}
+
 function buildSessionPayload(metadata, paths, nowIso = new Date().toISOString()) {
   return {
     sessionId: metadata.sessionId,
@@ -526,6 +531,53 @@ export async function updateSessionTitle(
   return buildSessionPayload(saved, loaded.paths, nowIso);
 }
 
+export async function refreshSessionCacheForRemoteActivity(
+  sessionId,
+  {
+    targetPath = process.cwd(),
+    title = "",
+    ttlSeconds = DEFAULT_TTL_SECONDS,
+    lastInteractionAt = "",
+    nowIso = new Date().toISOString(),
+  } = {}
+) {
+  const loaded = await loadMetadata(sessionId, { targetPath });
+  if (!loaded) {
+    return null;
+  }
+  const normalizedTtlSeconds = normalizePositiveInteger(ttlSeconds, DEFAULT_TTL_SECONDS);
+  const remoteInteractionIso = normalizeIsoTimestamp(
+    lastInteractionAt,
+    loaded.metadata.lastInteractionAt || loaded.metadata.createdAt || nowIso
+  );
+  const currentInteractionEpoch = Date.parse(
+    normalizeIsoTimestamp(loaded.metadata.lastInteractionAt, loaded.metadata.createdAt || nowIso)
+  );
+  const remoteInteractionEpoch = Date.parse(remoteInteractionIso);
+  const lastInteractionIso =
+    Number.isFinite(remoteInteractionEpoch) &&
+    (!Number.isFinite(currentInteractionEpoch) || remoteInteractionEpoch > currentInteractionEpoch)
+      ? remoteInteractionIso
+      : normalizeIsoTimestamp(loaded.metadata.lastInteractionAt, nowIso);
+
+  const metadata = {
+    ...loaded.metadata,
+    updatedAt: nowIso,
+    expiresAt: toIsoAfterSeconds(nowIso, normalizedTtlSeconds),
+    ttlSeconds: normalizedTtlSeconds,
+    status: SESSION_STATUS_ACTIVE,
+    expiredAt: null,
+    lastInteractionAt: lastInteractionIso,
+  };
+  const normalizedTitle = normalizeString(title);
+  if (normalizedTitle) {
+    metadata.title = normalizedTitle;
+  }
+
+  const saved = await saveMetadata(metadata, loaded.paths);
+  return buildSessionPayload(saved, loaded.paths, nowIso);
+}
+
 export async function recordSessionRemoteTitleSync(
   sessionId,
   {