@try-works/dsh-memory 0.1.15 → 0.1.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@try-works/dsh-memory",
-  "version": "0.1.15",
+  "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}}