@try-works/dsh-memory 0.1.8 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@try-works/dsh-memory",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Git-backed, workspace-scoped memory for the DeepSeek Harness (global layer + per-workspace layers)",
   "type": "module",
   "main": "src/index.js",

package/src/config.js

@@ -12,6 +12,9 @@ import { DEFAULT_CONFIG, defaultMemoryRoot } from './defaults.js'
 export const Config = z.object({
   // --- Settings -> Memory ---
   memoryRoot: z.string().default(defaultMemoryRoot()).volatile(),
+    // Where the schedule plugin keeps its tasks. Overridable so a test (or an unusual DSH_HOME)
+    // can point somewhere else; the default resolves DSH_HOME exactly as the harness does.
+    schedulePath: z.string().default('').volatile(),
   // A PREFERENCE, not a requirement: memory work walks a ladder of the models this
   // deployment can actually route to, so an empty value still works and an unusable model
   // is skipped rather than losing the memory.

package/src/host.js

@@ -16,12 +16,14 @@ import { due, problems, readQueue, reapStalled, REASONS, STATES, summarize as su
 import { planRecovery, recoverOne } from './recover.js'
 import { logRun, noteActivity, readMetrics, record } from './telemetry.js'
 import { GitRunner, SyncScheduler, classifyGitResult, commitMessage } from './git.js'
+import { backupTasks, defaultSchedulePath, planRestore, readScheduleStore } from './tasks.js'
 import { autoAssociateSession } from './session.js'
 import { readAssociations } from './workspace.js'
 
 const PLUGIN = 'dsh-memory'
 
 /** How often the idle ticker checks whether a cadence is due (the cadences self-throttle). */
+const TASKS_BACKUP_MS = 30 * 60 * 1000
 const IDLE_TICK_MS = 60_000
 
 function makeGitRunner(ctx) {
@@ -66,6 +68,8 @@ export function wireHost(ctx, store, cfg) {
   const injectionThrottle = new Map()
   let lastConsolidateAttempt = 0
   let lastRefreshAttempt = 0
+  let lastTasksBackupAttempt = 0
+  let restoreAttempted = false
   let lastHistoryAttempt = 0
   let syncInFlight = false
 
@@ -595,6 +599,96 @@ export function wireHost(ctx, store, cfg) {
     return { initialized: false, committed, synced }
   }
 
+  /**
+   * Back up the scheduled tasks on the sync cadence.
+   *
+   * This rides a cadence rather than an event because the thing it protects against is not an
+   * event: the host DELETES a task when its session stops (schedule index.ts:421), so a task can
+   * vanish between two turns with nothing to observe. Only a periodic pass notices.
+   *
+   * Throttled like the other cadences, and it reports through the run log the same way: a backup
+   * that silently stopped working would be indistinguishable from a machine with no tasks.
+   */
+  function maybeBackupTasks() {
+    const now = Date.now()
+    if (now - lastTasksBackupAttempt < TASKS_BACKUP_MS) return
+    lastTasksBackupAttempt = now
+    try {
+      // `||`, not `??`: the config default is an empty string, and `??` passes that straight
+      // through, so the pass would read a path of '' , find no store, and report a clean run that
+      // backed up nothing. A silent no-op is the failure this whole layer exists to prevent.
+      const result = backupTasks(store.root, { schedulePath: cfg.schedulePath || defaultSchedulePath() })
+      logRun(store.root, 'tasks-backup', {
+        ok: result.error === null,
+        written: result.written,
+        refreshed: result.refreshed,
+        stopped: result.stopped,
+        skipped: result.skipped.length,
+        error: result.error ?? '',
+      })
+    } catch (error) {
+      logRun(store.root, 'tasks-backup', { ok: false, error: String((error && error.message) || error).slice(0, 160) })
+    }
+  }
+
+  /**
+   * Restore backed-up tasks into the live schedule store, once per process.
+   *
+   * WHY IT WAITS FOR A SESSION. The schedule runtime resolves an agent from the task's sessionId
+   * before every delivery and throws when it cannot (schedule runtime.ts:101). At boot there is no
+   * session, so a task restored then would be armed against an owner that does not exist and would
+   * fail on every due scan. The first real session is therefore the earliest moment a restore can
+   * produce a task that actually fires.
+   *
+   * The OWNER IS CHOSEN, NEVER ASKED FOR. That session becomes the task's owner, and the report
+   * says so: the host deletes a task when its owning session stops (schedule index.ts:421), so a
+   * reader needs to know which session holds them.
+   *
+   * ADDITIVE. It only ever creates; nothing here deletes or updates. A task already in the live
+   * store is left exactly as it is, matched by CONTENT because create() mints a fresh id
+   * (schedule index.ts:256) and ids therefore cannot identify anything across a restore.
+   */
+  async function maybeRestoreTasks(agent) {
+    if (restoreAttempted) return
+    if (!agent || isSubagentSession(agent.session)) return
+    const sessionId = agent.session && agent.session.id
+    if (!sessionId) return
+    const schedule = ctx.get('schedule')
+    if (!schedule || typeof schedule.create !== 'function') return
+    restoreAttempted = true
+    try {
+      const path = cfg.schedulePath || defaultSchedulePath()
+      const live = readScheduleStore(path)
+      if (live.error !== null) {
+        logRun(store.root, 'tasks-restore', { ok: false, error: live.error })
+        return
+      }
+      const plan = planRestore(store.root, { liveTasks: live.tasks })
+      const added = []
+      const failed = []
+      for (const entry of plan.add) {
+        try {
+          const record = await schedule.create(sessionId, entry.request)
+          added.push({ id: record && record.id, title: entry.request.title })
+        } catch (error) {
+          failed.push({ title: entry.request.title, error: String((error && error.message) || error).slice(0, 120) })
+        }
+      }
+      logRun(store.root, 'tasks-restore', {
+        ok: failed.length === 0,
+        owner: sessionId,
+        added: added.length,
+        present: plan.present.length,
+        paused: plan.paused.length,
+        refused: plan.refused.length,
+        failed: failed.length,
+        detail: failed.length ? failed : undefined,
+      })
+    } catch (error) {
+      logRun(store.root, 'tasks-restore', { ok: false, error: String((error && error.message) || error).slice(0, 160) })
+    }
+  }
+
   function maybeSync() {
     if (syncInFlight || !git) return
     if (!scheduler.shouldCommit() && !scheduler.shouldSync()) return
@@ -635,6 +729,9 @@ export function wireHost(ctx, store, cfg) {
     maybeRefresh(agent)
     maybeHistory(agent)
     maybeSync()
+    maybeBackupTasks()
+    // Only a real session can own a restored task, so the restore waits for this hook.
+    void maybeRestoreTasks(agent)
     const now = Date.now()
     if (step !== 1 && now - (injectionThrottle.get(agent.id) ?? 0) < cfg.injectionRefreshMs) return decision
     injectionThrottle.set(agent.id, now)
@@ -668,6 +765,7 @@ export function wireHost(ctx, store, cfg) {
         maybePrune()
         // The ticker has no agent, so history ingest waits for the next step in a session.
         maybeSync()
+        maybeBackupTasks()
       } catch (error) {
         ctx.logger.warn('dsh-memory: idle tick failed: ' + (error && error.message))
       }
@@ -693,5 +791,7 @@ export function wireHost(ctx, store, cfg) {
   // injectionMaxChars travels with the host so memory_map can describe the card that was
   // ACTUALLY built: the cap is configuration, and a snapshot built with a different cap would
   // report a size the session never saw.
-  return { scheduler, syncNow: () => runSync(true), consolidate: consolidateNow, refresh: refreshNow, status: statusNow, recover: recoverNow, rerankSearch, workspaceOf, historyOf, injectionMaxChars: cfg.injectionMaxChars }
+  // Resolved once, here, where the config lives: tools.js has no access to cfg and a tool that
+  // reached for it would throw at call time (which is how memory_tasks first failed).
+  return { scheduler, schedulePath: cfg.schedulePath || defaultSchedulePath(), tasksNow: maybeBackupTasks, tasksRestore: maybeRestoreTasks, syncNow: () => runSync(true), consolidate: consolidateNow, refresh: refreshNow, status: statusNow, recover: recoverNow, rerankSearch, workspaceOf, historyOf, injectionMaxChars: cfg.injectionMaxChars }
 }

package/src/index.js

@@ -41,6 +41,9 @@ export function hostExtras(host) {
     workspaceOf: host.workspaceOf,
     historyOf: host.historyOf,
     injectionMaxChars: host.injectionMaxChars,
+    tasksNow: host.tasksNow,
+    tasksRestore: host.tasksRestore,
+    schedulePath: host.schedulePath,
   }
 }
 export const name = 'dsh-memory'

package/src/tasks.js

@@ -0,0 +1,536 @@
+// 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 { 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 = {
+  active: ['stopped', 'done', 'failed'],
+  pending: ['active'],
+  paused: ['pending'],
+  stopped: ['pending'],
+  failed: ['active'],
+  orphaned: ['pending'],
+  skipped: ['active'],
+  done: ['active'],
+}
+
+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;
+}
+
+/** The directory holding the task files for a scope root. */
+export function tasksDir(root) { return join(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]: 'seen in the live store but not captured, because its kind is not one we can read',
+  [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)
+  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;
+  if (kind === 'every') return 'every ' + String(record.every_seconds ?? '') + 's';
+  if (kind === 'at') return 'at ' + String(record.scheduledAt ?? '');
+  if (kind === 'after') return 'after ' + String(record.after_seconds ?? '') + '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 SKIPPED, not written: storing it would mean restoring
+ * it later without understanding it. It is reported, so the omission is visible.
+ */
+export function backupTasks(root, { schedulePath, now = Date.now(), nowIso } = {}) {
+  const at = nowIso ?? new Date(now).toISOString()
+  const live = readScheduleStore(schedulePath ?? defaultSchedulePath())
+  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))) {
+      skipped.push({ id: task.id, reason: 'unrecognised kind: ' + String(record.kind) })
+      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
+    const derived = deriveState({ stored: held ? TASK_STATES.PAUSED : null, live: task, now })
+    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 }
+}

package/src/tools.js

@@ -12,6 +12,7 @@ import { appendActivity, clearActivity, readWorking, workingSummary, writeWorkin
 import { associate, listWorkspaces } from './workspace.js'
 import { forget, forgetUndo } from './forget.js'
 import { buildMap } from './map.js'
+import { backupTasks, defaultSchedulePath, describeTask, listTasks, planRestore, readScheduleStore, TASK_STATES, writeTask } from './tasks.js'
 
 function renderHits(hits) {
   if (!hits || hits.length === 0) return [{ type: 'text', text: '(no memory matches)' }]
@@ -58,6 +59,25 @@ function renderMap(value) {
   }
   return parts.join('; ') + '.'
 }
+/** The text face of a tasks report: what a caller without a UI still needs to know. */
+function renderTasks(value) {
+  const parts = []
+  parts.push('Scheduled tasks: ' + value.live + ' live, ' + value.backedUp + ' backed up')
+  const p = value.pending ?? {}
+  if (p.add) parts.push(p.add + ' would be restored')
+  if (p.present) parts.push(p.present + ' already present')
+  if (p.paused) parts.push(p.paused + ' held back')
+  if (p.refused) parts.push(p.refused + ' refused')
+  if (value.changed) parts.push('this call: ' + JSON.stringify(value.changed))
+  const states = {}
+  for (const task of value.tasks ?? []) states[task.state] = (states[task.state] ?? 0) + 1
+  const summary = Object.keys(states).map((s) => s + ' ' + states[s]).join(', ')
+  if (summary) parts.push('states: ' + summary)
+  if (value.unreadable && value.unreadable.length) parts.push(value.unreadable.length + ' file(s) unreadable: ' + value.unreadable.join(', '))
+  if (value.error) parts.push('COULD NOT READ THE SCHEDULE STORE: ' + value.error)
+  return parts.join('; ') + '.'
+}
+
 export function registerTools(ctx, store, extras = {}) {
   /**
    * Refuse a WRITE from a subagent session.
@@ -80,6 +100,9 @@ export function registerTools(ctx, store, extras = {}) {
   const statusNow = extras.status
   const recoverNow = extras.recover
   const injectionMaxChars = extras.injectionMaxChars
+  const tasksNow = extras.tasksNow
+  const tasksRestore = extras.tasksRestore
+  const schedulePathOf = extras.schedulePath
 
   ctx.tools.register(defineTool({
     name: 'memory_search',
@@ -305,6 +328,90 @@ export function registerTools(ctx, store, extras = {}) {
     },
   }))
 
+
+  ctx.tools.register(defineTool({
+    name: 'memory_tasks',
+    description: 'Show and manage the backup of this machine\'s DSH scheduled tasks. The schedule store is the only copy of them: it is in no git repository, and the host DELETES a task when its owning session stops, so a task can vanish with nothing to observe. Memory keeps one file per task under global/tasks/ and restores them automatically into a session on boot. Actions: report (default), backup, restore, pause, resume.',
+    parameters: {
+      action: { type: 'string', description: 'report (default), backup, restore, pause or resume.' },
+      title: { type: 'string', description: 'Task title, required for pause and resume.' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          action: { type: 'string', required: true },
+          schedulePath: { type: 'string', required: true },
+          live: { type: 'integer', required: true },
+          backedUp: { type: 'integer', required: true },
+          tasks: { type: 'array', items: { type: 'object', additionalProperties: true }, required: true },
+          unreadable: { type: 'array', items: { type: 'string' } },
+          changed: { type: 'object', additionalProperties: true },
+          // What a restore would do, which is the question a reader of this report is asking:
+          // how many tasks would be re-armed, how many are already there, how many are held.
+          pending: { type: 'object', additionalProperties: true },
+          error: { type: 'string' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: renderTasks(value) }],
+      // The structured face. Without presentationMeta a tool result reaches its session event with
+      // no meta at all (core/tools/src/index.ts:1845-1859), which is the only channel a UI has.
+      presentationMeta: (_args, value) => value,
+    },
+    async execute(args, exec) {
+      const action = ['report', 'backup', 'restore', 'pause', 'resume'].includes(args.action) ? args.action : 'report'
+      const schedulePath = schedulePathOf || defaultSchedulePath()
+      let changed = null
+      if (action === 'backup') {
+        if (!tasksNow) throw new Error('memory_tasks: the backup is unavailable in this context')
+        const r = backupTasks(store.root, { schedulePath })
+        changed = { written: r.written, refreshed: r.refreshed, stopped: r.stopped, skipped: r.skipped.length, error: r.error }
+      } else if (action === 'restore') {
+        if (!tasksRestore) throw new Error('memory_tasks: the restore is unavailable in this context')
+        await tasksRestore(exec.agent)
+        changed = { restored: true }
+      } else if (action === 'pause' || action === 'resume') {
+        if (!args.title) throw new Error('memory_tasks: ' + action + ' needs a title')
+        const { tasks } = listTasks(store.root)
+        const match = tasks.find((task) => String(task.record.title ?? '') === args.title)
+        if (!match) throw new Error('memory_tasks: no backed-up task titled "' + args.title + '"')
+        // Pausing writes the STATE only. It does not touch the live store: a held task is not
+        // disarmed here, it is simply never re-armed by an automatic pass, which is the decision a
+        // pause expresses. Resuming returns it to the queue, and the next pass derives it afresh.
+        const nextState = action === 'pause' ? TASK_STATES.PAUSED : TASK_STATES.PENDING
+        writeTask(store.root, match.record, nextState, match.backedUpAt ?? new Date().toISOString())
+        changed = { title: args.title, state: nextState }
+      }
+      // The report is read AFTER the action, so what the caller sees is the state they produced.
+      const live = readScheduleStore(schedulePath)
+      const { tasks, unreadable } = listTasks(store.root)
+      const plan = planRestore(store.root, { liveTasks: live.tasks })
+      const rows = tasks.map((task) => {
+        const described = describeTask(task, Date.now())
+        return {
+          title: String(task.record.title ?? ''),
+          kind: String(task.record.kind ?? ''),
+          state: described.state,
+          reason: described.reason,
+          file: task.file,
+        }
+      })
+      return {
+        action,
+        schedulePath,
+        live: live.tasks.length,
+        backedUp: tasks.length,
+        tasks: rows,
+        unreadable,
+        ...(changed ? { changed } : {}),
+        ...(live.error ? { error: live.error } : {}),
+        // Carried for the tool's own use, never shown: the planner's own view of what a restore
+        // would do, which is the question a reader of this report is actually asking.
+        pending: { add: plan.add.length, present: plan.present.length, paused: plan.paused.length, refused: plan.refused.length },
+      }
+    },
+  }))
+
   ctx.tools.register(defineTool({
     name: 'memory_map',
     description: 'Show what memory holds, and what THIS session has done with it. scope "store" reports the whole store - entries per layer, freshness, workspaces, and the ingest queue. scope "session" reports what memory injected into this conversation and what this conversation wrote back. "all" returns both. Read-only, and the data behind the Memory view.',
@@ -321,7 +428,17 @@ export function registerTools(ctx, store, extras = {}) {
           session: { type: 'object', additionalProperties: true },
         },
       },
+      // The text face, for the agent and for any caller without a UI.
       render: (_args, value) => [{ type: 'text', text: renderMap(value) }],
+      // The STRUCTURED face, and the only reason the Memory tab and the inline card can draw
+      // anything. A tool result reaches the session event with a `meta` field ONLY when the tool
+      // declares presentationMeta (core/tools/src/index.ts:1845-1859), and that field is what
+      // ui-chat forwards to a view (conversation-nodes/tool.ts:77: meta: match.event.data.meta).
+      // Without this, memory_map rendered its snapshot to prose and threw the value away: the tab
+      // showed 'the result carried no snapshot' while the same call displayed 2,197 entries in
+      // the conversation. The rendered text is not a substitute - rebuilding panels by parsing it
+      // would be a second source of truth.
+      presentationMeta: (_args, value) => value,
     },
     async execute(args, exec) {
       const scope = args.scope === 'store' || args.scope === 'session' ? args.scope : 'all'