@try-works/dsh-memory 0.1.14 → 0.1.16

package/package.json

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

package/src/SYSTEM.template.md

@@ -254,6 +254,45 @@ Sync failures are never swallowed: a failed pull or push is logged, recorded in
 surfaced by `status()`, reported by `memory_sync`, and leaves a `state/CONFLICT.md` marker that
 the next clean sync clears.
 
+## 9b. The scheduled tasks layer
+
+`global/tasks/` is not a memory layer and holds no memories. It is a portable backup of the DSH
+scheduled tasks on this machine, and it exists because the schedule store is the only copy of them:
+it is in no git repository, and the host DELETES a task when the session that owns it stops. A task
+can therefore vanish with nothing to observe.
+
+One JSON file per task, plus a regenerated `index.md`. A file holds the task's record - id, kind,
+title, prompt, and the selector that says when it runs - and its lifecycle state. The owning session
+and the delivery history are deliberately NOT stored: they are machine-local, and carrying a session
+id to another machine would make a restored task fail, because the session it names does not exist
+there.
+
+Because the task files live in this store and are not gitignored, a push carries them to your other
+machines, where they are re-armed on boot.
+
+The states, and what each one means:
+
+| state | meaning |
+| --- | --- |
+| `active` | armed in the live store, waiting for its next occurrence |
+| `pending` | in the backup, not in the live store; a restore re-arms it |
+| `paused` | held back on purpose. Every automatic pass leaves it alone |
+| `stopped` | was armed, and its owning session stopped, so the host deleted it |
+| `failed` | was due and has still not delivered. The host records no failure of its own, so this is what is observable |
+| `orphaned` | armed, but the session that owns it no longer exists, so it can never fire |
+| `skipped` | captured, but its kind is not one we can re-arm, so a restore refuses it |
+| `done` | delivered, or its recurrence is exhausted |
+
+Two cadences, both off the write path. The **backup** runs with the sync cadence and is additive:
+it never deletes, so a stale backup cannot wipe a schedule. The **restore** runs once per process at
+the first real session, because a task needs a live session to own it, and it binds each restored
+task to that session - you are never asked which one. It matches tasks by CONTENT, not by id, since
+the schedule service mints a fresh id on every create.
+
+`memory_tasks` reports the whole picture and can `backup`, `restore`, `pause` or `resume` on
+demand. Holding a task back is a decision, and it outranks every automatic pass: a `paused` task is
+never silently re-armed.
+
 ## 10. Current state of this store
 
 {{storeState}}

package/src/host.js

@@ -648,20 +648,24 @@ export function wireHost(ctx, store, cfg) {
    * 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
+  async function maybeRestoreTasks(agent, { force = false } = {}) {
+    // EVERY early return REPORTS WHY. These used to return silently, and the tool that calls this
+    // reported success regardless - so a manual restore after the boot pass returned immediately at
+    // the once-per-process guard while telling the caller it had restored. An action that does
+    // nothing and says it worked is worse than one that fails.
+    if (restoreAttempted && !force) return { ran: false, reason: 'already restored in this process; pass force to run it again' }
+    if (!agent || isSubagentSession(agent.session)) return { ran: false, reason: 'a restored task needs a main session to own it' }
     const sessionId = agent.session && agent.session.id
-    if (!sessionId) return
+    if (!sessionId) return { ran: false, reason: 'the session has no id to bind the task to' }
     const schedule = ctx.get('schedule')
-    if (!schedule || typeof schedule.create !== 'function') return
+    if (!schedule || typeof schedule.create !== 'function') return { ran: false, reason: 'the schedule service is unavailable' }
     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
+        return { ran: true, owner: sessionId, error: live.error }
       }
       const plan = planRestore(store.root, { liveTasks: live.tasks })
       const added = []
@@ -684,8 +688,10 @@ export function wireHost(ctx, store, cfg) {
         failed: failed.length,
         detail: failed.length ? failed : undefined,
       })
+      return { ran: true, owner: sessionId, added: added.length, present: plan.present.length, paused: plan.paused.length, refused: plan.refused.length, failed: failed.length }
     } catch (error) {
       logRun(store.root, 'tasks-restore', { ok: false, error: String((error && error.message) || error).slice(0, 160) })
+      return { ran: true, owner: sessionId, error: String((error && error.message) || error).slice(0, 160) }
     }
   }
 

package/src/tools.js

@@ -368,8 +368,11 @@ export function registerTools(ctx, store, extras = {}) {
         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 }
+        // FORCED, because the once-per-process guard has almost certainly already been consumed by
+        // the boot restore - the manual action exists to run it again on demand.
+        // The outcome is REPORTED rather than assumed: this used to say { restored: true } whatever
+        // happened, including when nothing did.
+        changed = await tasksRestore(exec.agent, { force: true })
       } else if (action === 'pause' || action === 'resume') {
         if (!args.title) throw new Error('memory_tasks: ' + action + ' needs a title')
         const { tasks } = listTasks(store.root)