@hncode/hncode 0.4.1 → 0.5.0

package/src/rollout.js

@@ -0,0 +1,151 @@
+// Session replay (/replay) — play a recorded conversation back, one step at a time.
+//
+// Why this exists: a session file records WHAT happened but not how long it took or
+// in what ORDER relative to the tools, and reading the raw JSON to understand a run
+// is unpleasant. More importantly, when something went wrong two hours ago, the
+// question is "what did the model see when it made that bad call" — and the answer is
+// the transcript AS IT STOOD at that step, which is not the same as the final
+// transcript.
+//
+// So the replay is a step index over the session's messages, with the state at each
+// step reconstructable. It is deliberately read-only: nothing here writes a file or
+// resumes execution. A replay that could act would be a footgun.
+//
+// Steps are the unit the user cares about — a user message, an assistant reply, a
+// tool call, a tool result — not raw JSON entries, because one assistant message can
+// carry several tool calls and the interesting question is "which tool ran, in what
+// order".
+
+/** The kinds of step a replay can stop on, in the order they can occur. */
+export const STEP_KINDS = ['user', 'assistant', 'thinking', 'tool', 'system'];
+
+/**
+ * Turn a session's messages into replay steps.
+ *
+ * Returns an array of
+ * `{ index, kind, role, label, text, toolName, args, at }`. `at` is only present
+ * when the recording kept a timestamp, which older sessions do not.
+ */
+export function buildSteps(messages) {
+  const list = Array.isArray(messages) ? messages : [];
+  const steps = [];
+  for (const m of list) {
+    if (!m || typeof m !== 'object') continue;
+    const role = String(m.role || '');
+    const at = m.at || m.timestamp || null;
+    if (role === 'assistant') {
+      // Split one assistant message into its reasoning, its prose, and each tool
+      // call: the tool calls are the steps a debugging reader wants on their own.
+      const thinking = typeof m.reasoning === 'string' ? m.reasoning : '';
+      if (thinking.trim()) {
+        steps.push({ kind: 'thinking', role, label: 'thinking', text: thinking, at });
+      }
+      const text = typeof m.content === 'string' ? m.content : '';
+      if (text.trim()) {
+        steps.push({ kind: 'assistant', role, label: 'reply', text, at });
+      }
+      const calls = Array.isArray(m.toolCalls) ? m.toolCalls : [];
+      for (const c of calls) {
+        const name = (c && (c.name || (c.function && c.function.name))) || 'tool';
+        steps.push({
+          kind: 'tool', role, label: name, toolName: name,
+          text: '', args: c && (c.args || c.arguments || (c.function && c.function.arguments)) || null,
+          at,
+        });
+      }
+      if (!thinking.trim() && !text.trim() && !calls.length) {
+        steps.push({ kind: 'assistant', role, label: 'reply', text: '', at });
+      }
+      continue;
+    }
+    if (role === 'tool') {
+      const name = m.toolName || m.name || 'tool';
+      steps.push({ kind: 'tool', role, label: `${name} result`, toolName: name, text: typeof m.content === 'string' ? m.content : '', at });
+      continue;
+    }
+    if (role === 'user' || role === 'system') {
+      steps.push({ kind: role, role, label: role === 'user' ? 'prompt' : 'system', text: typeof m.content === 'string' ? m.content : '', at });
+      continue;
+    }
+    // Anything else (a plugin-injected role, a future one) is shown as itself rather
+    // than dropped: a replay that silently omits steps is worse than an ugly label.
+    steps.push({ kind: 'other', role, label: role || 'entry', text: typeof m.content === 'string' ? m.content : '', at });
+  }
+  return steps.map((s, i) => ({ ...s, index: i }));
+}
+
+/**
+ * The state at step `i`: which prompt is being answered and what has been seen.
+ *
+ * This is the "as it stood" view — the whole reason to replay rather than scroll.
+ */
+export function stateAtStep(steps, i) {
+  const list = Array.isArray(steps) ? steps : [];
+  const at = Math.max(0, Math.min(list.length - 1, i | 0));
+  let lastPrompt = '';
+  let tools = 0;
+  for (let n = 0; n <= at; n++) {
+    const s = list[n];
+    if (!s) continue;
+    if (s.kind === 'user') lastPrompt = s.text;
+    if (s.kind === 'tool') tools++;
+  }
+  return {
+    index: at,
+    lastPrompt,
+    tools,
+    // The turn number the step belongs to, counting prompts: 1-based for display.
+    turn: list.slice(0, at + 1).filter((s) => s && s.kind === 'user').length || 1,
+  };
+}
+
+/** A one-line summary per step, for the scrubber list. */
+export function stepLine(step, width = 72) {
+  if (!step) return '';
+  const t = String(step.text || '').replace(/\s+/g, ' ').trim();
+  const arg = step.args == null ? ''
+    : (typeof step.args === 'string' ? step.args : JSON.stringify(step.args)).replace(/\s+/g, ' ');
+  const body = t || arg;
+  const cut = body.length > width ? body.slice(0, width - 1) + '…' : body;
+  return cut;
+}
+
+/**
+ * The frame for one step: a header plus the step's body, wrapped.
+ *
+ * Wrapping is done here rather than by the caller so a replay view and a test agree
+ * on the exact rows.
+ */
+export function renderStep(steps, i, opts = {}) {
+  const list = Array.isArray(steps) ? steps : [];
+  if (!list.length) return ['(this session has no steps to replay)'];
+  const at = Math.max(0, Math.min(list.length - 1, i | 0));
+  const s = list[at];
+  const st = stateAtStep(list, at);
+  const width = Math.max(20, opts.width || 76);
+  const out = [];
+  out.push(`step ${at + 1}/${list.length}  turn ${st.turn}  ${s.kind}${s.toolName ? ' ' + s.toolName : ''}`);
+  if (st.lastPrompt) out.push(`  answering: ${st.lastPrompt.split('\n')[0].slice(0, width - 12)}`);
+  if (s.at) out.push(`  at: ${s.at}`);
+  out.push('');
+  const body = [String(s.text || ''), s.args == null ? '' : (typeof s.args === 'string' ? s.args : JSON.stringify(s.args, null, 2))]
+    .filter((x) => x && String(x).trim()).join('\n');
+  const rows = body ? String(body).split('\n') : ['(no content)'];
+  for (const r of rows) {
+    if (r.length <= width) { out.push(r); continue; }
+    for (let k = 0; k < r.length; k += width) out.push(r.slice(k, k + width));
+  }
+  return out;
+}
+
+/** Totals for the header: how many steps of each kind, and how many tools ran. */
+export function replaySummary(steps) {
+  const list = Array.isArray(steps) ? steps : [];
+  const counts = {};
+  for (const s of list) counts[s.kind] = (counts[s.kind] || 0) + 1;
+  const calls = list.filter((s) => s.kind === 'tool' && s.role === 'assistant').length;
+  const results = list.filter((s) => s.kind === 'tool' && s.role === 'tool').length;
+  return { total: list.length, counts, calls, results };
+}
+
+export default { buildSteps, stateAtStep, stepLine, renderStep, replaySummary, STEP_KINDS };

package/src/row-cache.js

@@ -0,0 +1,143 @@
+// A shared, bounded cache of rendered transcript rows.
+//
+// WHY THIS EXISTS
+// ---------------
+// Wrapping and markdown-rendering a message is the expensive half of every frame, and the
+// result depends only on (message text, width, colours) — so it is cacheable. The TUI
+// already cached it, but on the message object itself, which makes the cache a property of
+// the TRANSCRIPT rather than of the renderer:
+//
+//   * It was dropped by position, not by size. `CACHE_KEEP` counted messages from the
+//     tail, so a 4000-message session threw away the caches of the 3700 oldest messages
+//     while keeping the caches of 300 tiny ones — the window tracked message COUNT, not
+//     memory. Scrolling back into a long session re-rendered from scratch every time.
+//   * It could not survive a session switch, because it lived on messages that
+//     `reconstructChat` throws away and rebuilds from the log. Every `--continue` and
+//     every `/sessions` resume started with a cold cache, re-wrapping the whole
+//     transcript before the first frame.
+//   * It had two independent mechanisms — `m._cache` for the row list, `m._mdCache` for
+//     the markdown blocks — with separate lifetimes and no bound between them.
+//
+// A `Map` keyed by a string, with entries ordered by use, fixes all three: the bound is
+// real, the key survives any rebuild of the transcript, and both caches share one budget.
+//
+// THE KEY IS THE WHOLE POINT
+// --------------------------
+// A key that omitted a component of the layout would serve a row rendered for a different
+// width or colour — which is not a stale cache, it is a MISDRAWN frame. So the key spells
+// out everything the render depends on, and `makeRowKey` is the single place that decides
+// what "the same" means. `evictIfStale` is the second half of the same contract: a streamed
+// message's text grows every frame, so an entry whose text no longer matches is not a
+// reuse, and the cache has to notice rather than serve it.
+
+/** How many messages keep their rows. Chosen by measurement, not by feel: the rows for a
+ *  typical assistant message are a few hundred bytes each, so 1500 covers a long session's
+ *  visible history while staying in the low megabytes. */
+export const ROW_CACHE_LIMIT = 1500;
+
+/**
+ * A cache key that identifies a rendered message.
+ *
+ * Every input the render reads goes in, so "the same key" means "the same rows":
+ *   `id`  a stable identity for the message. Index-based ids break the moment a message
+ *         is inserted or removed, which is exactly what compaction and /undo do.
+ *   `text`  the content. Compared by VALUE, not by reference: a streamed message's
+ *         `text` is replaced on every delta, and a reference check would miss every
+ *         reuse after the first frame.
+ *   `w`  the wrap width, `fg`/`codeFg` the colours, `expanded` the plugin-log toggle,
+ *   `raw` the raw-mode flag, `pending`/`failed` the live-state flags, and `spin` the
+ *   spinner key.
+ */
+export function makeRowKey(parts) {
+  return [
+    parts.id,
+    parts.text == null ? '' : parts.text,
+    parts.w,
+    parts.fg,
+    parts.codeFg,
+    parts.expanded ? 1 : 0,
+    parts.raw ? 1 : 0,
+    parts.pending ? 1 : 0,
+    parts.failed ? 1 : 0,
+    parts.spin,
+  ].join('\x1f');
+}
+
+/**
+ * The shared store.
+ *
+ * A single `Map` with insertion order: `Map` iterates in insertion order and `set` on an
+ * existing key does NOT move it, so "touch on every read" has to be an explicit
+ * delete-then-set. That is what makes it an LRU rather than a FIFO — and the difference
+ * matters here, because the entries worth keeping are the ones being read, not the ones
+ * written most recently.
+ */
+const store = new Map();
+
+/** Hits and misses, so a caller can tell "the cache is not helping" from "there is
+ *  nothing to cache" without instrumenting the renderer. */
+const stats = { hits: 0, misses: 0, evictions: 0 };
+
+export function cacheStats() {
+  return { ...stats, size: store.size };
+}
+
+/** For tests: a clean slate. */
+export function resetRowCache() {
+  store.clear();
+  stats.hits = 0;
+  stats.misses = 0;
+  stats.evictions = 0;
+}
+
+/**
+ * Look up `key`, marking it as recently used.
+ *
+ * @returns the cached value, or undefined on a miss. Callers treat `undefined` as "render
+ *   it" — a cache that cannot say "no" is not a cache.
+ */
+export function rowCacheGet(key) {
+  if (!store.has(key)) { stats.misses++; return undefined; }
+  const v = store.get(key);
+  // Touch: re-insert so this key moves to the young end of the Map's iteration order.
+  store.delete(key);
+  store.set(key, v);
+  stats.hits++;
+  return v;
+}
+
+/**
+ * Store `value` under `key` and enforce the bound.
+ *
+ * Eviction is oldest-first, and it is done HERE rather than by the caller counting
+ * messages: the caller cannot know what the entries cost, and a message-count window
+ * keeps a lot of large messages while discarding a lot of small ones.
+ */
+export function rowCacheSet(key, value) {
+  // Re-inserting an existing key would leave the old entry in place, so drop it first —
+  // otherwise the bound could be evictions short of what it looks like.
+  store.delete(key);
+  store.set(key, value);
+  while (store.size > ROW_CACHE_LIMIT) {
+    // Map iteration is insertion order, so the first key is the least recently used.
+    const oldest = store.keys().next();
+    if (oldest.done) break;
+    store.delete(oldest.value);
+    stats.evictions++;
+  }
+  return value;
+}
+
+/**
+ * Is `cached` still valid for `key`'s message?
+ *
+ * A separate question from `rowCacheGet`, because a message can change without its key
+ * changing: a streamed reply's text is the key's own `text` component, so its key DOES
+ * change — but the row COUNT memo does not carry the text, and that one has to be asked
+ * whether the content moved. Kept as a function so the check is named at the call site
+ * rather than being an open-coded `===` someone later widens by accident.
+ */
+export function evictIfStale(entry, key) {
+  if (!entry) return true;
+  return entry.key !== key;
+}

package/src/schedule.js

@@ -0,0 +1,294 @@
+// Scheduled prompts (/schedule) — a cron-like entry that queues a prompt on a
+// running session. Mirrors cline's `schedule` command: a recurring prompt for work
+// that happens on a clock rather than because the user asked.
+//
+// The cron parser is written here rather than pulled in as a dependency, because the
+// whole point of the feature is one line of config and a timer — five fields of
+// numbers and ranges do not justify a package. It supports exactly the cron subset
+// that is useful for a coding session and REJECTS anything it does not understand
+// instead of guessing: a schedule that silently never fires is worse than one that
+// fails loudly at parse time.
+//
+// Supported syntax, per field:
+//   *      any value
+//   5       that value
+//   1,3,5   a list
+//   1-5     a range
+//   */15    a step over the field's range
+//   1-30/10 a step over a range
+//
+// Field order and ranges are the standard five-field form:
+//   minute 0-59, hour 0-23, day-of-month 1-31, month 1-12, day-of-week 0-6 (0 = Sun)
+//
+// Day-of-month and day-of-week are combined with OR when BOTH are restricted, which
+// is what cron does (and is the standard source of confusion — a `0 9 1 * 1` entry
+// fires on the 1st OR on Mondays, not only on Mondays that are the 1st). That
+// behaviour is implemented, and stated in the help text rather than left as folklore.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const FIELDS = [
+  { name: 'minute', min: 0, max: 59 },
+  { name: 'hour', min: 0, max: 23 },
+  { name: 'dom', min: 1, max: 31 },
+  { name: 'month', min: 1, max: 12 },
+  { name: 'dow', min: 0, max: 6 },
+];
+
+/** Compile one field into a Set of allowed numbers. Throws on anything invalid. */
+function parseField(spec, field) {
+  const out = new Set();
+  for (const part of String(spec).split(',')) {
+    const piece = part.trim();
+    if (!piece) throw new Error(`empty ${field.name} entry`);
+    // `base/step` — the base may be `*`, a single value or a range.
+    const [base, stepRaw] = piece.split('/');
+    let step = 1;
+    if (stepRaw !== undefined) {
+      step = Number(stepRaw);
+      if (!Number.isInteger(step) || step < 1) throw new Error(`bad step "${stepRaw}" in ${field.name}`);
+    }
+    let lo;
+    let hi;
+    if (base === '*') { lo = field.min; hi = field.max; }
+    else if (base.includes('-')) {
+      const [a, b] = base.split('-');
+      lo = Number(a);
+      hi = Number(b);
+      if (!Number.isInteger(lo) || !Number.isInteger(hi)) throw new Error(`bad range "${base}" in ${field.name}`);
+    } else {
+      lo = Number(base);
+      hi = lo;
+      if (!Number.isInteger(lo)) throw new Error(`bad value "${base}" in ${field.name}`);
+    }
+    // A DOW of 7 means Sunday in several cron implementations. Folding it to 0 must
+    // happen BEFORE the range tests: folding `hi` first made the single value `7`
+    // satisfy `hi < lo` (0 < 7) and be rejected as a backwards range.
+    const isDow = field.name === 'dow';
+    const foldDow = (v) => (isDow && v === 7 ? 0 : v);
+    if (isDow) {
+      // Validate against the ALLOWED range (0-7) before folding, so `8` is still
+      // rejected while `7` is accepted.
+      if (lo < field.min || lo > field.max + 1 || hi > field.max + 1) {
+        throw new Error(`${field.name} "${piece}" is out of range ${field.min}-${field.max}`);
+      }
+    } else if (lo < field.min || hi > field.max) {
+      throw new Error(`${field.name} "${piece}" is out of range ${field.min}-${field.max}`);
+    }
+    if (hi < lo) throw new Error(`${field.name} range "${base}" runs backwards`);
+    // A range ENDING at 7 covers Sunday, so the fold cannot just remap both ends to
+    // 0 — `0-7` would become `0-0` and lose six days. Iterate the original range and
+    // fold each VALUE instead.
+    for (let v = lo; v <= hi; v += step) out.add(foldDow(v));
+  }
+  return out;
+}
+
+/**
+ * Compile a cron expression. Returns a matcher with
+ * `{ fields, matches(date), describe(), restricted }`, or throws with a message
+ * naming the field that is wrong.
+ */
+export function parseCron(expr) {
+  const parts = String(expr == null ? '' : expr).trim().split(/\s+/).filter(Boolean);
+  if (parts.length !== 5) {
+    throw new Error(`expected 5 fields (minute hour day-of-month month day-of-week), got ${parts.length}`);
+  }
+  const fields = {};
+  for (let i = 0; i < FIELDS.length; i++) {
+    fields[FIELDS[i].name] = parseField(parts[i], FIELDS[i]);
+  }
+  // Which fields were written as `*`: the OR rule for dom/dow only applies when BOTH
+  // are restricted, so the distinction has to survive parsing.
+  const restricted = {
+    dom: parts[2].trim() !== '*',
+    dow: parts[4].trim() !== '*',
+  };
+  return {
+    fields,
+    restricted,
+    expr: parts.join(' '),
+    matches(date) {
+      const d = date || new Date();
+      if (!fields.minute.has(d.getMinutes())) return false;
+      if (!fields.hour.has(d.getHours())) return false;
+      if (!fields.month.has(d.getMonth() + 1)) return false;
+      const domHit = fields.dom.has(d.getDate());
+      const dowHit = fields.dow.has(d.getDay());
+      // Standard cron: when both day fields are restricted, either may match.
+      if (restricted.dom && restricted.dow) return domHit || dowHit;
+      if (restricted.dom) return domHit;
+      if (restricted.dow) return dowHit;
+      return true;
+    },
+  };
+}
+
+/** `0 9 * * 1-5` -> `weekdays at 09:00`. A readable gloss when the shape is known. */
+export function describeCron(expr) {
+  const text = String(expr || '').trim();
+  const named = {
+    '0 9 * * 1-5': 'weekdays at 09:00',
+    '0 18 * * 1-5': 'weekdays at 18:00',
+    '*/30 * * * *': 'every 30 minutes',
+    '0 * * * *': 'every hour, on the hour',
+    '0 0 * * *': 'daily at midnight',
+  };
+  return named[text] || text;
+}
+
+/** Validate a schedule entry's fields. Returns { ok, error }. */
+export function validateEntry(entry) {
+  if (!entry || typeof entry !== 'object') return { ok: false, error: 'not a table' };
+  if (!String(entry.prompt || '').trim()) return { ok: false, error: 'prompt is required' };
+  try {
+    parseCron(entry.cron || entry.at);
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+  return { ok: true, error: '' };
+}
+
+/** Normalise the config table into a list with stable ids. */
+export function listSchedules(schedule) {
+  const table = schedule && typeof schedule === 'object' ? schedule : {};
+  return Object.entries(table).map(([id, e]) => ({
+    id,
+    cron: String((e && (e.cron || e.at)) || '').trim(),
+    prompt: String((e && e.prompt) || ''),
+    enabled: !(e && e.enabled === false),
+    cwd: (e && e.cwd) || '',
+    lastRun: (e && e.last_run) || null,
+    valid: validateEntry(e).ok,
+    error: validateEntry(e).error,
+  }));
+}
+
+/**
+ * Which entries are DUE now.
+ *
+ * The rule is "the schedule matches this minute and it has not already run in this
+ * minute". Both halves matter: a timer that ticks twice within one minute (which
+ * happens when the process was busy, or when the tick lands on a minute boundary)
+ * must not fire the same entry twice, and a session that was closed over the due
+ * minute must not fire a burst of catch-up prompts on the next launch — a schedule
+ * is not a queue of missed work.
+ */
+export function dueSchedules(schedule, now) {
+  const d = now || new Date();
+  const minuteKey = `${d.getFullYear()}-${d.getMonth() + 1}-${d.getDate()}T${d.getHours()}:${d.getMinutes()}`;
+  const out = [];
+  for (const e of listSchedules(schedule)) {
+    if (!e.enabled || !e.valid) continue;
+    let matcher;
+    try { matcher = parseCron(e.cron); } catch { continue; }
+    if (!matcher.matches(d)) continue;
+    if (e.lastRun === minuteKey) continue;
+    out.push({ ...e, minuteKey });
+  }
+  return out;
+}
+
+/**
+ * The schedule table with the given entries marked as run in this minute.
+ *
+ * Kept for callers that keep their history IN the config (the panel shows it either
+ * way); the TUI uses the side file (see writeHistory) because rewriting the user's
+ * whole config.toml once a minute is not acceptable.
+ */
+export function markRun(schedule, ids, minuteKey) {
+  const out = { ...(schedule && typeof schedule === 'object' ? schedule : {}) };
+  for (const id of ids) {
+    if (!out[id]) continue;
+    out[id] = { ...out[id], last_run: minuteKey };
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Run history
+// ---------------------------------------------------------------------------
+// `last_run` cannot live in config.toml: the schedules are HAND-WRITTEN tables, and
+// rewriting that file on every fire is both risky (it holds the user's whole
+// configuration) and wrong in kind (a run record is state, not configuration). So the
+// history is a separate small JSON file beside the config, keyed by entry id.
+//
+// It is also what makes "once per due minute" survive a RESTART: without a record on
+// disk, a session closed and reopened within the same minute would fire the entry a
+// second time.
+
+/** Where the run history lives — beside the config, so a test HOME gets its own. */
+export function historyFile(configFile) {
+  return path.join(path.dirname(String(configFile)), 'schedule-state.json');
+}
+
+/** Read the run history. A missing or corrupt file reads as empty; never throws. */
+export function readHistory(configFile) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(historyFile(configFile), 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch { return {}; }
+}
+
+/** Write the run history. Best-effort: a failed write must not drop the work. */
+export function writeHistory(configFile, history) {
+  try {
+    fs.mkdirSync(path.dirname(historyFile(configFile)), { recursive: true });
+    fs.writeFileSync(historyFile(configFile), JSON.stringify(history, null, 2) + '\n', 'utf8');
+    return true;
+  } catch { return false; }
+}
+
+/** `2026-9-30T9:5` — LOCAL time, since a cron expression is local by definition. */
+export function minuteKeyOf(d) {
+  return `${d.getFullYear()}-${d.getMonth() + 1}-${d.getDate()}T${d.getHours()}:${d.getMinutes()}`;
+}
+
+/**
+ * Which entries are due, consulting BOTH the config and the persisted history.
+ *
+ * Kept beside `dueSchedules` rather than replacing it, so the pure matching rule stays
+ * testable without a filesystem.
+ */
+export function dueWithHistory(schedule, history, now) {
+  const d = now || new Date();
+  const minuteKey = minuteKeyOf(d);
+  const out = [];
+  for (const e of listSchedules(schedule)) {
+    if (!e.enabled || !e.valid) continue;
+    let matcher;
+    try { matcher = parseCron(e.cron); } catch { continue; }
+    if (!matcher.matches(d)) continue;
+    const last = (history && history[e.id]) || e.lastRun || '';
+    if (last === minuteKey) continue;
+    out.push({ ...e, minuteKey });
+  }
+  return out;
+}
+
+/** Panel lines for /schedule — history included when it is available. */
+export function describeSchedules(schedule, history) {
+  const rows = listSchedules(schedule);
+  if (!rows.length) {
+    return [
+      'No schedules. Add one to config.toml:',
+      '',
+      '  [schedule.morning]',
+      '  cron = "0 9 * * 1-5"           # weekdays at 09:00',
+      '  prompt = "Check the open PRs and post a summary"',
+      '  enabled = true                  # optional, default true',
+    ].join('\n');
+  }
+  return rows.map((e) => {
+    const state = !e.enabled ? 'off' : e.valid ? 'on ' : 'BAD';
+    const when = e.valid ? describeCron(e.cron) : `INVALID: ${e.error}`;
+    const last = (history && history[e.id]) || e.lastRun || '';
+    return `${state} ${e.id.padEnd(16)} ${when.padEnd(26)} ${e.prompt.slice(0, 44)}${last ? `  last ${last}` : ''}`;
+  }).join('\n');
+}
+
+export default {
+  parseCron, describeCron, validateEntry, listSchedules, dueSchedules, markRun,
+  describeSchedules, dueWithHistory, readHistory, writeHistory, historyFile, minuteKeyOf,
+};

package/src/session-approvals.js

@@ -0,0 +1,86 @@
+// Session approval memory — "always allow this, for now".
+//
+// The permission RULES in config.toml are the durable answer ("allow npm test
+// forever"). This module is the transient one: the user is mid-task, a prompt
+// appears for something they already decided about five minutes ago, and they want
+// it gone without editing a file. kimi has exactly this as one of its permission
+// policies (`session-approval-history`), evaluated AFTER the configured rules so a
+// rule always wins.
+//
+// Scope rules, all of which exist to keep the memory from being a surprise:
+//   * The entry lives on the SESSION object, not on config — it dies with the
+//     session. A persisted grant would silently apply to next week's work.
+//   * It is keyed by the SHAPE of the call, not the call: for a command, the
+//     PROGRAM plus its first argument (`npm test`), so `npm test --watch` is
+//     covered but `npm publish` is not.
+//   * It never covers a destructive command, whatever the user approved. Ctrl+A on
+//     `rm -rf /build` must not pre-approve the next `rm -rf /`. This is the one
+//     place the module refuses to be literal about what was approved.
+//   * It cannot override a `deny` rule: the rule check runs first (see the caller).
+
+/**
+ * The key an approval is remembered under.
+ *
+ * For a shell command: the program and its first non-flag argument. That is the
+ * narrowest unit that is still useful — `npm test` covers `npm test --watch` and
+ * `npm test src/a.test.ts`, while `npm run` stays separate from `npm test`.
+ *
+ * For anything else: the tool name alone. A file tool's approval is about the TOOL
+ * (the path guard still applies per call), and keying by path would produce a new
+ * entry per file with no benefit.
+ */
+export function approvalKey(toolName, args) {
+  const tool = String(toolName || '');
+  if (tool !== 'Bash') return tool;
+  const cmd = String((args && (args.command || args.cmd)) || '').trim();
+  if (!cmd) return tool;
+  const words = cmd.split(/\s+/).filter(Boolean);
+  // Skip a leading assignment (`FOO=1 npm test`) — it is not the program.
+  const prog = words.find((w) => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(w)) || '';
+  if (!prog) return tool;
+  const sub = words.slice(words.indexOf(prog) + 1).find((w) => !w.startsWith('-')) || '';
+  return sub ? `${tool}:${prog} ${sub}` : `${tool}:${prog}`;
+}
+
+/** A label for the transcript, e.g. `Bash: npm test` or `Write`. */
+export function sessionApprovalLabel(toolName, args) {
+  return approvalKey(toolName, args);
+}
+
+/**
+ * Was this call approved for the session? `destructive` is the caller's verdict on
+ * the command; a true value always returns false, so the memory cannot pre-approve
+ * something that was judged too dangerous to run unattended.
+ */
+export function isApprovedForSession(list, toolName, args, destructive = false) {
+  if (destructive) return false;
+  const key = approvalKey(toolName, args);
+  if (!key) return false;
+  return Array.isArray(list) && list.includes(key);
+}
+
+/** Add a key to the list (returning a new array; no duplicates). */
+export function rememberApproval(list, toolName, args) {
+  const key = approvalKey(toolName, args);
+  const cur = Array.isArray(list) ? list : [];
+  if (!key || cur.includes(key)) return cur.slice();
+  return [...cur, key];
+}
+
+/** Drop one key. */
+export function forgetApproval(list, key) {
+  return (Array.isArray(list) ? list : []).filter((k) => k !== key);
+}
+
+/** Panel lines for /permissions, so the grants are visible and revocable. */
+export function describeSessionApprovals(list) {
+  const arr = Array.isArray(list) ? list : [];
+  if (!arr.length) return 'No session approvals. Ctrl+A on a prompt remembers one.';
+  return ['Approved for this session (cleared when the session ends):']
+    .concat(arr.map((k) => '  ' + k)).join('\n');
+}
+
+export default {
+  approvalKey, sessionApprovalLabel, isApprovedForSession,
+  rememberApproval, forgetApproval, describeSessionApprovals,
+};