@kairyou/agent-tools 0.13.2 → 0.13.4

package/dist/log/hook.mjs

@@ -897,21 +897,75 @@ async function main() {
   const statePath = path.join(CACHE_ROOT, `${day}.state.json`);
   const snapshotsRoot = path.join(CACHE_ROOT, `${day}.snapshots`);
   await fs.mkdir(CACHE_ROOT, { recursive: true });
-  await cleanupCache(day);
-  const state = await loadState(statePath, day);
-  await handleEvent(state, hookInput, { now, snapshotsRoot, effective, scopeKey, scopePath: scope?.path || "" });
-  await writeFileAtomic(statePath, `${JSON.stringify(state, null, 2)}
-`);
-  if (effective.format === "detailed") {
-    const report = await renderDetailedReport(state, {
+  const release = await acquireLock(path.join(CACHE_ROOT, `${day}.lock`));
+  if (!release) {
+    await debugLog(`dropped ${eventName}: could not acquire ${day}.lock`);
+    return;
+  }
+  try {
+    await cleanupCache(day);
+    const state = await loadState(statePath, day);
+    await handleEvent(state, hookInput, {
+      now,
       snapshotsRoot,
-      language: effective.language,
-      scopeKey
+      effective,
+      scopeKey,
+      scopePath: scope?.path || ""
     });
-    await fs.mkdir(effective.output, { recursive: true });
-    await writeFileAtomic(path.join(effective.output, `${day}.md`), report);
-  } else {
-    await updateDailyFile(effective.output, day, buildDailyItems(state, scopeKey));
+    await writeFileAtomic(statePath, `${JSON.stringify(state, null, 2)}
+`);
+    if (effective.format === "detailed") {
+      const report = await renderDetailedReport(state, {
+        snapshotsRoot,
+        language: effective.language,
+        scopeKey
+      });
+      await fs.mkdir(effective.output, { recursive: true });
+      await writeFileAtomic(path.join(effective.output, `${day}.md`), report);
+    } else {
+      await updateDailyFile(effective.output, day, buildDailyItems(state, scopeKey));
+    }
+  } finally {
+    await release();
+  }
+}
+var LOCK_TIMEOUT_MS = 5e3;
+var LOCK_RETRY_MS = 25;
+var LOCK_STALE_MS = 3e4;
+async function acquireLock(lockPath) {
+  const deadline = Date.now() + LOCK_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    try {
+      const handle = await fs.open(lockPath, "wx");
+      await handle.close();
+      return async () => {
+        try {
+          await fs.unlink(lockPath);
+        } catch {
+        }
+      };
+    } catch (error) {
+      if (error?.code !== "EEXIST") return null;
+      const age = await fs.stat(lockPath).then(({ mtimeMs }) => Date.now() - mtimeMs).catch(() => 0);
+      if (age > LOCK_STALE_MS) {
+        await fs.unlink(lockPath).catch(() => {
+        });
+        continue;
+      }
+      await sleep(LOCK_RETRY_MS);
+    }
+  }
+  return null;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function debugLog(message) {
+  if (process.env.AGENT_TOOLS_LOG_DEBUG !== "1") return;
+  try {
+    await fs.appendFile(path.join(CACHE_ROOT, "debug.log"), `${(/* @__PURE__ */ new Date()).toISOString()} ${message}
+`);
+  } catch {
   }
 }
 function eventCwd(input) {
@@ -980,6 +1034,11 @@ async function handleEvent(state, input, context) {
   const session = ensureSession(state, sessionId, timestamp);
   session.last_time = timestamp;
   if (eventName === "UserPromptSubmit") {
+    const last = session.turns[session.turns.length - 1];
+    if (last && !last.request_text && last.result_summary) {
+      last.request_text = excerptMultiline(getPromptText(input), 1600);
+      return;
+    }
     session.turns.push(
       createTurn(session, timestamp, getPromptText(input), resolveProjectLabel(input, context.scopePath), context.scopeKey)
     );
@@ -1028,7 +1087,7 @@ async function cleanupCache(day) {
   }
   await Promise.all(
     entries.map(async (entry) => {
-      const isState = entry.isFile() && /^\d{4}-\d{2}-\d{2}\.state\.json$/.test(entry.name);
+      const isState = entry.isFile() && /^\d{4}-\d{2}-\d{2}\.(state\.json|lock)$/.test(entry.name);
       const isSnapshots = entry.isDirectory() && /^\d{4}-\d{2}-\d{2}\.snapshots$/.test(entry.name);
       if (!isState && !isSnapshots || entry.name.startsWith(day)) return;
       try {
@@ -1192,30 +1251,46 @@ async function updateDailyFile(outputFile, day, items) {
     (item, index) => `  ${index + 1}. ${item.project ? `${item.project}: ` : ""}${item.text}`
   );
   const block = [`<!-- log:${day}:start -->`, ...lines, `<!-- log:${day}:end -->`];
-  let current = "";
+  let raw = "";
   try {
-    current = await fs.readFile(outputFile, "utf8");
+    raw = await fs.readFile(outputFile, "utf8");
   } catch {
   }
+  const hadBom = raw.charCodeAt(0) === 65279;
+  const current = hadBom ? raw.slice(1) : raw;
   const eol = current.includes("\r\n") ? "\r\n" : "\n";
   const fileLines = current ? current.split(/\r?\n/) : [];
   const startMarker = `<!-- log:${day}:start -->`;
   const endMarker = `<!-- log:${day}:end -->`;
-  const startIndex = fileLines.findIndex((line) => line.trim() === startMarker);
-  const endIndex = fileLines.findIndex((line) => line.trim() === endMarker);
+  const startIndex = fileLines.findLastIndex((line) => line.trim() === startMarker);
+  const endIndex = fileLines.findIndex(
+    (line, index) => index > startIndex && line.trim() === endMarker
+  );
   let nextLines;
   if (startIndex !== -1 && endIndex > startIndex) {
     nextLines = [...fileLines.slice(0, startIndex), ...block, ...fileLines.slice(endIndex + 1)];
-  } else if (startIndex !== -1 || endIndex !== -1) {
-    console.error(`[agent-tools log] Unpaired markers for ${day} in ${outputFile}; skipped.`);
-    return;
   } else {
     nextLines = insertDatedBlock(fileLines, day, block);
   }
-  const text = nextLines.join(eol).replace(/(\r?\n)*$/, eol);
+  const body = nextLines.join(eol).replace(/(\r?\n)*$/, eol);
+  const text = hadBom ? "\uFEFF" + body : body;
   await fs.mkdir(path.dirname(outputFile), { recursive: true });
   await writeFileAtomic(outputFile, text);
 }
+var ENTRY_MARKER_RE = /^<!--\s*(?:daily-)?log:\d{4}-\d{2}-\d{2}:(?:start|end)\b/;
+function datedSectionEnd(fileLines, dateIndex) {
+  let end = dateIndex + 1;
+  for (let i = dateIndex + 1; i < fileLines.length; i += 1) {
+    const line = fileLines[i];
+    if (!line.trim()) continue;
+    if (ENTRY_MARKER_RE.test(line.trim()) || /^\s/.test(line)) {
+      end = i + 1;
+      continue;
+    }
+    break;
+  }
+  return end;
+}
 function insertDatedBlock(fileLines, day, block) {
   const dateLineRe = /^\+ (\d{4}-\d{2}-\d{2})\s*$/;
   const dates = [];
@@ -1225,22 +1300,14 @@ function insertDatedBlock(fileLines, day, block) {
   }
   const existing = dates.find((entry) => entry.date === day);
   if (existing) {
-    const boundaryRe = /^(\+ \d{4}-\d{2}-\d{2}\s*$|#{1,6}\s)/;
-    let insertAt2 = fileLines.length;
-    for (let i = existing.index + 1; i < fileLines.length; i += 1) {
-      if (boundaryRe.test(fileLines[i])) {
-        insertAt2 = i;
-        break;
-      }
-    }
-    while (insertAt2 - 1 > existing.index && fileLines[insertAt2 - 1].trim() === "") insertAt2 -= 1;
+    const insertAt2 = datedSectionEnd(fileLines, existing.index);
     const trailing = fileLines.slice(insertAt2);
     const inserted = [...block];
     if (trailing.length > 0 && trailing[0].trim() !== "") inserted.push("");
     return [...fileLines.slice(0, insertAt2), ...inserted, ...trailing];
   }
   const ascending = dates.length < 2 || dates[0].date <= dates[dates.length - 1].date;
-  let insertAt = fileLines.length;
+  let insertAt = dates.length > 0 ? datedSectionEnd(fileLines, dates[dates.length - 1].index) : fileLines.length;
   for (const entry of dates) {
     if (ascending ? entry.date > day : entry.date < day) {
       insertAt = entry.index;
@@ -1528,7 +1595,19 @@ function getShellCommand(input) {
 async function writeFileAtomic(file, text) {
   const temp = `${file}.${process.pid}.tmp`;
   await fs.writeFile(temp, text, "utf8");
-  await fs.rename(temp, file);
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      await fs.rename(temp, file);
+      return;
+    } catch (error) {
+      if (attempt >= 5 || !["EPERM", "EACCES", "EBUSY"].includes(error?.code)) {
+        await fs.unlink(temp).catch(() => {
+        });
+        throw error;
+      }
+      await sleep(20 * (attempt + 1));
+    }
+  }
 }
 function excerptMultiline(text, limit) {
   const value = String(text || "").replace(/\r\n/g, "\n").trim();

package/docs/en/extras.md

@@ -78,14 +78,15 @@ npx -y @kairyou/agent-tools@latest log -a claude codex opencode
 ```markdown
 + 2026-08-03
 <!-- log:2026-08-03:start -->
-  1. project-a: traced the login timeout to sessions never renewing.
-  2. project-a: fixed the login timeout, added regression tests.
-  3. project-b: traced empty report exports to an inverted permission filter.
+  1. project-a: Found the cause of the login timeout: the renewal branch never updated the cache expiry, so the second request still read the old value. Patched session.ts and verified...
+  2. project-a: Fix is in, with 3 regression tests covering the renewal path; all passing.
+  3. project-b: Empty report exports came from an inverted permission filter, now corrected and confirmed working.
 <!-- log:2026-08-03:end -->
 ```
 
-One line per turn, written from the AI's own summary at the end of that turn; no
-cross-turn consolidation. Updates likewise rewrite only what sits between the markers.
+One line per turn, taken verbatim from the closing text of that turn's AI reply
+(truncated when long); no distilling, no cross-turn consolidation. Updates likewise
+rewrite only what sits between the markers.
 
 `detailed` output example (excerpt):
 

package/docs/zh-CN/extras.md

@@ -76,14 +76,14 @@ npx -y @kairyou/agent-tools@latest log -a claude codex opencode
 ```markdown
 + 2026-08-03
 <!-- log:2026-08-03:start -->
-  1. project-a: 排查登录超时, 定位到会话缓存没有续期.
-  2. project-a: 修复登录超时, 补充回归用例.
-  3. project-b: 定位报表导出为空的问题, 原因是权限过滤条件写反.
+  1. project-a: 已定位登录超时的原因: 会话缓存在续期分支上没有更新过期时间, 第二次请求拿到的还是旧值。已经在 session.ts 补上续期并本地验证通过, 接下来...
+  2. project-a: 修复完成, 新增 3 个回归用例覆盖续期路径, 全部通过。
+  3. project-b: 报表导出为空定位到权限过滤条件写反, 已修正并确认导出恢复正常。
 <!-- log:2026-08-03:end -->
 ```
 
-每轮一行, 内容是那一轮结束时 AI 自己写的总结, 不做跨轮归纳; 同样只重写标记之间
-的部分, 文件里的其他内容不会被碰.
+每轮一行, 直接摘录那一轮 AI 回复的收尾内容(过长会截断), 不做提炼也不跨轮归纳;
+同样只重写标记之间的部分, 文件里的其他内容不会被碰.
 
 `detailed` 输出示例(节选):
 

package/integrations/log/hook.mjs

@@ -13,12 +13,10 @@
 //             recorded, and an entry may override format/output/language
 //
 // State and diff snapshots live in ~/.agent-tools/cache/log/ and only the
-// current day is kept. Concurrent sessions share the day state without a lock,
-// last-writer-wins: a simultaneous write from another session can drop that
-// event's update, up to a whole turn with its outcome and file records.
-// Accepted as best effort — the log is generated data, never user content.
-// The opencode adapter serializes its own sends, so single-session events
-// there never race each other.
+// current day is kept. Sessions across agents share that state, so each run
+// takes ~/.agent-tools/cache/log/<date>.lock for the whole read-update-render
+// cycle; an event that cannot get the lock within seconds is dropped rather
+// than corrupting the day.
 
 import { spawnSync } from "node:child_process";
 import fs from "node:fs/promises";
@@ -67,22 +65,89 @@ async function main() {
   const snapshotsRoot = path.join(CACHE_ROOT, `${day}.snapshots`);
 
   await fs.mkdir(CACHE_ROOT, { recursive: true });
-  await cleanupCache(day);
 
-  const state = await loadState(statePath, day);
-  await handleEvent(state, hookInput, { now, snapshotsRoot, effective, scopeKey, scopePath: scope?.path || "" });
-  await writeFileAtomic(statePath, `${JSON.stringify(state, null, 2)}\n`);
-
-  if (effective.format === "detailed") {
-    const report = await renderDetailedReport(state, {
+  // Read, update and render under one lock: concurrent sessions across agents
+  // otherwise overwrite each other's turns, and on Windows their simultaneous
+  // renames fail outright with EPERM.
+  const release = await acquireLock(path.join(CACHE_ROOT, `${day}.lock`));
+  if (!release) {
+    await debugLog(`dropped ${eventName}: could not acquire ${day}.lock`);
+    return;
+  }
+  try {
+    await cleanupCache(day);
+    const state = await loadState(statePath, day);
+    await handleEvent(state, hookInput, {
+      now,
       snapshotsRoot,
-      language: effective.language,
+      effective,
       scopeKey,
+      scopePath: scope?.path || "",
     });
-    await fs.mkdir(effective.output, { recursive: true });
-    await writeFileAtomic(path.join(effective.output, `${day}.md`), report);
-  } else {
-    await updateDailyFile(effective.output, day, buildDailyItems(state, scopeKey));
+    await writeFileAtomic(statePath, `${JSON.stringify(state, null, 2)}\n`);
+
+    if (effective.format === "detailed") {
+      const report = await renderDetailedReport(state, {
+        snapshotsRoot,
+        language: effective.language,
+        scopeKey,
+      });
+      await fs.mkdir(effective.output, { recursive: true });
+      await writeFileAtomic(path.join(effective.output, `${day}.md`), report);
+    } else {
+      await updateDailyFile(effective.output, day, buildDailyItems(state, scopeKey));
+    }
+  } finally {
+    await release();
+  }
+}
+
+// ---- Cross-process lock. ----
+
+const LOCK_TIMEOUT_MS = 5_000;
+const LOCK_RETRY_MS = 25;
+// A hook run is short; a lock older than this belongs to a process that died.
+const LOCK_STALE_MS = 30_000;
+
+async function acquireLock(lockPath) {
+  const deadline = Date.now() + LOCK_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    try {
+      const handle = await fs.open(lockPath, "wx");
+      await handle.close();
+      return async () => {
+        try {
+          await fs.unlink(lockPath);
+        } catch {
+          // Already reclaimed as stale by another process.
+        }
+      };
+    } catch (error) {
+      if (error?.code !== "EEXIST") return null;
+      const age = await fs
+        .stat(lockPath)
+        .then(({ mtimeMs }) => Date.now() - mtimeMs)
+        .catch(() => 0);
+      if (age > LOCK_STALE_MS) {
+        await fs.unlink(lockPath).catch(() => {});
+        continue;
+      }
+      await sleep(LOCK_RETRY_MS);
+    }
+  }
+  return null;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function debugLog(message) {
+  if (process.env.AGENT_TOOLS_LOG_DEBUG !== "1") return;
+  try {
+    await fs.appendFile(path.join(CACHE_ROOT, "debug.log"), `${new Date().toISOString()} ${message}\n`);
+  } catch {
+    // Diagnostics must never break logging.
   }
 }
 
@@ -170,9 +235,16 @@ async function handleEvent(state, input, context) {
   session.last_time = timestamp;
 
   if (eventName === "UserPromptSubmit") {
-    // Always start a turn, even for greetings: reusing the previous turn would
-    // let this prompt's Stop overwrite the previous result summary. Trivial
-    // turns are filtered at render time instead.
+    const last = session.turns[session.turns.length - 1];
+    // A Stop that arrived before its prompt left a turn holding only an
+    // outcome; fill this prompt in rather than splitting one exchange in two.
+    if (last && !last.request_text && last.result_summary) {
+      last.request_text = excerptMultiline(getPromptText(input), 1600);
+      return;
+    }
+    // Otherwise always start a turn, even for greetings: reusing the previous
+    // turn would let this prompt's Stop overwrite the previous result summary.
+    // Trivial turns are filtered at render time instead.
     session.turns.push(
       createTurn(session, timestamp, getPromptText(input), resolveProjectLabel(input, context.scopePath), context.scopeKey)
     );
@@ -231,7 +303,7 @@ async function cleanupCache(day) {
   }
   await Promise.all(
     entries.map(async (entry) => {
-      const isState = entry.isFile() && /^\d{4}-\d{2}-\d{2}\.state\.json$/.test(entry.name);
+      const isState = entry.isFile() && /^\d{4}-\d{2}-\d{2}\.(state\.json|lock)$/.test(entry.name);
       const isSnapshots = entry.isDirectory() && /^\d{4}-\d{2}-\d{2}\.snapshots$/.test(entry.name);
       if ((!isState && !isSnapshots) || entry.name.startsWith(day)) return;
       try {
@@ -448,36 +520,63 @@ async function updateDailyFile(outputFile, day, items) {
   );
   const block = [`<!-- log:${day}:start -->`, ...lines, `<!-- log:${day}:end -->`];
 
-  let current = "";
+  let raw = "";
   try {
-    current = await fs.readFile(outputFile, "utf8");
+    raw = await fs.readFile(outputFile, "utf8");
   } catch {
     // First write creates the file.
   }
+  // Windows editors and PowerShell write a BOM; strip it for parsing and put
+  // it back on write so the file keeps the encoding its author chose.
+  const hadBom = raw.charCodeAt(0) === 0xfeff;
+  const current = hadBom ? raw.slice(1) : raw;
   const eol = current.includes("\r\n") ? "\r\n" : "\n";
   const fileLines = current ? current.split(/\r?\n/) : [];
 
   const startMarker = `<!-- log:${day}:start -->`;
   const endMarker = `<!-- log:${day}:end -->`;
-  const startIndex = fileLines.findIndex((line) => line.trim() === startMarker);
-  const endIndex = fileLines.findIndex((line) => line.trim() === endMarker);
+  // Pair with the LAST start: an earlier damaged start must not swallow
+  // whatever the user wrote between it and our block.
+  const startIndex = fileLines.findLastIndex((line) => line.trim() === startMarker);
+  const endIndex = fileLines.findIndex(
+    (line, index) => index > startIndex && line.trim() === endMarker
+  );
 
   let nextLines;
   if (startIndex !== -1 && endIndex > startIndex) {
     nextLines = [...fileLines.slice(0, startIndex), ...block, ...fileLines.slice(endIndex + 1)];
-  } else if (startIndex !== -1 || endIndex !== -1) {
-    // Unpaired markers: refuse to guess an edit range in an unattended run.
-    console.error(`[agent-tools log] Unpaired markers for ${day} in ${outputFile}; skipped.`);
-    return;
   } else {
+    // Also covers an unpaired marker: never guess its range, just add an
+    // intact block. Recording must not stop because one block got damaged;
+    // the stray marker stays visible for the user to clean up.
     nextLines = insertDatedBlock(fileLines, day, block);
   }
 
-  const text = nextLines.join(eol).replace(/(\r?\n)*$/, eol);
+  const body = nextLines.join(eol).replace(/(\r?\n)*$/, eol);
+  const text = hadBom ? "" + body : body;
   await fs.mkdir(path.dirname(outputFile), { recursive: true });
   await writeFileAtomic(outputFile, text);
 }
 
+// Where a dated entry stops: markers and indented items belong to it, anything
+// else below (headings, comment blocks, separators, todo lists) does not. Both
+// marker namespaces count, since at-daily-log may share this file.
+const ENTRY_MARKER_RE = /^<!--\s*(?:daily-)?log:\d{4}-\d{2}-\d{2}:(?:start|end)\b/;
+
+function datedSectionEnd(fileLines, dateIndex) {
+  let end = dateIndex + 1;
+  for (let i = dateIndex + 1; i < fileLines.length; i += 1) {
+    const line = fileLines[i];
+    if (!line.trim()) continue;
+    if (ENTRY_MARKER_RE.test(line.trim()) || /^\s/.test(line)) {
+      end = i + 1;
+      continue;
+    }
+    break;
+  }
+  return end;
+}
+
 function insertDatedBlock(fileLines, day, block) {
   const dateLineRe = /^\+ (\d{4}-\d{2}-\d{2})\s*$/;
   const dates = [];
@@ -488,18 +587,10 @@ function insertDatedBlock(fileLines, day, block) {
 
   const existing = dates.find((entry) => entry.date === day);
   if (existing) {
-    // Date line exists without markers (user-written): append the block below
-    // that date's lines. The dated section ends at the next date line or the
-    // next heading (notes and todo lists after the entries stay untouched).
-    const boundaryRe = /^(\+ \d{4}-\d{2}-\d{2}\s*$|#{1,6}\s)/;
-    let insertAt = fileLines.length;
-    for (let i = existing.index + 1; i < fileLines.length; i += 1) {
-      if (boundaryRe.test(fileLines[i])) {
-        insertAt = i;
-        break;
-      }
-    }
-    while (insertAt - 1 > existing.index && fileLines[insertAt - 1].trim() === "") insertAt -= 1;
+    // The date exists but carries no block of ours yet (user-written, or only
+    // at-daily-log's). Append below that date's own lines, never past the
+    // notes and todo lists that live further down the file.
+    const insertAt = datedSectionEnd(fileLines, existing.index);
     const trailing = fileLines.slice(insertAt);
     const inserted = [...block];
     if (trailing.length > 0 && trailing[0].trim() !== "") inserted.push("");
@@ -507,8 +598,12 @@ function insertDatedBlock(fileLines, day, block) {
   }
 
   // Insert a new date at its date-order position; ascending when ambiguous.
+  // Falling off the end means this date sorts last, so it goes at the end of
+  // the dated section rather than the end of the file: notes, comment blocks
+  // and todo lists kept below the log must stay below it.
   const ascending = dates.length < 2 || dates[0].date <= dates[dates.length - 1].date;
-  let insertAt = fileLines.length;
+  let insertAt =
+    dates.length > 0 ? datedSectionEnd(fileLines, dates[dates.length - 1].index) : fileLines.length;
   for (const entry of dates) {
     if (ascending ? entry.date > day : entry.date < day) {
       insertAt = entry.index;
@@ -862,10 +957,23 @@ function getShellCommand(input) {
 
 // ---- Small helpers. ----
 
+// Windows fails the rename with EPERM when another process holds the target
+// open, so a lost race retries briefly instead of dropping the write.
 async function writeFileAtomic(file, text) {
   const temp = `${file}.${process.pid}.tmp`;
   await fs.writeFile(temp, text, "utf8");
-  await fs.rename(temp, file);
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      await fs.rename(temp, file);
+      return;
+    } catch (error) {
+      if (attempt >= 5 || !["EPERM", "EACCES", "EBUSY"].includes(error?.code)) {
+        await fs.unlink(temp).catch(() => {});
+        throw error;
+      }
+      await sleep(20 * (attempt + 1));
+    }
+  }
 }
 
 function excerptMultiline(text, limit) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kairyou/agent-tools",
-  "version": "0.13.2",
+  "version": "0.13.4",
   "description": "Reusable Agent Skills, plus integrations (statusline, provider usage, vision) that install into Codex, Claude Code, and opencode.",
   "license": "MIT",
   "repository": {

package/skills/workflow/at-daily-log/SKILL.md

@@ -103,8 +103,9 @@ the current block and the regenerated one before writing, then replace only that
 date's block. If the date exists without markers, append a marked block below the
 user's lines instead of editing them. Do not duplicate the date. Insert a new date
 among the existing dated entries at its date-order position, inferring ascending or
-descending from the dates already present (ascending when that is ambiguous); content
-above or below the dated entries, such as notes or todo lists, stays where it is. On duplicate or
+descending from the dates already present (ascending when that is ambiguous). A date
+that sorts last goes right after the final dated entry, not at the end of the file:
+notes, comment blocks and todo lists kept below the log stay below it. On duplicate or
 unpaired markers, stop and propose the edit instead of writing. When neither Git nor
 the session log shows activity for the day, leave the file unchanged and say so; the
 user can add a manual entry themselves. Recording a range applies these rules to each day's block independently.