@try-works/dsh-memory 0.1.19 → 0.1.20

package/src/tasks.js

@@ -1,617 +1,617 @@
-// The tasks layer: a durable, portable record of the DSH scheduled tasks this machine had.
-//
-// Why this exists at all. ~/.dsh/storages/schedule.json holds the only copy of every automated
-// task: it is in no git repository and no backup. A task is owned by the session that created
-// it, and that ownership is load-bearing twice - runtime.ts:101 resolves an agent from
-// task.sessionId before every delivery and throws when it cannot, and index.ts:421 DELETES
-// every active task of a session when that session stops. So tasks die with their session and
-// nothing anywhere keeps a second copy.
-//
-// Two rules shape the format.
-//
-// PORTABLE ONLY. The stored value is the task's `record` - id, kind, title, prompt, and the
-// selector that says when it runs. `sessionId`, `status` and `deliveryHistory` are machine-local
-// runtime state and are never written: carrying sessionId across machines is exactly what would
-// make a restored task fail, because the session it names does not exist there.
-//
-// ONE FILE PER TASK, JSON. A record must round-trip EXACTLY - a cron expression, an IANA zone,
-// and prompts that run to thousands of characters. Markdown would need a hand-rolled format and
-// would be one escaping bug away from a corrupted schedule. index.md is the readable overview.
-
-import { createHash } from 'node:crypto'
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
-import { homedir } from 'node:os'
-import { join } from 'node:path'
-import { globalDir } from './store.js'
-import { slugify } from './workspace-key.js'
-
-/** Directory, under a scope root, holding one file per task plus the index. */
-export const TASKS_DIR = 'tasks'
-export const TASK_INDEX = 'index.md'
-
-/**
- * The lifecycle a backed-up task can rest in.
- *
- * The host records only two states (schedule types.ts:217, 'active' | 'inactive') and its
- * 'inactive' means DELIVERED or recurrence-exhausted, not failed: a delivery failure throws
- * before any commit (runtime.ts:101-102), so a task failing on every scan stays 'active' and
- * leaves no trace. Everything below that the host cannot express is carried here instead.
- */
-export const TASK_STATES = {
-  ACTIVE: 'active',
-  PENDING: 'pending',
-  PAUSED: 'paused',
-  STOPPED: 'stopped',
-  FAILED: 'failed',
-  ORPHANED: 'orphaned',
-  SKIPPED: 'skipped',
-  DONE: 'done',
-}
-
-/**
- * Every resting state's single exit, meaning 'something changed'.
- *
- * The queue in src/queue.js learned this the hard way: a state with no way out is a state a
- * thing sits in forever, silently. A test walks this table so a new state cannot be added
- * without one.
- */
-export const TASK_STATE_EXITS = {
-  // Two entries were missing, and NOTHING noticed until writeTask began reading this table.
-  //
-  // 'orphaned': the session holding a live task can disappear while the task itself does not
-  // change, so an armed task can become one that can never fire.
-  //
-  // 'paused' in every row: holding a task back is a DECISION the user makes about a task in any
-  // condition, not a lifecycle step. Writing the table without it left the entire pause path
-  // undeclared - the feature worked, and the declaration that was supposed to describe it did not.
-  active: ['stopped', 'done', 'failed', 'orphaned', 'paused'],
-  pending: ['active', 'paused'],
-  paused: ['pending'],
-  stopped: ['pending', 'paused'],
-  failed: ['active', 'paused'],
-  orphaned: ['pending', 'paused'],
-  skipped: ['active', 'paused'],
-  done: ['active', 'paused'],
-}
-
-const STATES = Object.values(TASK_STATES)
-
-/**
- * A stored state, or null when it is not one we know.
- *
- * Null rather than a throw or a silent default: an index that crashes on one bad file takes the
- * whole layer with it, and quietly treating an unknown state as 'active' would report a task as
- * armed when nothing has established that. The caller decides, and the index shows it verbatim.
- */
-export function readState(value) {
-  return STATES.includes(value) ? value : null;
-}
-
-/**
- * Where the task files live: under the GLOBAL scope, not the store root.
- *
- * The layer is global-only by design - DSH tasks are not repository-scoped - so it belongs beside
- * global/semantic.md and the rest. Resolving it against the root instead put it at <root>/tasks,
- * a directory nothing else in the store knows about and no index or sync rule covers. Caught by
- * looking for global/tasks in a real store and finding nothing there.
- */
-export function tasksDir(root) { return join(globalDir(root), TASKS_DIR) }
-
-/**
- * The fields that say WHEN a task runs. Used to tell one task from another.
- *
- * `id` and `scheduledAt` are deliberately absent. An id is minted fresh by the schedule service
- * on every create (index.ts:256), so a restored task never keeps the id it was backed up with,
- * and scheduledAt is recomputed from now. Keying on either would make restore re-add every task
- * on every boot - the worst possible failure for something that runs automatically.
- */
-const SELECTOR_FIELDS = ['cron', 'daily', 'weekly', 'at', 'after_seconds', 'every_seconds', 'expression', 'timeZone']
-
-/**
- * The content identity of a task: what makes it the SAME task across a restore.
- *
- * Title plus kind plus whichever selector fields the record carries. Derived identically on the
- * backup and restore sides, which is why it lives here as one function rather than being
- * inlined twice. Two tasks sharing a title and a schedule are treated as one, which is the
- * correct reading: no reader could tell them apart either.
- */
-export function contentKey(record) {
-  if (!record || typeof record !== 'object') return ''
-  const parts = [String(record.kind ?? ''), String(record.title ?? '').trim()]
-  for (const field of SELECTOR_FIELDS) {
-    const value = record[field]
-    if (value === undefined || value === null) continue
-    parts.push(field + '=' + (typeof value === 'object' ? JSON.stringify(value) : String(value)))
-  }
-  return parts.join('|')
-}
-
-/**
- * The file one task lives in: its title as a slug, plus a short digest of the content key.
- *
- * The digest is what makes the name safe. Two tasks can share a title - the slug alone would
- * have them overwrite each other - and the digest is derived from the content key, so a task's
- * file keeps its name across restarts and across a backup/restore round trip. A title with no
- * usable characters (a fully non-Latin or punctuation-only title) falls back to the digest
- * rather than producing '.json'.
- */
-export function taskFileName(record) {
-  const key = contentKey(record)
-  const digest = createHash('sha1').update(key).digest('hex').slice(0, 8)
-  const slug = slugify(record && record.title)
-  return (slug === '' ? digest : slug + '-' + digest) + '.json'
-}
-
-export function taskFilePath(root, record) { return join(tasksDir(root), taskFileName(record)) }
-
-/**
- * What each state MEANS, in one line.
- *
- * Separate from deriveState's reasons on purpose. A derived reason explains a transition - why the
- * state changed to what was just computed - and cannot be reused to caption a state that was
- * simply read back off disk. Pairing the two is how an armed task briefly acquired the reason a
- * stopped one carries.
- */
-const STATE_MEANING = {
-  [TASK_STATES.ACTIVE]: 'armed in the live store and waiting for its next occurrence',
-  [TASK_STATES.PENDING]: 'in the backup but not in the live store; a restore re-arms it',
-  [TASK_STATES.PAUSED]: 'held back on purpose; every automatic pass leaves it alone',
-  [TASK_STATES.STOPPED]: 'was armed, and its owning session stopped, so the host deleted it',
-  [TASK_STATES.FAILED]: 'was due and has still not delivered; the host records no failure of its own',
-  [TASK_STATES.ORPHANED]: 'armed, but the session that owns it cannot be resolved, so it can never fire',
-  [TASK_STATES.SKIPPED]: 'captured, but its kind is not one we can re-arm; a restore refuses it rather than guessing',
-  [TASK_STATES.DONE]: 'delivered, or its recurrence is exhausted',
-}
-
-/**
- * One index row: the task, its state, and what that state means.
- * Exported so a test can caption a state with the real wording rather than a placeholder - a stub
- * reason would have made the caption assertion pass while proving nothing about the page.
- */
-export function describeTask(task, now) {
-  const state = task.stateKnown ? task.state : deriveState({ stored: null, live: null, now }).state
-  return {
-    ...task,
-    fileName: task.file ?? '',
-    state,
-    reason: STATE_MEANING[state] ?? 'an unrecognised state, shown as found in the file',
-  }
-}
-
-function ensureTasksDir(root) {
-  const dir = tasksDir(root)
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
-  return dir
-}
-
-/**
- * Write one task, replacing any file for the same content key.
- * @returns the file path written.
- */
-export function writeTask(root, record, state, nowIso) {
-  ensureTasksDir(root)
-  const file = taskFilePath(root, record)
-  // ENFORCED, not documented. This table sat in the file unread since it was written, so a state
-  // could move anywhere and nothing objected - the same shape as the vocabulary states that had a
-  // test and no producer. Refusing here means a task cannot silently leave a state by a route
-  // nobody declared, which is what makes 'every resting state has a working exit' checkable
-  // rather than aspirational.
-  const previous = readTaskFile(file)
-  if (previous && previous.stateKnown && previous.state !== state) {
-    const allowed = TASK_STATE_EXITS[previous.state] ?? []
-    if (!allowed.includes(state)) {
-      throw new Error('tasks: refusing the transition ' + previous.state + ' -> ' + state + ' for "' + String(record.title ?? '') + '"; allowed from ' + previous.state + ': ' + allowed.join(', '))
-    }
-  }
-  writeFileSync(file, JSON.stringify({ backedUpAt: nowIso, state, record }, null, 2) + '\n', 'utf8')
-  return file;
-}
-
-/**
- * Read one task file.
- * @returns { file, backedUpAt, state, raw, record } or null when the file is unreadable.
- *
- * A malformed file yields null rather than throwing: one bad file must not take the layer down,
- * and the index reports what it could not read instead of pretending the task is absent.
- */
-export function readTaskFile(file) {
-  try {
-    const parsed = JSON.parse(readFileSync(file, 'utf8'))
-    if (!parsed || typeof parsed !== 'object' || !parsed.record || typeof parsed.record !== 'object') return null
-    return {
-      file,
-      backedUpAt: typeof parsed.backedUpAt === 'string' ? parsed.backedUpAt : null,
-      // Kept verbatim, including when unrecognised, so the index can show what it found.
-      state: typeof parsed.state === 'string' ? parsed.state : null,
-      stateKnown: readState(parsed.state) !== null,
-      record: parsed.record,
-    }
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Every task file in the layer, ordered by title so the index is stable between runs.
- * @returns { tasks, unreadable } - unreadable names the files that could not be parsed.
- */
-export function listTasks(root) {
-  const dir = tasksDir(root)
-  if (!existsSync(dir)) return { tasks: [], unreadable: [] }
-  const tasks = [];
-  const unreadable = [];
-  for (const name of readdirSync(dir)) {
-    if (!name.endsWith('.json')) continue;
-    const task = readTaskFile(join(dir, name));
-    if (task === null) unreadable.push(name);
-    else tasks.push(task);
-  }
-  tasks.sort((a, b) => String(a.record.title ?? '').localeCompare(String(b.record.title ?? '')));
-  unreadable.sort();
-  return { tasks, unreadable };
-}
-
-/** How long past its due time an armed task may sit before we call it failed. */
-export const OVERDUE_MS = 6 * 60 * 60 * 1000
-
-/**
- * Derive a task's state from what can actually be observed.
- *
- * This is the honest version of the vocabulary, and three entries are narrower than they first
- * look, because the host does not publish what they name:
- *
- * - FAILED is not a status the host records. A delivery failure throws before any commit
- *   (runtime.ts:101-102), so a task failing on every scan stays 'active' with no trace. What IS
- *   observable is a task still armed long after the moment it was due, which is what this
- *   reports - 'due at X, still not delivered' rather than a claim about why.
- * - ORPHANED is a live row whose owning session cannot be resolved, so it can never fire while
- *   still occupying the store. Detecting that needs the session lookup, which the caller does;
- *   it is passed in rather than guessed here.
- * - SKIPPED is a live task with no backup file: seen, deliberately not captured.
- *
- * PAUSED outranks everything. An automatic restore must never silently re-arm something that was
- * held back on purpose - that surprise is the thing this design exists to prevent.
- *
- * @returns { state, reason } - the reason is recorded so a reader is told why, not just what.
- */
-export function deriveState({ stored, live, now = Date.now(), ownerResolvable = true }) {
-  if (stored === TASK_STATES.PAUSED) {
-    return { state: TASK_STATES.PAUSED, reason: 'held back on purpose; automatic restore leaves it alone' };
-  }
-  if (live) {
-    if (!ownerResolvable) {
-      return { state: TASK_STATES.ORPHANED, reason: 'armed, but the session that owns it cannot be resolved, so it can never fire' };
-    }
-    if (live.status === 'inactive') {
-      return { state: TASK_STATES.DONE, reason: 'delivered, or its recurrence is exhausted' };
-    }
-    const due = Date.parse(live.record && live.record.scheduledAt ? live.record.scheduledAt : '');
-    if (Number.isFinite(due) && due < now - OVERDUE_MS) {
-      return { state: TASK_STATES.FAILED, reason: 'was due at ' + new Date(due).toISOString() + ' and has still not delivered' };
-    }
-    return { state: TASK_STATES.ACTIVE, reason: 'armed in the live store and waiting for its next occurrence' };
-  }
-  if (stored === TASK_STATES.ACTIVE) {
-    return { state: TASK_STATES.STOPPED, reason: 'was armed; the host deletes a task when its session stops' };
-  }
-  return { state: TASK_STATES.PENDING, reason: 'in the backup, not in the live store; a restore re-arms it' };
-}
-
-/**
- * Render the layer index.
- *
- * Readable and diffable, which is the whole reason the tasks are files rather than one blob: a
- * git diff of this page is how you see that a task appeared, changed state, or went missing.
- * Unreadable files are listed rather than omitted - an index that hides what it could not parse
- * reports a smaller world than exists.
- */
-export function renderTaskIndex(rows, { unreadable = [], nowIso, error = null } = {}) {
-  const out = ['# Scheduled tasks', ''];
-  out.push('Portable backup of the DSH scheduled tasks on this machine. One file per task, plus');
-  out.push('this index. Machine-local state (the owning session, delivery history) is never stored.');
-  out.push('');
-  out.push('Generated ' + nowIso + '. ' + rows.length + ' task(s).');
-  // A page that stayed silent while the backup could not read the store would read as a healthy
-  // machine with nothing to do. The failure belongs on the page, not only in a return value.
-  if (error) {
-    out.push('');
-    out.push('> **The last backup could not read the schedule store.** ' + String(error));
-    out.push('>');
-    out.push('> The tasks below are what memory already holds; they are not a fresh reading.');
-  }
-  out.push('');
-  if (rows.length === 0) {
-    out.push('No tasks are backed up yet. The backup runs on the memory sync cadence, or on demand');
-    out.push('with memory_tasks.');
-    out.push('');
-  } else {
-    out.push('| task | kind | schedule | state | backed up |');
-    out.push('| --- | --- | --- | --- | --- |');
-    for (const row of rows) {
-      out.push('| ' + cell(row.record.title) + ' | ' + cell(row.record.kind) + ' | ' + cell(scheduleOf(row.record)) + ' | ' + cell(stateCell(row)) + ' | ' + cell(row.backedUpAt) + ' |');
-    }
-    out.push('');
-    for (const row of rows) {
-      out.push('## ' + String(row.record.title ?? '(untitled)'));
-      out.push('');
-      out.push('- file: `' + row.fileName + '`');
-      out.push('- id: `' + String(row.record.id ?? '') + '` (diagnostic only; a restore mints a new one)');
-      out.push('- state: **' + row.state + '** - ' + row.reason);
-      out.push('');
-    }
-  }
-  if (unreadable.length > 0) {
-    out.push('## Could not be read');
-    out.push('');
-    for (const name of unreadable) out.push('- `' + name + '` - not valid task JSON, so it is neither counted nor drawn');
-    out.push('');
-  }
-  return out.join('\n');
-}
-
-/** A markdown table cell: a pipe or a newline in a title would otherwise break the row. */
-function cell(value) {
-  return String(value ?? '').replace(/\|/g, '\\|').replace(/\r?\n/g, ' ').trim();
-}
-
-/** The schedule in words, so the index is readable without decoding the record. */
-function scheduleOf(record) {
-  const kind = String(record.kind ?? '');
-  const zone = record.timeZone ? ' ' + record.timeZone : '';
-  if (kind === 'cron') return 'cron ' + String(record.expression ?? '') + zone;
-  if (kind === 'weekly') return 'weekly ' + JSON.stringify(record.weekly ?? {}) + zone;
-  if (kind === 'daily') return 'daily ' + JSON.stringify(record.daily ?? {}) + zone;
-  // The same camelCase/snake_case confusion as `after` above, in the same function. Writing a test
-  // to pin ONE of them surfaced the other.
-  if (kind === 'every') return 'every ' + String(record.everySeconds ?? '') + 's';
-  if (kind === 'at') return 'at ' + String(record.scheduledAt ?? '');
-  // `afterSeconds`, not `after_seconds` - the record uses camelCase, the CREATE REQUEST uses
-  // snake_case. The live index printed "after s" with the interval missing, which no test saw
-  // because no test rendered an `after` record.
-  if (kind === 'after') return 'after ' + String(record.afterSeconds ?? '') + 's';
-  return kind;
-}
-
-/** The state cell: an unrecognised stored state is shown as found, never silently defaulted. */
-function stateCell(row) {
-  return row.stateKnown === false ? row.state + ' (unknown state in file)' : row.state;
-}
-
-/** The kinds the schedule plugin can store (types.ts ScheduleRecord union). */
-export const KNOWN_KINDS = ['after', 'at', 'every', 'daily', 'weekly', 'cron']
-
-/**
- * Where the schedule plugin keeps its tasks: a storage unit under the DSH home.
- *
- * DSH_HOME is the harness's own override (boot/app-boot reads it), defaulting to ~/.dsh - the
- * same resolution the harness uses, so the plugin finds the store without being told.
- */
-export function defaultSchedulePath(home = homedir()) {
-  const configured = process.env.DSH_HOME
-  const dshHome = configured && configured !== '' ? configured : join(home, '.dsh')
-  return join(dshHome, 'storages', 'schedule.json')
-}
-
-/**
- * Read the live schedule store.
- * @returns { tasks, error, missing } where tasks are the rows as stored.
- *
- * A missing file is not an error: a machine that has never scheduled anything has no store, and
- * the backup pass must read that as 'nothing to do' rather than as a failure. A file that exists
- * but cannot be read IS reported, because writing an index over an unreadable store would quietly
- * claim the machine has no tasks.
- */
-export function readScheduleStore(path) {
-  if (!existsSync(path)) return { tasks: [], error: null, missing: true }
-  let parsed
-  try {
-    parsed = JSON.parse(readFileSync(path, 'utf8'))
-  } catch (error) {
-    return { tasks: [], error: 'unreadable: ' + (error && error.message ? error.message : String(error)), missing: false }
-  }
-  const table = parsed && parsed.tables && parsed.tables.tasks
-  if (!table || typeof table !== 'object') return { tasks: [], error: 'no tables.tasks in the schedule store', missing: false }
-  return { tasks: Object.keys(table).map((id) => ({ id, ...table[id] })), error: null, missing: false }
-}
-
-/**
- * Back up every live task, and refresh the state of every task already backed up.
- *
- * ADDITIVE, ALWAYS. Nothing here deletes: a task gone from the live store keeps its file and has
- * its state rewritten to say so. A stale backup must never be able to wipe a schedule, and a task
- * deleted on purpose must stay visible as gone rather than vanish from the record of what this
- * machine used to run.
- *
- * A task whose kind we do not recognise is stored and flagged SKIPPED: dropping it would mean losing
- * a task from a backup, and flagging it means a restore refuses it rather than guessing.
- */
-export function backupTasks(root, { schedulePath, now = Date.now(), nowIso, sessions } = {}) {
-  const at = nowIso ?? new Date(now).toISOString()
-  const live = readScheduleStore(schedulePath ?? defaultSchedulePath())
-  // Read once per pass, not per task: it is a directory walk, and every row asks the same question.
-  // Injectable so a test can state the world instead of inheriting this machine's: `null` means
-  // the question cannot be answered and no row is called orphaned.
-  const sessionSet = sessions === undefined ? sessionIdsOnDisk() : sessions
-  const before = listTasks(root)
-  if (live.error !== null) {
-    // The index is still rewritten, so a page from an earlier pass cannot sit on disk describing a
-    // store this pass could not read.
-    writeTaskIndex(root, before.tasks.map((t) => describeTask(t, now)), { unreadable: before.unreadable, nowIso: at, error: live.error })
-    return { written: 0, refreshed: 0, skipped: [], stopped: 0, unreadable: before.unreadable, error: live.error }
-  }
-  const byKey = new Map()
-  for (const task of before.tasks) byKey.set(contentKey(task.record), task)
-  let written = 0
-  let refreshed = 0
-  const skipped = []
-  const seen = new Set()
-  for (const task of live.tasks) {
-    const record = task.record
-    if (!record || typeof record !== 'object') { skipped.push({ id: task.id, reason: 'no record' }); continue }
-    if (!KNOWN_KINDS.includes(String(record.kind))) {
-      // CAPTURED, not dropped. An earlier version skipped these entirely, which meant a task whose
-      // kind we did not recognise silently vanished from a BACKUP - the one job this layer has. It
-      // is written and flagged 'skipped' instead, and planRestore refuses that state, so it can
-      // never be blindly re-armed. Preserved, visible, and unrestorable: all three on purpose.
-      skipped.push({ id: task.id, reason: 'unrecognised kind: ' + String(record.kind) })
-      writeTask(root, record, TASK_STATES.SKIPPED, byKey.get(contentKey(record))?.backedUpAt ?? at)
-      seen.add(contentKey(record))
-      continue
-    }
-    const key = contentKey(record)
-    seen.add(key)
-    const previous = byKey.get(key)
-    // A held-back task stays held back across every backup: that state is the user's decision, and
-    // a routine pass must not overwrite it with a derived one.
-    const held = previous && previous.stateKnown && previous.state === TASK_STATES.PAUSED
-    // Without this the ORPHANED state exists in the vocabulary and is never produced by any real
-    // pass - reachable from a unit test and from nothing else. `sessions === null` means the
-    // sessions directory is absent and we cannot tell, so the row is left as active.
-    const ownerResolvable = sessionSet === null || task.sessionId === undefined ? true : sessionSet.has(task.sessionId)
-    const derived = deriveState({ stored: held ? TASK_STATES.PAUSED : null, live: task, now, ownerResolvable })
-    writeTask(root, record, derived.state, previous ? previous.backedUpAt : at)
-    if (previous) refreshed += 1
-    else written += 1
-  }
-  let stopped = 0
-  const rows = []
-  for (const task of listTasks(root).tasks) {
-    if (seen.has(contentKey(task.record))) { rows.push(task); continue }
-    const derived = deriveState({ stored: task.stateKnown ? task.state : null, live: null, now })
-    if (derived.state !== task.state) {
-      writeTask(root, task.record, derived.state, task.backedUpAt ?? at)
-      stopped += 1
-    }
-    rows.push({ ...task, state: derived.state })
-  }
-  writeTaskIndex(root, rows.map((t) => describeTask(t, now)), { unreadable: before.unreadable, nowIso: at })
-  return { written, refreshed, skipped, stopped, unreadable: before.unreadable, error: null, rows, nowIso: at }
-}
-
-/**
- * Write the layer index.
- *
- * Regenerated on every pass rather than appended: an index that only grows would report tasks the
- * machine no longer runs as though they were still there. The per-task files are the truth; this
- * page is a view of them, which is why losing it costs nothing.
- * @returns the index path.
- */
-export function writeTaskIndex(root, rows, { unreadable = [], nowIso, error = null } = {}) {
-  ensureTasksDir(root)
-  const file = join(tasksDir(root), TASK_INDEX)
-  writeFileSync(file, renderTaskIndex(rows, { unreadable, nowIso, error }), 'utf8')
-  return file
-}
-
-/**
- * Translate a stored record back into the request the schedule service accepts.
- *
- * The two shapes do NOT share field names, and the differences are the kind that fail silently:
- * a record stores `timeZone` and `everySeconds` (types.ts ScheduleRecord union), while
- * ScheduleCreateRequest takes `time_zone` and `every_seconds`. Passing the record straight
- * through would drop the zone - a task would be re-armed in the wrong time zone, or refused, and
- * nothing in the record would look wrong afterwards.
- *
- * One-shot kinds are REFUSED rather than approximated. An `at` record keeps only its resolved
- * instant, which for any task that already ran is in the past, and an `after` record keeps a
- * relative delay whose clock would restart from now. Re-arming either would fabricate a schedule
- * the user never set, so the caller is told instead.
- *
- * @returns { request } or { error } naming exactly what could not be translated.
- */
-export function toCreateRequest(record) {
-  if (!record || typeof record !== 'object') return { error: 'no record' }
-  const title = String(record.title ?? '').trim()
-  const prompt = String(record.prompt ?? '')
-  if (title === '') return { error: 'no title' }
-  if (prompt === '') return { error: 'no prompt' }
-  const kind = String(record.kind ?? '')
-  const zone = record.timeZone
-  if (kind === 'cron') {
-    if (typeof record.expression !== 'string' || record.expression === '') return { error: 'cron with no expression' }
-    if (typeof zone !== 'string' || zone === '') return { error: 'cron with no time zone' }
-    return { request: { title, prompt, cron: { expression: record.expression, time_zone: zone } } }
-  }
-  if (kind === 'daily') {
-    if (typeof record.time !== 'string' || record.time === '') return { error: 'daily with no time' }
-    if (typeof zone !== 'string' || zone === '') return { error: 'daily with no time zone' }
-    return { request: { title, prompt, daily: { time: record.time, time_zone: zone } } }
-  }
-  if (kind === 'weekly') {
-    if (typeof record.time !== 'string' || record.time === '') return { error: 'weekly with no time' }
-    if (typeof zone !== 'string' || zone === '') return { error: 'weekly with no time zone' }
-    if (!Array.isArray(record.weekdays) || record.weekdays.length === 0) return { error: 'weekly with no weekdays' }
-    return { request: { title, prompt, weekly: { time: record.time, time_zone: zone, weekdays: [...record.weekdays] } } }
-  }
-  if (kind === 'every') {
-    if (!Number.isFinite(record.everySeconds) || record.everySeconds <= 0) return { error: 'every with no interval' }
-    return { request: { title, prompt, every_seconds: record.everySeconds } }
-  }
-  if (kind === 'at' || kind === 'after') {
-    return { error: 'a one-shot ' + kind + ' task is not restorable: it either already fired or its target is in the past, and re-arming it would invent a schedule that was never set' }
-  }
-  return { error: 'unrecognised kind: ' + kind }
-}
-
-/**
- * Decide what a restore would do, without doing any of it.
- *
- * Pure, so the decision can be tested and shown before anything is written. Additive and
- * de-duplicating by CONTENT: the service mints a fresh id on every create (schedule index.ts:256),
- * so a restored task never keeps the id it was backed up with, and matching on ids would find
- * nothing on the second boot and re-add everything.
- *
- * @returns { add, present, paused, refused } - one entry per backed-up task, each saying why.
- */
-export function planRestore(root, { liveTasks = [], now = Date.now() } = {}) {
-  const live = new Set(liveTasks.map((task) => contentKey(task.record)))
-  const { tasks, unreadable } = listTasks(root)
-  const add = []
-  const present = []
-  const paused = []
-  const refused = []
-  for (const task of tasks) {
-    const key = contentKey(task.record)
-    if (live.has(key)) { present.push({ task, reason: 'already in the live store, under whatever id it now carries' }); continue }
-    if (task.stateKnown && task.state === TASK_STATES.PAUSED) { paused.push({ task, reason: 'held back on purpose; automatic restore leaves it alone' }); continue }
-    if (task.stateKnown && task.state === TASK_STATES.SKIPPED) { refused.push({ task, reason: 'recorded as skipped' }); continue }
-    const translated = toCreateRequest(task.record)
-    if (translated.error) refused.push({ task, reason: translated.error })
-    else add.push({ task, request: translated.request })
-  }
-  return { add, present, paused, refused, unreadable }
-}
-
-/** The directory DSH keeps session records in, beside the schedule store's home. */
-export function sessionsRoot(home = homedir()) {
-  const configured = process.env.DSH_HOME
-  const dshHome = configured && configured !== '' ? configured : join(home, '.dsh')
-  return join(dshHome, 'sessions')
-}
-
-/**
- * Every session id that still has a record on disk.
- *
- * Used to tell ORPHANED from ACTIVE. A live task is armed against the session that created it, and
- * the runtime resolves an agent from that id before every delivery (schedule runtime.ts:101) - so
- * a task whose session is gone is a row that will never fire while still occupying the store. The
- * backup cannot see the runtime, but it can see whether the session still exists.
- *
- * @returns a Set, or null when the sessions directory is absent
- *
- * Null rather than an empty set on purpose: no sessions directory means we cannot tell, and an
- * empty set would mark every task on the machine orphaned. Refusing to guess is the rule here.
- */
-export function sessionIdsOnDisk(home = homedir()) {
-  const root = sessionsRoot(home)
-  if (!existsSync(root)) return null
-  const ids = new Set()
-  let projects
-  try { projects = readdirSync(root) } catch { return null }
-  for (const project of projects) {
-    let sessions
-    try { sessions = readdirSync(join(root, project)) } catch { continue }
-    for (const id of sessions) ids.add(id)
-  }
-  return ids
-}
+// The tasks layer: a durable, portable record of the DSH scheduled tasks this machine had.
+//
+// Why this exists at all. ~/.dsh/storages/schedule.json holds the only copy of every automated
+// task: it is in no git repository and no backup. A task is owned by the session that created
+// it, and that ownership is load-bearing twice - runtime.ts:101 resolves an agent from
+// task.sessionId before every delivery and throws when it cannot, and index.ts:421 DELETES
+// every active task of a session when that session stops. So tasks die with their session and
+// nothing anywhere keeps a second copy.
+//
+// Two rules shape the format.
+//
+// PORTABLE ONLY. The stored value is the task's `record` - id, kind, title, prompt, and the
+// selector that says when it runs. `sessionId`, `status` and `deliveryHistory` are machine-local
+// runtime state and are never written: carrying sessionId across machines is exactly what would
+// make a restored task fail, because the session it names does not exist there.
+//
+// ONE FILE PER TASK, JSON. A record must round-trip EXACTLY - a cron expression, an IANA zone,
+// and prompts that run to thousands of characters. Markdown would need a hand-rolled format and
+// would be one escaping bug away from a corrupted schedule. index.md is the readable overview.
+
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { globalDir } from './store.js'
+import { slugify } from './workspace-key.js'
+
+/** Directory, under a scope root, holding one file per task plus the index. */
+export const TASKS_DIR = 'tasks'
+export const TASK_INDEX = 'index.md'
+
+/**
+ * The lifecycle a backed-up task can rest in.
+ *
+ * The host records only two states (schedule types.ts:217, 'active' | 'inactive') and its
+ * 'inactive' means DELIVERED or recurrence-exhausted, not failed: a delivery failure throws
+ * before any commit (runtime.ts:101-102), so a task failing on every scan stays 'active' and
+ * leaves no trace. Everything below that the host cannot express is carried here instead.
+ */
+export const TASK_STATES = {
+  ACTIVE: 'active',
+  PENDING: 'pending',
+  PAUSED: 'paused',
+  STOPPED: 'stopped',
+  FAILED: 'failed',
+  ORPHANED: 'orphaned',
+  SKIPPED: 'skipped',
+  DONE: 'done',
+}
+
+/**
+ * Every resting state's single exit, meaning 'something changed'.
+ *
+ * The queue in src/queue.js learned this the hard way: a state with no way out is a state a
+ * thing sits in forever, silently. A test walks this table so a new state cannot be added
+ * without one.
+ */
+export const TASK_STATE_EXITS = {
+  // Two entries were missing, and NOTHING noticed until writeTask began reading this table.
+  //
+  // 'orphaned': the session holding a live task can disappear while the task itself does not
+  // change, so an armed task can become one that can never fire.
+  //
+  // 'paused' in every row: holding a task back is a DECISION the user makes about a task in any
+  // condition, not a lifecycle step. Writing the table without it left the entire pause path
+  // undeclared - the feature worked, and the declaration that was supposed to describe it did not.
+  active: ['stopped', 'done', 'failed', 'orphaned', 'paused'],
+  pending: ['active', 'paused'],
+  paused: ['pending'],
+  stopped: ['pending', 'paused'],
+  failed: ['active', 'paused'],
+  orphaned: ['pending', 'paused'],
+  skipped: ['active', 'paused'],
+  done: ['active', 'paused'],
+}
+
+const STATES = Object.values(TASK_STATES)
+
+/**
+ * A stored state, or null when it is not one we know.
+ *
+ * Null rather than a throw or a silent default: an index that crashes on one bad file takes the
+ * whole layer with it, and quietly treating an unknown state as 'active' would report a task as
+ * armed when nothing has established that. The caller decides, and the index shows it verbatim.
+ */
+export function readState(value) {
+  return STATES.includes(value) ? value : null;
+}
+
+/**
+ * Where the task files live: under the GLOBAL scope, not the store root.
+ *
+ * The layer is global-only by design - DSH tasks are not repository-scoped - so it belongs beside
+ * global/semantic.md and the rest. Resolving it against the root instead put it at <root>/tasks,
+ * a directory nothing else in the store knows about and no index or sync rule covers. Caught by
+ * looking for global/tasks in a real store and finding nothing there.
+ */
+export function tasksDir(root) { return join(globalDir(root), TASKS_DIR) }
+
+/**
+ * The fields that say WHEN a task runs. Used to tell one task from another.
+ *
+ * `id` and `scheduledAt` are deliberately absent. An id is minted fresh by the schedule service
+ * on every create (index.ts:256), so a restored task never keeps the id it was backed up with,
+ * and scheduledAt is recomputed from now. Keying on either would make restore re-add every task
+ * on every boot - the worst possible failure for something that runs automatically.
+ */
+const SELECTOR_FIELDS = ['cron', 'daily', 'weekly', 'at', 'after_seconds', 'every_seconds', 'expression', 'timeZone']
+
+/**
+ * The content identity of a task: what makes it the SAME task across a restore.
+ *
+ * Title plus kind plus whichever selector fields the record carries. Derived identically on the
+ * backup and restore sides, which is why it lives here as one function rather than being
+ * inlined twice. Two tasks sharing a title and a schedule are treated as one, which is the
+ * correct reading: no reader could tell them apart either.
+ */
+export function contentKey(record) {
+  if (!record || typeof record !== 'object') return ''
+  const parts = [String(record.kind ?? ''), String(record.title ?? '').trim()]
+  for (const field of SELECTOR_FIELDS) {
+    const value = record[field]
+    if (value === undefined || value === null) continue
+    parts.push(field + '=' + (typeof value === 'object' ? JSON.stringify(value) : String(value)))
+  }
+  return parts.join('|')
+}
+
+/**
+ * The file one task lives in: its title as a slug, plus a short digest of the content key.
+ *
+ * The digest is what makes the name safe. Two tasks can share a title - the slug alone would
+ * have them overwrite each other - and the digest is derived from the content key, so a task's
+ * file keeps its name across restarts and across a backup/restore round trip. A title with no
+ * usable characters (a fully non-Latin or punctuation-only title) falls back to the digest
+ * rather than producing '.json'.
+ */
+export function taskFileName(record) {
+  const key = contentKey(record)
+  const digest = createHash('sha1').update(key).digest('hex').slice(0, 8)
+  const slug = slugify(record && record.title)
+  return (slug === '' ? digest : slug + '-' + digest) + '.json'
+}
+
+export function taskFilePath(root, record) { return join(tasksDir(root), taskFileName(record)) }
+
+/**
+ * What each state MEANS, in one line.
+ *
+ * Separate from deriveState's reasons on purpose. A derived reason explains a transition - why the
+ * state changed to what was just computed - and cannot be reused to caption a state that was
+ * simply read back off disk. Pairing the two is how an armed task briefly acquired the reason a
+ * stopped one carries.
+ */
+const STATE_MEANING = {
+  [TASK_STATES.ACTIVE]: 'armed in the live store and waiting for its next occurrence',
+  [TASK_STATES.PENDING]: 'in the backup but not in the live store; a restore re-arms it',
+  [TASK_STATES.PAUSED]: 'held back on purpose; every automatic pass leaves it alone',
+  [TASK_STATES.STOPPED]: 'was armed, and its owning session stopped, so the host deleted it',
+  [TASK_STATES.FAILED]: 'was due and has still not delivered; the host records no failure of its own',
+  [TASK_STATES.ORPHANED]: 'armed, but the session that owns it cannot be resolved, so it can never fire',
+  [TASK_STATES.SKIPPED]: 'captured, but its kind is not one we can re-arm; a restore refuses it rather than guessing',
+  [TASK_STATES.DONE]: 'delivered, or its recurrence is exhausted',
+}
+
+/**
+ * One index row: the task, its state, and what that state means.
+ * Exported so a test can caption a state with the real wording rather than a placeholder - a stub
+ * reason would have made the caption assertion pass while proving nothing about the page.
+ */
+export function describeTask(task, now) {
+  const state = task.stateKnown ? task.state : deriveState({ stored: null, live: null, now }).state
+  return {
+    ...task,
+    fileName: task.file ?? '',
+    state,
+    reason: STATE_MEANING[state] ?? 'an unrecognised state, shown as found in the file',
+  }
+}
+
+function ensureTasksDir(root) {
+  const dir = tasksDir(root)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+  return dir
+}
+
+/**
+ * Write one task, replacing any file for the same content key.
+ * @returns the file path written.
+ */
+export function writeTask(root, record, state, nowIso) {
+  ensureTasksDir(root)
+  const file = taskFilePath(root, record)
+  // ENFORCED, not documented. This table sat in the file unread since it was written, so a state
+  // could move anywhere and nothing objected - the same shape as the vocabulary states that had a
+  // test and no producer. Refusing here means a task cannot silently leave a state by a route
+  // nobody declared, which is what makes 'every resting state has a working exit' checkable
+  // rather than aspirational.
+  const previous = readTaskFile(file)
+  if (previous && previous.stateKnown && previous.state !== state) {
+    const allowed = TASK_STATE_EXITS[previous.state] ?? []
+    if (!allowed.includes(state)) {
+      throw new Error('tasks: refusing the transition ' + previous.state + ' -> ' + state + ' for "' + String(record.title ?? '') + '"; allowed from ' + previous.state + ': ' + allowed.join(', '))
+    }
+  }
+  writeFileSync(file, JSON.stringify({ backedUpAt: nowIso, state, record }, null, 2) + '\n', 'utf8')
+  return file;
+}
+
+/**
+ * Read one task file.
+ * @returns { file, backedUpAt, state, raw, record } or null when the file is unreadable.
+ *
+ * A malformed file yields null rather than throwing: one bad file must not take the layer down,
+ * and the index reports what it could not read instead of pretending the task is absent.
+ */
+export function readTaskFile(file) {
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'))
+    if (!parsed || typeof parsed !== 'object' || !parsed.record || typeof parsed.record !== 'object') return null
+    return {
+      file,
+      backedUpAt: typeof parsed.backedUpAt === 'string' ? parsed.backedUpAt : null,
+      // Kept verbatim, including when unrecognised, so the index can show what it found.
+      state: typeof parsed.state === 'string' ? parsed.state : null,
+      stateKnown: readState(parsed.state) !== null,
+      record: parsed.record,
+    }
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Every task file in the layer, ordered by title so the index is stable between runs.
+ * @returns { tasks, unreadable } - unreadable names the files that could not be parsed.
+ */
+export function listTasks(root) {
+  const dir = tasksDir(root)
+  if (!existsSync(dir)) return { tasks: [], unreadable: [] }
+  const tasks = [];
+  const unreadable = [];
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith('.json')) continue;
+    const task = readTaskFile(join(dir, name));
+    if (task === null) unreadable.push(name);
+    else tasks.push(task);
+  }
+  tasks.sort((a, b) => String(a.record.title ?? '').localeCompare(String(b.record.title ?? '')));
+  unreadable.sort();
+  return { tasks, unreadable };
+}
+
+/** How long past its due time an armed task may sit before we call it failed. */
+export const OVERDUE_MS = 6 * 60 * 60 * 1000
+
+/**
+ * Derive a task's state from what can actually be observed.
+ *
+ * This is the honest version of the vocabulary, and three entries are narrower than they first
+ * look, because the host does not publish what they name:
+ *
+ * - FAILED is not a status the host records. A delivery failure throws before any commit
+ *   (runtime.ts:101-102), so a task failing on every scan stays 'active' with no trace. What IS
+ *   observable is a task still armed long after the moment it was due, which is what this
+ *   reports - 'due at X, still not delivered' rather than a claim about why.
+ * - ORPHANED is a live row whose owning session cannot be resolved, so it can never fire while
+ *   still occupying the store. Detecting that needs the session lookup, which the caller does;
+ *   it is passed in rather than guessed here.
+ * - SKIPPED is a live task with no backup file: seen, deliberately not captured.
+ *
+ * PAUSED outranks everything. An automatic restore must never silently re-arm something that was
+ * held back on purpose - that surprise is the thing this design exists to prevent.
+ *
+ * @returns { state, reason } - the reason is recorded so a reader is told why, not just what.
+ */
+export function deriveState({ stored, live, now = Date.now(), ownerResolvable = true }) {
+  if (stored === TASK_STATES.PAUSED) {
+    return { state: TASK_STATES.PAUSED, reason: 'held back on purpose; automatic restore leaves it alone' };
+  }
+  if (live) {
+    if (!ownerResolvable) {
+      return { state: TASK_STATES.ORPHANED, reason: 'armed, but the session that owns it cannot be resolved, so it can never fire' };
+    }
+    if (live.status === 'inactive') {
+      return { state: TASK_STATES.DONE, reason: 'delivered, or its recurrence is exhausted' };
+    }
+    const due = Date.parse(live.record && live.record.scheduledAt ? live.record.scheduledAt : '');
+    if (Number.isFinite(due) && due < now - OVERDUE_MS) {
+      return { state: TASK_STATES.FAILED, reason: 'was due at ' + new Date(due).toISOString() + ' and has still not delivered' };
+    }
+    return { state: TASK_STATES.ACTIVE, reason: 'armed in the live store and waiting for its next occurrence' };
+  }
+  if (stored === TASK_STATES.ACTIVE) {
+    return { state: TASK_STATES.STOPPED, reason: 'was armed; the host deletes a task when its session stops' };
+  }
+  return { state: TASK_STATES.PENDING, reason: 'in the backup, not in the live store; a restore re-arms it' };
+}
+
+/**
+ * Render the layer index.
+ *
+ * Readable and diffable, which is the whole reason the tasks are files rather than one blob: a
+ * git diff of this page is how you see that a task appeared, changed state, or went missing.
+ * Unreadable files are listed rather than omitted - an index that hides what it could not parse
+ * reports a smaller world than exists.
+ */
+export function renderTaskIndex(rows, { unreadable = [], nowIso, error = null } = {}) {
+  const out = ['# Scheduled tasks', ''];
+  out.push('Portable backup of the DSH scheduled tasks on this machine. One file per task, plus');
+  out.push('this index. Machine-local state (the owning session, delivery history) is never stored.');
+  out.push('');
+  out.push('Generated ' + nowIso + '. ' + rows.length + ' task(s).');
+  // A page that stayed silent while the backup could not read the store would read as a healthy
+  // machine with nothing to do. The failure belongs on the page, not only in a return value.
+  if (error) {
+    out.push('');
+    out.push('> **The last backup could not read the schedule store.** ' + String(error));
+    out.push('>');
+    out.push('> The tasks below are what memory already holds; they are not a fresh reading.');
+  }
+  out.push('');
+  if (rows.length === 0) {
+    out.push('No tasks are backed up yet. The backup runs on the memory sync cadence, or on demand');
+    out.push('with memory_tasks.');
+    out.push('');
+  } else {
+    out.push('| task | kind | schedule | state | backed up |');
+    out.push('| --- | --- | --- | --- | --- |');
+    for (const row of rows) {
+      out.push('| ' + cell(row.record.title) + ' | ' + cell(row.record.kind) + ' | ' + cell(scheduleOf(row.record)) + ' | ' + cell(stateCell(row)) + ' | ' + cell(row.backedUpAt) + ' |');
+    }
+    out.push('');
+    for (const row of rows) {
+      out.push('## ' + String(row.record.title ?? '(untitled)'));
+      out.push('');
+      out.push('- file: `' + row.fileName + '`');
+      out.push('- id: `' + String(row.record.id ?? '') + '` (diagnostic only; a restore mints a new one)');
+      out.push('- state: **' + row.state + '** - ' + row.reason);
+      out.push('');
+    }
+  }
+  if (unreadable.length > 0) {
+    out.push('## Could not be read');
+    out.push('');
+    for (const name of unreadable) out.push('- `' + name + '` - not valid task JSON, so it is neither counted nor drawn');
+    out.push('');
+  }
+  return out.join('\n');
+}
+
+/** A markdown table cell: a pipe or a newline in a title would otherwise break the row. */
+function cell(value) {
+  return String(value ?? '').replace(/\|/g, '\\|').replace(/\r?\n/g, ' ').trim();
+}
+
+/** The schedule in words, so the index is readable without decoding the record. */
+function scheduleOf(record) {
+  const kind = String(record.kind ?? '');
+  const zone = record.timeZone ? ' ' + record.timeZone : '';
+  if (kind === 'cron') return 'cron ' + String(record.expression ?? '') + zone;
+  if (kind === 'weekly') return 'weekly ' + JSON.stringify(record.weekly ?? {}) + zone;
+  if (kind === 'daily') return 'daily ' + JSON.stringify(record.daily ?? {}) + zone;
+  // The same camelCase/snake_case confusion as `after` above, in the same function. Writing a test
+  // to pin ONE of them surfaced the other.
+  if (kind === 'every') return 'every ' + String(record.everySeconds ?? '') + 's';
+  if (kind === 'at') return 'at ' + String(record.scheduledAt ?? '');
+  // `afterSeconds`, not `after_seconds` - the record uses camelCase, the CREATE REQUEST uses
+  // snake_case. The live index printed "after s" with the interval missing, which no test saw
+  // because no test rendered an `after` record.
+  if (kind === 'after') return 'after ' + String(record.afterSeconds ?? '') + 's';
+  return kind;
+}
+
+/** The state cell: an unrecognised stored state is shown as found, never silently defaulted. */
+function stateCell(row) {
+  return row.stateKnown === false ? row.state + ' (unknown state in file)' : row.state;
+}
+
+/** The kinds the schedule plugin can store (types.ts ScheduleRecord union). */
+export const KNOWN_KINDS = ['after', 'at', 'every', 'daily', 'weekly', 'cron']
+
+/**
+ * Where the schedule plugin keeps its tasks: a storage unit under the DSH home.
+ *
+ * DSH_HOME is the harness's own override (boot/app-boot reads it), defaulting to ~/.dsh - the
+ * same resolution the harness uses, so the plugin finds the store without being told.
+ */
+export function defaultSchedulePath(home = homedir()) {
+  const configured = process.env.DSH_HOME
+  const dshHome = configured && configured !== '' ? configured : join(home, '.dsh')
+  return join(dshHome, 'storages', 'schedule.json')
+}
+
+/**
+ * Read the live schedule store.
+ * @returns { tasks, error, missing } where tasks are the rows as stored.
+ *
+ * A missing file is not an error: a machine that has never scheduled anything has no store, and
+ * the backup pass must read that as 'nothing to do' rather than as a failure. A file that exists
+ * but cannot be read IS reported, because writing an index over an unreadable store would quietly
+ * claim the machine has no tasks.
+ */
+export function readScheduleStore(path) {
+  if (!existsSync(path)) return { tasks: [], error: null, missing: true }
+  let parsed
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'))
+  } catch (error) {
+    return { tasks: [], error: 'unreadable: ' + (error && error.message ? error.message : String(error)), missing: false }
+  }
+  const table = parsed && parsed.tables && parsed.tables.tasks
+  if (!table || typeof table !== 'object') return { tasks: [], error: 'no tables.tasks in the schedule store', missing: false }
+  return { tasks: Object.keys(table).map((id) => ({ id, ...table[id] })), error: null, missing: false }
+}
+
+/**
+ * Back up every live task, and refresh the state of every task already backed up.
+ *
+ * ADDITIVE, ALWAYS. Nothing here deletes: a task gone from the live store keeps its file and has
+ * its state rewritten to say so. A stale backup must never be able to wipe a schedule, and a task
+ * deleted on purpose must stay visible as gone rather than vanish from the record of what this
+ * machine used to run.
+ *
+ * A task whose kind we do not recognise is stored and flagged SKIPPED: dropping it would mean losing
+ * a task from a backup, and flagging it means a restore refuses it rather than guessing.
+ */
+export function backupTasks(root, { schedulePath, now = Date.now(), nowIso, sessions } = {}) {
+  const at = nowIso ?? new Date(now).toISOString()
+  const live = readScheduleStore(schedulePath ?? defaultSchedulePath())
+  // Read once per pass, not per task: it is a directory walk, and every row asks the same question.
+  // Injectable so a test can state the world instead of inheriting this machine's: `null` means
+  // the question cannot be answered and no row is called orphaned.
+  const sessionSet = sessions === undefined ? sessionIdsOnDisk() : sessions
+  const before = listTasks(root)
+  if (live.error !== null) {
+    // The index is still rewritten, so a page from an earlier pass cannot sit on disk describing a
+    // store this pass could not read.
+    writeTaskIndex(root, before.tasks.map((t) => describeTask(t, now)), { unreadable: before.unreadable, nowIso: at, error: live.error })
+    return { written: 0, refreshed: 0, skipped: [], stopped: 0, unreadable: before.unreadable, error: live.error }
+  }
+  const byKey = new Map()
+  for (const task of before.tasks) byKey.set(contentKey(task.record), task)
+  let written = 0
+  let refreshed = 0
+  const skipped = []
+  const seen = new Set()
+  for (const task of live.tasks) {
+    const record = task.record
+    if (!record || typeof record !== 'object') { skipped.push({ id: task.id, reason: 'no record' }); continue }
+    if (!KNOWN_KINDS.includes(String(record.kind))) {
+      // CAPTURED, not dropped. An earlier version skipped these entirely, which meant a task whose
+      // kind we did not recognise silently vanished from a BACKUP - the one job this layer has. It
+      // is written and flagged 'skipped' instead, and planRestore refuses that state, so it can
+      // never be blindly re-armed. Preserved, visible, and unrestorable: all three on purpose.
+      skipped.push({ id: task.id, reason: 'unrecognised kind: ' + String(record.kind) })
+      writeTask(root, record, TASK_STATES.SKIPPED, byKey.get(contentKey(record))?.backedUpAt ?? at)
+      seen.add(contentKey(record))
+      continue
+    }
+    const key = contentKey(record)
+    seen.add(key)
+    const previous = byKey.get(key)
+    // A held-back task stays held back across every backup: that state is the user's decision, and
+    // a routine pass must not overwrite it with a derived one.
+    const held = previous && previous.stateKnown && previous.state === TASK_STATES.PAUSED
+    // Without this the ORPHANED state exists in the vocabulary and is never produced by any real
+    // pass - reachable from a unit test and from nothing else. `sessions === null` means the
+    // sessions directory is absent and we cannot tell, so the row is left as active.
+    const ownerResolvable = sessionSet === null || task.sessionId === undefined ? true : sessionSet.has(task.sessionId)
+    const derived = deriveState({ stored: held ? TASK_STATES.PAUSED : null, live: task, now, ownerResolvable })
+    writeTask(root, record, derived.state, previous ? previous.backedUpAt : at)
+    if (previous) refreshed += 1
+    else written += 1
+  }
+  let stopped = 0
+  const rows = []
+  for (const task of listTasks(root).tasks) {
+    if (seen.has(contentKey(task.record))) { rows.push(task); continue }
+    const derived = deriveState({ stored: task.stateKnown ? task.state : null, live: null, now })
+    if (derived.state !== task.state) {
+      writeTask(root, task.record, derived.state, task.backedUpAt ?? at)
+      stopped += 1
+    }
+    rows.push({ ...task, state: derived.state })
+  }
+  writeTaskIndex(root, rows.map((t) => describeTask(t, now)), { unreadable: before.unreadable, nowIso: at })
+  return { written, refreshed, skipped, stopped, unreadable: before.unreadable, error: null, rows, nowIso: at }
+}
+
+/**
+ * Write the layer index.
+ *
+ * Regenerated on every pass rather than appended: an index that only grows would report tasks the
+ * machine no longer runs as though they were still there. The per-task files are the truth; this
+ * page is a view of them, which is why losing it costs nothing.
+ * @returns the index path.
+ */
+export function writeTaskIndex(root, rows, { unreadable = [], nowIso, error = null } = {}) {
+  ensureTasksDir(root)
+  const file = join(tasksDir(root), TASK_INDEX)
+  writeFileSync(file, renderTaskIndex(rows, { unreadable, nowIso, error }), 'utf8')
+  return file
+}
+
+/**
+ * Translate a stored record back into the request the schedule service accepts.
+ *
+ * The two shapes do NOT share field names, and the differences are the kind that fail silently:
+ * a record stores `timeZone` and `everySeconds` (types.ts ScheduleRecord union), while
+ * ScheduleCreateRequest takes `time_zone` and `every_seconds`. Passing the record straight
+ * through would drop the zone - a task would be re-armed in the wrong time zone, or refused, and
+ * nothing in the record would look wrong afterwards.
+ *
+ * One-shot kinds are REFUSED rather than approximated. An `at` record keeps only its resolved
+ * instant, which for any task that already ran is in the past, and an `after` record keeps a
+ * relative delay whose clock would restart from now. Re-arming either would fabricate a schedule
+ * the user never set, so the caller is told instead.
+ *
+ * @returns { request } or { error } naming exactly what could not be translated.
+ */
+export function toCreateRequest(record) {
+  if (!record || typeof record !== 'object') return { error: 'no record' }
+  const title = String(record.title ?? '').trim()
+  const prompt = String(record.prompt ?? '')
+  if (title === '') return { error: 'no title' }
+  if (prompt === '') return { error: 'no prompt' }
+  const kind = String(record.kind ?? '')
+  const zone = record.timeZone
+  if (kind === 'cron') {
+    if (typeof record.expression !== 'string' || record.expression === '') return { error: 'cron with no expression' }
+    if (typeof zone !== 'string' || zone === '') return { error: 'cron with no time zone' }
+    return { request: { title, prompt, cron: { expression: record.expression, time_zone: zone } } }
+  }
+  if (kind === 'daily') {
+    if (typeof record.time !== 'string' || record.time === '') return { error: 'daily with no time' }
+    if (typeof zone !== 'string' || zone === '') return { error: 'daily with no time zone' }
+    return { request: { title, prompt, daily: { time: record.time, time_zone: zone } } }
+  }
+  if (kind === 'weekly') {
+    if (typeof record.time !== 'string' || record.time === '') return { error: 'weekly with no time' }
+    if (typeof zone !== 'string' || zone === '') return { error: 'weekly with no time zone' }
+    if (!Array.isArray(record.weekdays) || record.weekdays.length === 0) return { error: 'weekly with no weekdays' }
+    return { request: { title, prompt, weekly: { time: record.time, time_zone: zone, weekdays: [...record.weekdays] } } }
+  }
+  if (kind === 'every') {
+    if (!Number.isFinite(record.everySeconds) || record.everySeconds <= 0) return { error: 'every with no interval' }
+    return { request: { title, prompt, every_seconds: record.everySeconds } }
+  }
+  if (kind === 'at' || kind === 'after') {
+    return { error: 'a one-shot ' + kind + ' task is not restorable: it either already fired or its target is in the past, and re-arming it would invent a schedule that was never set' }
+  }
+  return { error: 'unrecognised kind: ' + kind }
+}
+
+/**
+ * Decide what a restore would do, without doing any of it.
+ *
+ * Pure, so the decision can be tested and shown before anything is written. Additive and
+ * de-duplicating by CONTENT: the service mints a fresh id on every create (schedule index.ts:256),
+ * so a restored task never keeps the id it was backed up with, and matching on ids would find
+ * nothing on the second boot and re-add everything.
+ *
+ * @returns { add, present, paused, refused } - one entry per backed-up task, each saying why.
+ */
+export function planRestore(root, { liveTasks = [], now = Date.now() } = {}) {
+  const live = new Set(liveTasks.map((task) => contentKey(task.record)))
+  const { tasks, unreadable } = listTasks(root)
+  const add = []
+  const present = []
+  const paused = []
+  const refused = []
+  for (const task of tasks) {
+    const key = contentKey(task.record)
+    if (live.has(key)) { present.push({ task, reason: 'already in the live store, under whatever id it now carries' }); continue }
+    if (task.stateKnown && task.state === TASK_STATES.PAUSED) { paused.push({ task, reason: 'held back on purpose; automatic restore leaves it alone' }); continue }
+    if (task.stateKnown && task.state === TASK_STATES.SKIPPED) { refused.push({ task, reason: 'recorded as skipped' }); continue }
+    const translated = toCreateRequest(task.record)
+    if (translated.error) refused.push({ task, reason: translated.error })
+    else add.push({ task, request: translated.request })
+  }
+  return { add, present, paused, refused, unreadable }
+}
+
+/** The directory DSH keeps session records in, beside the schedule store's home. */
+export function sessionsRoot(home = homedir()) {
+  const configured = process.env.DSH_HOME
+  const dshHome = configured && configured !== '' ? configured : join(home, '.dsh')
+  return join(dshHome, 'sessions')
+}
+
+/**
+ * Every session id that still has a record on disk.
+ *
+ * Used to tell ORPHANED from ACTIVE. A live task is armed against the session that created it, and
+ * the runtime resolves an agent from that id before every delivery (schedule runtime.ts:101) - so
+ * a task whose session is gone is a row that will never fire while still occupying the store. The
+ * backup cannot see the runtime, but it can see whether the session still exists.
+ *
+ * @returns a Set, or null when the sessions directory is absent
+ *
+ * Null rather than an empty set on purpose: no sessions directory means we cannot tell, and an
+ * empty set would mark every task on the machine orphaned. Refusing to guess is the rule here.
+ */
+export function sessionIdsOnDisk(home = homedir()) {
+  const root = sessionsRoot(home)
+  if (!existsSync(root)) return null
+  const ids = new Set()
+  let projects
+  try { projects = readdirSync(root) } catch { return null }
+  for (const project of projects) {
+    let sessions
+    try { sessions = readdirSync(join(root, project)) } catch { continue }
+    for (const id of sessions) ids.add(id)
+  }
+  return ids
+}