[CarmenDou]

What

openagents 1.0.0 shipped with the wrong explanation of why channel history does not come back
after a restart, and with a Scope section the README no longer wants. This corrects the
explanation, drops the section, and takes the template to 1.0.1 because 1.0.0's canonical tag is
already published.

How

The explanation was wrong. The claim that shipped was that the messaging mod writes its
history only from shutdown(), so channel history never survives. Reading
sdk/src/openagents/mods/workspace/messaging/, _save_message_history has two call sites:

mod.py:170	_save_interval = 50, so the mod flushes every 50 messages
message_storage_helper.py	dump_interval_minutes = 10, a second flush every 10 minutes
mod.py:338	shutdown(), the third

The deploy that verified 1.0.0 posted one message and restarted a few minutes later. Neither
threshold fired, so nothing was ever written, and the storage directory holds no history file and
no dump rather than an empty one. The same instance's forum directory holds the metadata.json
written the minute its topic was created, which is the contrast that rules out the volume and the
platform: one mod in this app batches, the other writes through.

So the accurate statement is narrower. Whatever arrived since the last flush is in memory only.

alwaysOn: true still earns its place, because scale-to-zero on a quiet network drops that
tail with nobody having restarted anything. The manifest comment now argues it from the batching
rather than from a mod that never persists.

The Scope section comes out. Its two caveats go back into the body where a reader meets
them in context: the channel one as part of what the volume does and does not hold, corrected,
and the MCP one back in the walkthrough step that sends people to /api.

1.0.0 -> 1.0.1. version-guard refuses a manifest change against a published canonical tag,
correctly: overwriting :1.0.0 would drift instances already deployed. The Dockerfile and
entrypoint.sh are untouched, so the rebuild carries the same image content under the new tag.

One for upstream, not worked around here

shutdown() calls self.message_history.clear() and self.files.clear() and only then calls
_save_message_history() and _save_file_metadata(), both of which open their file with "w"
and write whatever dict they are handed. A graceful shutdown therefore truncates
message_history.json and files_metadata.json to empty, discarding batches that had already
been written, while an abrupt stop loses only the unflushed tail. On this mod a clean shutdown is
the more destructive of the two. Left alone here because it belongs in openagents-org/openagents.

Verify

$ node scripts/version-guard.mjs origin/main
✓ openagents: 1.0.0 -> 1.0.1

$ npm run lint
✓ openagents

$ npm run check-categories
✓ 32 templates and the UI snapshot match the platform's 15 categories

$ npx vitest run templates/scripts
Test Files  16 passed (16)
     Tests  453 passed (453)

The two source facts, read on the pinned tree:

mod.py:170    self._save_interval = 50  # Save every 50 messages
mod.py:2207   self._message_count_since_save += 1
mod.py:2208   if self._message_count_since_save >= self._save_interval:
mod.py:2209       self._save_message_history()

message_storage_helper.py:32   dump_interval_minutes: int = 10,

And on the still-running verification instance, the contrast between the two mods:

mods/…forum/      metadata.json   (written the minute the topic was created)
                  topics/
mods/…messaging/  files/          (no message_history.json, no dump)

🤖 Generated with Claude Code

---

Summary by cubic

Corrects the openagents template's explanation of why channel history is lost after a restart, and removes the Scope section.

The claim that shipped with 1.0.0 — that the messaging mod writes history only from shutdown() and channels never survive — is wrong. The mod flushes every 50 messages and dumps every 10 minutes; the verification behind 1.0.0 posted a single message, so neither threshold fired and nothing was ever written. What is true is narrower: whatever arrived since the last write is in memory only. alwaysOn: true stays justified, now argued from that batching. The Scope section's caveats move back into the README body, the channel one corrected and the MCP one as it stood. Bumps the manifest to 1.0.1 because the 1.0.0 canonical tag is already published; image content is unchanged.

Upstream, not worked around here

A graceful shutdown is more destructive than an abrupt stop: shutdown() clears the history and file dicts before saving with "w", truncating files that already held batches. Left for openagents-org/openagents.

^{Written for commit de5c2ee. Summary will update on new commits.}

[cubic-dev-ai]

2 issues found across 2 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="templates/openagents/README.md">

<violation number="1" location="templates/openagents/README.md:35">
P2: These lines imply that a scheduled flush makes channel history survive a restart. The pinned mod’s shutdown path can truncate already-flushed history, so document that shutdown caveat too.</violation>

<violation number="2" location="templates/openagents/README.md:36">
P2: The README now explains the persistence trade-off without disclosing its cost. Keep a sentence here stating that the template stays always on to avoid scale-to-zero loss and bills continuously.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The README now explains the persistence trade-off without disclosing its cost. Keep a sentence here stating that the template stays always on to avoid scale-to-zero loss and bills continuously.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At templates/openagents/README.md, line 36:

<comment>The README now explains the persistence trade-off without disclosing its cost. Keep a sentence here stating that the template stays always on to avoid scale-to-zero loss and bills continuously.</comment>

<file context>
@@ -31,7 +31,9 @@ from source as a separate backend and frontend.
-  one. Channel messages are upstream's own exception, covered under Scope below.
+  one. Channel messages are the exception: the messaging mod batches them, writing its history
+  out every 50 messages or every 10 minutes, so whatever has arrived since the last write is in
+  memory only and a restart drops it. The forum and the wiki write through as they go.
 - A password gate on registration, enforced at the protocol level: a `POST /api/register` with no
   password is refused with "Password authentication required for network registration".
</file context>

[cubic-dev-ai]

P2: These lines imply that a scheduled flush makes channel history survive a restart. The pinned mod’s shutdown path can truncate already-flushed history, so document that shutdown caveat too.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At templates/openagents/README.md, line 35:

<comment>These lines imply that a scheduled flush makes channel history survive a restart. The pinned mod’s shutdown path can truncate already-flushed history, so document that shutdown caveat too.</comment>

<file context>
@@ -31,7 +31,9 @@ from source as a separate backend and frontend.
   forum and wiki, and uploaded files. A forum topic created before a restart was still there after
-  one. Channel messages are upstream's own exception, covered under Scope below.
+  one. Channel messages are the exception: the messaging mod batches them, writing its history
+  out every 50 messages or every 10 minutes, so whatever has arrived since the last write is in
+  memory only and a restart drops it. The forum and the wiki write through as they go.
 - A password gate on registration, enforced at the protocol level: a `POST /api/register` with no
</file context>

Suggested change

	out every 50 messages or every 10 minutes, so whatever has arrived since the last write is in
	memory only and a restart drops it. The forum and the wiki write through as they go.
	out every 50 messages or every 10 minutes, but the upstream shutdown path can still truncate
	persisted history, so a stop or scale-to-zero can lose messages even after an earlier flush. The
	forum and the wiki write through as they go.

[jwfing]

LGTM - approved.