@nightlab-agent/date-check 0.1.3 → 0.1.5

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
       "name": "date-check",
       "source": "./",
       "description": "Checks the dates and times Claude Code writes into files against the real clock before the write lands.",
-      "version": "0.1.3",
+      "version": "0.1.5",
       "category": "productivity"
     }
   ],

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "date-check",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Checks the dates and times Claude Code writes into changelogs, logs, release notes and handoffs against the real clock before the write lands: a stamp in the future is refused with the real time, a stale one gets a note.",
   "homepage": "https://github.com/nightlab-agent/date-check#readme",
   "repository": "https://github.com/nightlab-agent/date-check",
@@ -39,6 +39,18 @@
       "title": "Notes on old stamps",
       "description": "Tell the agent when a stamp it adds is older than the limits above. Off: only stamps in the future are acted on.",
       "default": true
+    },
+    "promptClock": {
+      "type": "boolean",
+      "title": "The clock on every prompt",
+      "description": "Each prompt carries the local weekday, date, time and zone, and how long ago your previous message came, so Claude has the real time instead of a guess. Off: nothing is added to prompts.",
+      "default": true
+    },
+    "fill": {
+      "type": "boolean",
+      "title": "Fill placeholders",
+      "description": "Replace ⟦NOW⟧, ⟦DATE⟧, ⟦TIME⟧ and ⟦NOW-ISO⟧ in what Claude writes with the local time as the write lands, so Claude need not type the time. Off: placeholders stay as written.",
+      "default": true
     }
   }
 }

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.1.5 (2026-11-02)
+
+- A future date written as a release heading is refused even when the line the edit removes
+  named that date in a sentence ("Release planned for 2026-11-05" edited into
+  "## [1.0.0] - 2026-11-05"). Before, any new stamp whose text appeared anywhere in a removed
+  line was taken as carried over; now only a removed line's own stamp is.
+- A new file named for a past day is refused in each folder. Before, the "write it again"
+  memory was kept by the file name alone, so a refusal for `log/2025-06-12.md` let a
+  different new `journal/2025-06-12.md` through unasked.
+- A future stamp refused in a Write and written again by the shell with a relative path
+  (`echo ... >> notes.md`) now goes through as the refusal promises. Before, the retry was
+  matched by the path as typed, so the relative spelling was refused a second time. Both
+  checks now join a relative path to the session's directory and resolve `.` and `..`; on
+  Windows, `E:\p\notes.md` and a relative `notes.md` from `E:\p` are one file. A relative
+  path after a `cd` in the same command (in parentheses too) is the same file only after the
+  same `cd`. Network paths (`\\srv\share`) match in any letter case, as drive paths do.
+- A date moved out of a code block into the text is judged. Before, the line counted as one
+  the file already had, so a sample heading in a fence turned into a real heading dated in
+  the future went through.
+
+## 0.1.4 (2026-11-02)
+
+- Every prompt now carries the clock, so Claude knows the time instead of guessing it: the
+  local weekday, date, time, UTC offset and zone name, and how long ago your previous message
+  came (`it is Sunday 2026-11-01 05:58 local time, UTC-05:00 (America/New_York, EST). The
+  person's previous message came 3 h 12 min ago.`). A background task's notification or
+  another plugin's prompt gets the time but does not count as your previous message. The
+  "clock on every prompt" setting turns it off. Before, Claude Code gave Claude the date only,
+  with no time and no zone.
+- Claude can leave the time to the clock: `⟦NOW⟧` (date and time), `⟦DATE⟧`, `⟦TIME⟧` or
+  `⟦NOW-ISO⟧` in what it writes (a Write or an Edit and its file name, a shell command) is replaced with the
+  machine's local time as the call lands, and Claude is told what went in. One inside
+  backticks or a code block is kept as written. The prompt clock tells Claude about `⟦NOW⟧`, `⟦DATE⟧`
+  and `⟦TIME⟧`; the "fill placeholders" setting turns them off. The names follow a request in
+  MikalaiKryvusha/KAIF#170, which found that a clock in the prompt still left an agent writing
+  the minute after.
+
 ## 0.1.3 (2026-11-01)
 
 - A new Markdown or text file whose name carries a date more than a day before today

package/README.md

@@ -3,13 +3,21 @@
 A Claude Code mod that checks the dates and times Claude writes into your files
 against the real clock, before the write lands.
 
+Install with one line at the Claude Code prompt (scopes, the shell form and npm
+are under [Install](#install)):
+
+```
+/plugin install date-check --marketplace nightlab-agent/date-check
+```
+
 Agents guess the time. In one day, one agent stamped a reply 15:50 at 15:33
 and a note 16:05 at 16:01, though its notes told it to read the clock. People
 ask for Claude to be told the time
 ([anthropics/claude-code#32913](https://github.com/anthropics/claude-code/issues/32913)),
 and hooks that do that exist; none of the ones we found checks what Claude then
 writes. A mod (a plugin that changes what Claude Code does) can read the real
-clock; this one reads it at the moment Claude writes a stamp.
+clock; this one does both: it tells Claude the time with every prompt, and it
+reads the clock again at the moment Claude writes a stamp.
 
 ![Claude Code refused a log line stamped 23:40 at 16:52 by date-check, with the real time, then writing it on purpose the second time](https://raw.githubusercontent.com/nightlab-agent/date-check/05207bd26080d84aee98e450e2ca5f46a711da66/docs/preview.png)
 
@@ -25,8 +33,36 @@ Seen on 2026-11-01 at 02:11 EST, same terminal. Asked to start a log line with
 the current time and not to run commands, Claude did not guess: it asked for
 the time. Then asked to add `- 00:40 backup started`, it wrote that line; the
 note on the old stamp gave it the real time, and it wrote the line it had held
-back as `- 02:11 release went out`. A stamp Claude guesses on its own has not
-yet been seen on a screen.
+back as `- 02:11 release went out`. Claude has been seen guessing a time on its
+own (17:23, taken from a folder name, close enough to pass); date-check catching
+a wrong guess Claude made on its own has not yet been seen on a screen.
+
+![With date-check telling Claude the time on each prompt, Claude wrote a log line starting 05:54 at 05:54 without running a command, then named the day, the time zone and how long ago the previous message came](https://raw.githubusercontent.com/nightlab-agent/date-check/1f80c3f7744ebb8d6edab7dfb767d82b42cb2e5b/docs/preview-clock.png)
+
+Seen on 2026-11-01 at 05:54 EST, same terminal, with the clock on every
+prompt (new in 0.1.4). The same request as above, to
+start a log line with the current time and not run commands: this time Claude
+wrote `05:54 Release went out.` and said the time came from the session
+context. Asked what day and time it was, which zone, and how long ago the
+previous message came, it answered Sunday 1 November, 05:54, America/New_York
+on Eastern Standard Time, under a minute ago.
+
+- Each prompt carries one line Claude reads and you do not see: the local
+  weekday, date, time, UTC offset and zone name, and how long ago your
+  previous message came. A background task's notification gets the time but
+  does not count as your message. The "clock on every prompt" setting turns it off.
+- Claude can leave the time to the clock: `⟦NOW⟧` (date and time), `⟦DATE⟧`,
+  `⟦TIME⟧` or `⟦NOW-ISO⟧` in what it writes (a file and its name, an edit, a shell command)
+  is replaced with the machine's local time as the write lands, and Claude is
+  told what went in. One inside backticks or a code block is kept as written.
+  `⟦NOW⟧` has a space in it, so in a file name use `⟦DATE⟧`. The prompt clock
+  tells Claude about `⟦NOW⟧`, `⟦DATE⟧` and `⟦TIME⟧`; the "fill placeholders" setting turns them off.
+
+![Claude Code writing a log line, "06:14 The release went out.", and saying the time came from the clock](https://raw.githubusercontent.com/nightlab-agent/date-check/f2fc92e73b769c88db998d6d7078a25bbc5c5b70/docs/preview-fill.png)
+
+Seen in a preview on 2026-11-01: asked to start a log line with the exact time
+it is written, Claude wrote `06:14 The release went out.` and said the time
+was filled in from the clock as the file was written.
 
 - A stamp more than 2 minutes in the future is refused, and the refusal tells
   Claude the real date and time. If the future date is meant (a deadline, a
@@ -66,7 +102,7 @@ yet been seen on a screen.
 
 Settings (asked when you enable the plugin): minutes ahead allowed (2), minutes
 behind before a note (30), days behind before a note (1), notes on old stamps
-(on).
+(on), the clock on every prompt (on), fill placeholders (on).
 
 ![Claude Code refused a log line stamped 01:58 EST at 01:39 EST by date-check, with the real time and its UTC offset, and Claude asked whether the stamp was meant as EST or EDT](https://raw.githubusercontent.com/nightlab-agent/date-check/003f73177b78ef78659626e8cacbf06d1ab5753d/docs/preview-zone.png)
 
@@ -86,11 +122,14 @@ year old and offered to rename it to `daily-brief-2026-11-01.md`.
 
 ## What it writes
 
-Nothing. It reads the file a Write or an Edit is about to change, to judge only the new
-lines. Nothing leaves your machine through this mod: it makes no network calls.
+No files. It adds one line beside each prompt for Claude to read (the clock, above), and it
+reads the file a Write or an Edit is about to change, to judge only the new lines. Nothing leaves your machine through this mod: it makes no network calls.
 
 ## How it works
 
+- One hook, `prompt.submit`, which Claude Code runs as each prompt enters: it reads Claude
+  Code's clock and attaches the clock line to the prompt. A failure of the mod lets the
+  prompt through unchanged.
 - One hook, `tool.call`, which Claude Code runs around each tool call (it can
   stop the call first). On Write, Edit and Bash it finds the stamps the call adds, compares
   each with Claude Code's clock, and either refuses the call with the real time

package/hooks/register.tsx

@@ -1,5 +1,5 @@
 import type { EngineInterface, Register } from 'claude-code'
-import { dateOfFile, dayOf, judge, judgeName, LIMITS, newStamps } from './stamps'
+import { clockText, dateOfFile, dayOf, fillNow, gapText, judge, judgeName, LIMITS, newStamps, unfill } from './stamps'
 import type { Limits, Verdict } from './stamps'
 
 // date-check, the hooks module. Before a Write, an Edit, or a shell command that appends to
@@ -13,8 +13,13 @@ import type { Limits, Verdict } from './stamps'
 //   on 2026-11-01) is refused once with the real date, the same way; a later day is a plan.
 // Lines the file already had are never judged: only what this call adds. Only Markdown and
 // text files (isText): a date in code is data, not a stamp.
+// And before the agent writes anything: each prompt carries the clock (promptClock), the local
+// weekday, date, time and zone, and how long ago the person's previous message came, so the
+// agent has the real time instead of a guess.
+// And so the agent need not type a time at all: ⟦NOW⟧, ⟦DATE⟧, ⟦TIME⟧ and ⟦NOW-ISO⟧ in what a
+// call writes are filled from the clock as it lands (fill; fillNow says which spellings).
 
-type Options = { aheadMinutes?: unknown; staleMinutes?: unknown; staleDays?: unknown; staleNotes?: unknown }
+type Options = { aheadMinutes?: unknown; staleMinutes?: unknown; staleDays?: unknown; staleNotes?: unknown; promptClock?: unknown; fill?: unknown }
 type Call = { tool: string; file_path?: string; content?: string; old_string?: string; new_string?: string; replace_all?: boolean; command?: string }
 
 const num = (v: unknown, d: number) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : d)
@@ -53,6 +58,40 @@ export const shellWrite = (command: string): { file: string; text: string } | un
   return file === undefined ? undefined : { file, text: texts.join('\n') }
 }
 
+/** The directory changes in a shell command (`cd a`, `(pushd b`): after one, a relative path means no one place. */
+const dirMoves = (command: string) =>
+  [...command.matchAll(/(?:^|[;&|\n({]\s*)(cd|pushd)\s+([^;&|\n)}]*)/g)].map(m => `${m[1]} ${m[2]!.trim()}`)
+const movesDir = (command: string) => dirMoves(command).length > 0
+
+/** The file as one spelling, for remembering what was refused: a relative path joined to the
+ * session's directory, `.` and `..` resolved, one separator, a drive letter's path in lower
+ * case, a network path in lower case. A relative path after a `cd` in the same command is kept
+ * with the `cd`s before it, so it is one file only with the same moves; `~` and a failed reading
+ * stay as written. */
+async function placed($: EngineInterface, file: string, moves: string[] = []): Promise<string> {
+  if (!file || file.startsWith('~')) return file
+  const absolute = /^(?:[\\/]|[A-Za-z]:[\\/])/.test(file)
+  if (!absolute && moves.length) return `${moves.join('; ')}; ${file}`
+  let full = file
+  if (!absolute) {
+    try {
+      full = `${await $.session.cwd()}/${file}`
+    } catch {
+      return file
+    }
+  }
+  const drive = /^[A-Za-z]:/.exec(full)?.[0] ?? ''
+  const parts: string[] = []
+  for (const part of full.slice(drive.length).split(/[\\/]+/)) {
+    if (part === '' || part === '.') continue
+    if (part === '..') parts.pop()
+    else parts.push(part)
+  }
+  const network = /^[\\/]{2}/.test(full)
+  const one = `${network ? '//' : drive}/${parts.join('/')}`.replace(/^\/\/\//, '//')
+  return drive || network ? one.toLowerCase() : one
+}
+
 /** What a call changes in which file: the file's text before and after it. */
 async function change($: EngineInterface, x: Call): Promise<{ file: string; before: string; after: string; created?: boolean }> {
   const none = { file: '', before: '', after: '' }
@@ -75,7 +114,7 @@ async function change($: EngineInterface, x: Call): Promise<{ file: string; befo
     if (!w) return none
     // Whether the shell's file is new is only known when its path means one place: not under
     // `~` (the engine does not expand it) and not after a `cd` in the same command.
-    const sure = !w.file.startsWith('~') && !/(?:^|[;&|\n]\s*)(?:cd|pushd)\s/.test(x.command)
+    const sure = !w.file.startsWith('~') && !movesDir(x.command)
     return { file: w.file, before: '', after: w.text, created: sure && !(await $.fs.exists(w.file)) }
   }
   return none
@@ -97,6 +136,31 @@ export const staleNote = (vs: Verdict[]) =>
   `date-check: ${vs.map(quote).join('; ')} ${vs.length === 1 ? 'is' : 'are'} older than now (${vs[0]!.real}). ` +
   `If ${vs.length === 1 ? 'it records' : 'they record'} something past, leave ${vs.length === 1 ? 'it' : 'them'}; if ${vs.length === 1 ? 'it was' : 'they were'} meant as now, correct ${vs.length === 1 ? 'it' : 'them'}.`
 
+/** Prompts the person sent: typed, from Remote Control or Slack, or the SDK host's own turn. */
+const PERSON = new Set(['composer', 'bridge', 'slack-ping', 'sdk'])
+
+export const clockLine = (now: number, since?: number, fill = true) =>
+  `date-check: it is ${clockText(now)}.` +
+  (since === undefined ? '' : ` The person's previous message came ${gapText(now - since)} ago.`) +
+  (fill ? ' To record the moment a file is written, write ⟦NOW⟧ (date and time), ⟦DATE⟧ (also in a file name) or ⟦TIME⟧: the clock fills it in as the write lands.' : '')
+
+/** The call with its placeholders filled from the clock (the text it writes, and a Write's or Edit's file path), and which ones were. */
+const filledCall = (x: Call, now: number): { call: Call; filled: string[] } => {
+  const key = x.tool === 'Write' ? 'content' : x.tool === 'Edit' ? 'new_string' : 'command'
+  const call: Call = { ...x }
+  const filled = new Set<string>()
+  const v = x[key]
+  if (typeof v === 'string' && v.includes('⟦')) {
+    const f = fillNow(v, now, x.tool !== 'Bash')
+    if (f.filled.length) { call[key] = f.text; f.filled.forEach(t => filled.add(t)) }
+  }
+  if (x.tool !== 'Bash' && x.file_path?.includes('⟦')) {
+    const f = fillNow(x.file_path, now, false)
+    if (f.filled.length) { call.file_path = f.text; f.filled.forEach(t => filled.add(t)) }
+  }
+  return filled.size ? { call, filled: [...filled] } : { call: x, filled: [] }
+}
+
 export const register: Register = (on, options: Options = {}) => {
   const limits: Limits = {
     aheadMinutes: num(options.aheadMinutes, LIMITS.aheadMinutes),
@@ -104,16 +168,59 @@ export const register: Register = (on, options: Options = {}) => {
     staleDays: num(options.staleDays, LIMITS.staleDays),
   }
   const notes = options.staleNotes !== false
+  const fill = options.fill !== false
   // A future stamp refused once, by file and line: written again after that refusal, it is
   // meant. Each refusal and each call's start take a number in order, so a call that began
   // before the refusal (two calls at once) is refused too.
   const meant = new Map<string, number>()
   let order = 0
 
+  if (options.promptClock !== false) {
+    // The person's prompts in the order they entered, each with its clock reading once it
+    // came back. A prompt measures its gap from the latest earlier one: not from a later one
+    // whose reading came back first (two at once), and not from one dropped beneath.
+    const sent: { at?: number; dropped?: boolean }[] = []
+    on('prompt.submit', async ($, e, next) => {
+      const me = PERSON.has(e.origin?.kind) ? { at: undefined as number | undefined, dropped: false } : undefined
+      const earlier = sent.slice()
+      if (me) sent.push(me)
+      if (sent.length > 50) sent.splice(0, sent.length - 50)
+      let line: string | undefined
+      try {
+        const now = await $.clock.now()
+        let since: number | undefined
+        if (me) {
+          const before = earlier.filter(x => !x.dropped)
+          // One still waiting for its reading entered with this one: under a minute.
+          since = before.some(x => x.at === undefined) ? now : before.length ? Math.max(...before.map(x => x.at!)) : undefined
+          me.at = now
+        }
+        line = clockLine(now, since, fill)
+      } catch {
+        // A failure of this mod never stops the prompt; a prompt with no reading is no one's previous one.
+        if (me) me.dropped = true
+      }
+      const done = await next(line ? { ...e, context: [...(e.context ?? []), line] } : e)
+      if (me && done.drop !== undefined) me.dropped = true
+      return done
+    })
+  }
+
   on('tool.call', async ($, e, next) => {
-    const x = e as unknown as Call
+    let x = e as unknown as Call
     if (x.tool !== 'Write' && x.tool !== 'Edit' && x.tool !== 'Bash') return next(e)
     const began = ++order
+    let filled: string[] = []
+    if (fill) {
+      try {
+        const f = filledCall(x, await $.clock.now())
+        x = f.call
+        filled = f.filled
+      } catch {
+        // No reading: the call goes on as written.
+      }
+    }
+    const sent = (filled.length ? { ...e, ...x } : e) as typeof e
     let verdicts: Verdict[] = []
     let name: ReturnType<typeof judgeName>
     let file = ''
@@ -132,11 +239,14 @@ export const register: Register = (on, options: Options = {}) => {
       verdicts = []
       name = undefined
     }
-    const key = (v: Verdict) => `${file}\n${v.stamp.line}`
+    // Keyed by the line as the agent wrote it, so a retry with the same placeholder a minute later is the same line.
+    const at = await placed($, file, x.tool === 'Bash' && typeof x.command === 'string' ? dirMoves(x.command) : [])
+    const key = (v: Verdict) => `${at}\n${unfill(v.stamp.line, filled)}`
     const future = verdicts.filter(v => v.kind === 'future')
     const fresh = future.filter(v => !((meant.get(key(v)) ?? Infinity) < began))
-    // By the file's name alone, so a retry spelled another way (relative, absolute) is the same file.
-    const nameKey = `(name)\n${file.split(/[/\\]/).pop()}`
+    // By the placed path, so a retry spelled another way (relative, absolute) is the same file
+    // and a file of the same name in another folder is not.
+    const nameKey = `(name)\n${at}`
     const freshName = name && !((meant.get(nameKey) ?? Infinity) < began) ? name : undefined
     if (fresh.length || freshName) {
       // The first refusal's number is kept: an older call refused late must not move it past a retry.
@@ -145,9 +255,10 @@ export const register: Register = (on, options: Options = {}) => {
       if (freshName) mark(nameKey)
       return { deny: [...(freshName ? [nameRefusal(file, freshName)] : []), ...(fresh.length ? [refusal(fresh)] : [])].join('\n') }
     }
-    const done = await next(e)
+    const done = await next(sent)
     if (done.deny !== undefined || done.isError) return done
     const said = [
+      ...(filled.length ? [`date-check: filled from the clock: ${filled.join(', ')}.`] : []),
       ...(name ? [`date-check: kept the date ${name.date} in the new file's name as written the second time.`] : []),
       ...(future.length ? [`date-check: kept ${future.map(v => `"${v.stamp.text}"`).join(', ')} as written the second time (a date in the future on purpose).`] : []),
       ...(notes && verdicts.some(v => v.kind === 'stale') ? [staleNote(verdicts.filter(v => v.kind === 'stale'))] : []),

package/hooks/stamps.ts

@@ -106,27 +106,64 @@ const lineStamp = (line: string, fileDate?: string): Stamp | undefined => {
   return undefined
 }
 
+/** For each line, whether it sits in a code fence that is closed (a fence left open to the end is not counted). */
+const closedFences = (lines: string[]): boolean[] => {
+  const inside: boolean[] = []
+  let open = -1
+  for (const [i, l] of lines.entries()) {
+    if (/^\s*(```|~~~)/.test(l)) open = open < 0 ? i : -1
+    inside.push(open >= 0 || (/^\s*(```|~~~)/.test(l) && open < 0))
+  }
+  if (open >= 0) for (let i = open; i < lines.length; i++) inside[i] = false
+  return inside
+}
+
 /**
  * The stamps a change adds: the stamps on lines of `after` that `before` did not have, read
  * in the whole of `after` (so a line inside a code block the file already had is seen as
  * code). A stamp whose text was on a line the change removes is carried over, not added.
  */
 export const newStamps = (before: string, after: string, fileDate?: string): Stamp[] => {
+  // A line is the same line only in the same place: inside a closed code fence or out of one,
+  // so a sample moved out of a fence into the text is a new line, and closing a fence left open
+  // does not make every line under it new.
   const had = new Map<string, number>()
-  for (const l of before.split(/\r?\n/)) had.set(l, (had.get(l) ?? 0) + 1)
+  const beforeIn = closedFences(before.split(/\r?\n/))
+  before.split(/\r?\n/).forEach((l, i) => {
+    const k = `${beforeIn[i] ? '`' : ' '}${l}`
+    had.set(k, (had.get(k) ?? 0) + 1)
+  })
   const out: Stamp[] = []
+  const kept: string[] = []
+  const lines = after.split(/\r?\n/)
+  const afterIn = closedFences(lines)
   let fence = false
-  for (const line of after.split(/\r?\n/)) {
-    const n = had.get(line) ?? 0
+  for (const [i, line] of lines.entries()) {
+    const isFence = /^\s*(```|~~~)/.test(line)
+    if (isFence) fence = !fence
+    const k = `${afterIn[i] ? '`' : ' '}${line}`
+    const n = had.get(k) ?? 0
     const isNew = n === 0
-    if (!isNew) had.set(line, n - 1)
-    if (/^\s*(```|~~~)/.test(line)) { fence = !fence; continue }
-    if (fence || !isNew || indentedCode(line)) continue
+    if (!isNew) had.set(k, n - 1)
+    if (isFence) continue
+    if (fence || indentedCode(line)) continue
     const s = lineStamp(line, fileDate)
-    if (s) out.push(s)
+    if (s) (isNew ? out.push(s) : kept.push(s.text))
+  }
+  // Only a stamp the old text itself had carries over, read in the old text's own context (a
+  // date named in a removed sentence or code block is not one): the old text's stamps less those
+  // still on its unchanged lines.
+  const carried = new Map<string, number>()
+  if (before) {
+    for (const s of newStamps('', before, fileDate)) carried.set(s.text, (carried.get(s.text) ?? 0) + 1)
+    for (const s of kept) carried.set(s, (carried.get(s) ?? 0) - 1)
   }
-  const removed = [...had.entries()].filter(([, n]) => n > 0).map(([l]) => l).join('\n')
-  return out.filter(s => !removed.includes(s.text))
+  return out.filter(s => {
+    const n = carried.get(s.text) ?? 0
+    if (n <= 0) return true
+    carried.set(s.text, n - 1)
+    return false
+  })
 }
 
 /** The stamps in some lines of text. */
@@ -164,6 +201,76 @@ export const nowText = (ms: number) => {
   return `${dayOf(ms)} ${pad(d.getHours())}:${pad(d.getMinutes())} local time, ${zone}`
 }
 
+/**
+ * Placeholders the agent writes instead of typing a time, filled from the clock as the call
+ * lands: `⟦NOW⟧` 2026-11-01 06:20, `⟦DATE⟧` 2026-11-01, `⟦TIME⟧` 06:20, `⟦NOW-ISO⟧`
+ * 2026-11-01T06:20:41-05:00, all local. One in code is kept as written (a README that shows
+ * the placeholder): a code span, a ``` or ~~~ fence (closed by the same mark, as long or
+ * longer), and, in a file (`indented`), an indented code line, as the judge reads code.
+ * Exactly these spellings: `⟦now⟧`, `[NOW]` and `⟦NOW ⟧` are text. ⟦NOW⟧ has a space in
+ * it: in a file name or an unquoted shell word, ⟦DATE⟧ is the one to use.
+ */
+export const fillNow = (text: string, ms: number, indented = true): { text: string; filled: string[] } => {
+  const d = new Date(ms)
+  const o = -d.getTimezoneOffset()
+  const time = `${pad(d.getHours())}:${pad(d.getMinutes())}`
+  const iso = `${dayOf(ms)}T${time}:${pad(d.getSeconds())}${o < 0 ? '-' : '+'}${pad(Math.floor(Math.abs(o) / 60))}:${pad(Math.abs(o) % 60)}`
+  const value: Record<string, string> = { 'NOW-ISO': iso, NOW: `${dayOf(ms)} ${time}`, DATE: dayOf(ms), TIME: time }
+  const filled = new Set<string>()
+  let fence: string | undefined
+  const lines = text.split('\n').map(line => {
+    const mark = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1]
+    if (fence !== undefined) {
+      if (mark && mark[0] === fence[0] && mark.length >= fence.length && /^ {0,3}[`~]+\s*$/.test(line)) fence = undefined
+      return line
+    }
+    if (mark && !(mark[0] === '`' && line.slice(line.indexOf(mark) + mark.length).includes('`'))) { fence = mark; return line }
+    if (indented && indentedCode(line)) return line
+    return line.replace(/(?<!`)(`+)(?!`)[^]*?(?<!`)\1(?!`)|⟦(NOW-ISO|NOW|DATE|TIME)⟧/g, (m, code: string | undefined, tok: string | undefined) => {
+      if (code !== undefined || !tok) return m
+      filled.add(`⟦${tok}⟧ ${value[tok]}`)
+      return value[tok]!
+    })
+  })
+  return { text: lines.join('\n'), filled: [...filled] }
+}
+
+/** A line as written before filling: each filled value back to its placeholder, longest first. */
+export const unfill = (line: string, filled: string[]) =>
+  filled.map(f => [f.slice(0, f.indexOf('⟧') + 1), f.slice(f.indexOf('⟧') + 2)] as const)
+    .sort((x, y) => y[1].length - x[1].length)
+    .reduce((l, [tok, v]) => l.split(v).join(tok), line)
+
+const DAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']
+/** The zone's name where the runtime knows it (`America/New_York, EST`); '' where it does not. */
+const zoneName = (ms: number) => {
+  try {
+    const iana = Intl.DateTimeFormat().resolvedOptions().timeZone
+    const short = new Intl.DateTimeFormat('en-US', { timeZoneName: 'short' }).formatToParts(new Date(ms)).find(p => p.type === 'timeZoneName')?.value
+    return [...new Set([iana, short && !/^GMT[+-]/.test(short) ? short : ''].filter(Boolean))].join(', ')
+  } catch {
+    return ''
+  }
+}
+/**
+ * The clock a prompt carries: weekday, date, local time and offset, and the zone's name:
+ * `Sunday 2026-11-01 05:58 local time, UTC-05:00 (America/New_York, EST)`.
+ */
+export const clockText = (ms: number) => {
+  const name = zoneName(ms)
+  return `${DAYS[new Date(ms).getDay()]} ${nowText(ms)}${name ? ` (${name})` : ''}`
+}
+/** A span of time as a person says it: `under a minute`, `12 min`, `3 h 5 min`, `2 days 4 h`. */
+export const gapText = (ms: number) => {
+  const m = Math.floor(Math.max(0, ms) / 60000)
+  if (m < 1) return 'under a minute'
+  if (m < 60) return `${m} min`
+  const h = Math.floor(m / 60)
+  if (h < 24) return m % 60 ? `${h} h ${m % 60} min` : `${h} h`
+  const d = Math.floor(h / 24)
+  return `${d} day${d === 1 ? '' : 's'}${h % 24 ? ` ${h % 24} h` : ''}`
+}
+
 /** The local zone's UTC offset in minutes at a moment (New York in winter: -300). */
 export type ZoneAt = (ms: number) => number
 const localZone: ZoneAt = ms => -new Date(ms).getTimezoneOffset()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nightlab-agent/date-check",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Claude Code mod: checks the dates and times Claude Code writes into changelogs, logs, release notes and handoffs against the real clock before the write lands; a stamp in the future is refused with the real time.",
   "keywords": [
     "claude-code",