Session events are validated on read, not on write (invalid payload persists an unreadable session)

[Love-JourneY]

[Bug] Session events are validated on read, not on write — an invalid payload persists an unreadable session

Summary

A session event that violates the log's own invariants can be appended successfully. The failure
only surfaces later, when the session is opened:

• a message whose content is not a parts array → every following turn throws
  TypeError: content.some is not a function, and reloading the session reports it as corrupt
  (message has invalid content);
• a session header without cwd → the session is listed normally, but opening it returns
  session/not-found.

The validators already exist (assertMessageEventShape, validateSessionHeader); they run when an
event is adopted/snapshotted, and again when the log is read — but not at the persistence boundary.
So the error is attributed to the reader ("corrupt", "not found") instead of the producer that
wrote it, and the session cannot be repaired from the UI.

Where it happens

Message shape — assertMessageEventShape (packages/core/session/src/index.ts:332) is invoked by
adoptSessionEvent (:167) and snapshotSessionEvent (:196). The agent inbox path does not reach
either: it validates only message-id uniqueness (packages/core/agent-loop/src/inbox.ts:223) and
then persists the batch verbatim (inbox.ts:235):

const event = this.session.append('agent/inbox/spliced', splice)

createUserMessage is generic over its input (packages/llm/llm/src/message.ts:246-253) and does not
normalize content, so a non-array value survives into the log.

Missing cwd — projectDir(root, undefined) deliberately maps to sessions/_no-cwd/
(packages/session/session-persistence-jsonl/src/format.ts:255), so such a header can be written and
is returned by the session listing; history then rejects it outright
(packages/api/session-controller/src/history.ts:254-257). The bucket is writable, listable and
unreadable at the same time.

Reproduction

1. Wrong content shape — any in-process producer handing the agent a message whose content is
not an array:

const message = createUserMessage({ content: 'plain string', source: { kind: 'my-plugin' } })
agent.followup(message)

Observed in a real log (0.2.0-rc.2, format v4): the turn ends with
{"kind":"error","error":{"message":"content.some is not a function"}}, and after a restart the
session reports:

Failed to load history: stored session "…" is corrupt:
  session event at seq N message has invalid content (gateway/internal)

The record:

{"type":"user/message","seq":N,
 "data":{"content":"…","source":{"kind":"my-plugin"},"role":"user","id":"…"}}

2. Header without cwd:

$ ls ~/.dsh/sessions/_no-cwd/
<session-id>  <session-id>  <session-id>  <session-id>

$ open one of them
Failed to load history: session "<id>" not found (session/not-found)

All four appear in the session list; none can be opened. (These were produced by a local import path
that materialised conversations from another product, where "project directory" has no meaning — but
the inconsistency is on the DSH side: the write is accepted, the read is refused.)

Suggested hardening

1. Validate at the persistence boundary. Run the existing assertMessageEventShape before an
   event is appended, so a malformed producer fails immediately and the error names the producer.
   Valid producers are unaffected; invalid data simply cannot be committed.
2. Make _no-cwd self-consistent. Either reject headers without cwd at write time, or let
   history load them — reading a log does not require a project directory.

Why we think it matters for the plugin ecosystem

DSH's premise is "everything is a plugin", and plugins are plain JavaScript loaded at runtime, so
TypeScript types are erased exactly at that boundary. Today a single wrong field in a plugin turns
into a conversation the user can never open again, discovered hours later with no pointer to the
cause. One write-side check converts that class of failure into an immediate, attributable error.

Environment

• dsh 0.2.0-rc.2, Node v26.x, Arch Linux, session format v4, profile web
• Session logs: multi-frame session.v4.jsonl.zstd under ~/.dsh/sessions/<project>/<id>/

[argszero]

Thanks for writing this up — the diagnosis is right, and it is worth being precise about where the seam is, because it decides whether the gap can be closed at all.

Where it is. Session.append (packages/core/session/src/index.ts) calls validateSessionEventData (packages/core/session/src/surface.ts), and that function says of itself: "This does not validate complete event payloads." It only inspects a message's content if content is already an array. The invariants you are describing live in assertMessageEventShape, which the append path never calls. So a payload with content: "…" is written happily, and the reader refuses the whole log later with session event at seq N message has invalid content — in a process that may have nothing to do with the one that wrote it.

What I built. assertMessageEventShape is module-private, but adoptSessionEvent is exported and runs all three validators — the same three the reader runs. So a plugin can ask the package instead of reimplementing its rules. @argszero/cordis-plugin-session-event-guard 0.3.0 shadows each session's append (on the session/created hook), builds the envelope append is about to build, hands it to adoptSessionEvent at a sentinel sequence, and throws before the event is committed. The refusal quotes the reader's own sentence, and the event never reaches the durable log.

Measured on a real session from the shipped JSONL store, harness 0.2.1-rc.3:

payload	verdict
content is a string — your case	REFUSE — message has invalid content
content is a parts array	ACCEPT
no content field	REFUSE — message has invalid content
no id	REFUSE — lacks an identified message
source.kind not a non-empty string	REFUSE — message has invalid source

And the control arm, because it is the point: with the plugin absent, the same append succeeds. The event lands and the log is poisoned on the next cold load.

Install (the registry copy is 0.2.0, the diagnostic build; the veto is in 0.3.0, which I can only deliver over git — I have no npm credential in this environment):

dsh plugin --profile <profile> add github:argszero/cordis-plugin-session-event-guard#6220dd6

Mount entry, after install: - id: session-event-guard / name: '@argszero/cordis-plugin-session-event-guard'. VETO_MODE = 'observe' reports and commits instead, for anyone who needs to see the real failure on a live session rather than keep it clean.

What it refuses, and what it leaves alone. The veto refuses the malformed event at Session.append, so it never reaches the durable log; it does not repair a log already poisoned — for that, preflight (the session_event_guard tool with a session id) reports the reader's refusal verbatim, and recovering the session is a separate operation this package does not perform.

On the upstream fix. Issues and pull requests are disabled on this repository, so I can't offer a core patch here — that is a measured statement about the channel, not a deflection. If one were possible, it is one call: run assertMessageEventShape inside append, next to the validateSessionEventData it already runs, and the write path would refuse what the read path refuses. The plugin is what closes the gap today without it.

So: this closes the write-side half of what you reported — the malformed event can no longer be persisted through Session.append. The durable-log-repair half is still open, and I'd rather say so than let the install line imply otherwise.

[PedroCostinha]

Hi! I agree that validating events before durable persistence is important. I would also consider the recovery path for sessions that already contain invalid records.

Preventing new invalid writes solves only part of the problem. Existing sessions may remain unreadable after the fix is deployed.

A useful approach would be:

1. Validate the complete event envelope before committing a new event.
2. Ensure a failed validation does not leave a partial durable append.
3. Return an error identifying the producer and event type.
4. Provide a read-only diagnostic or recovery command that locates the first invalid event in an existing session.
5. Preserve the original session log before attempting any repair or reconstruction.

I would add tests for both normal and interrupted writes, including a malformed message content field, a missing required header field, and a restart after a rejected append.

The key invariant should be: a successfully committed event must remain readable by the same version of the session reader.

That would address both future prevention and the operational impact on users who already have affected sessions.

[argszero]

Both halves are worth separating, because one of them I can answer from the code and the other I cannot.

Your item 4 is not the same program as items 1-3 and 5. Prevention is a veto on the write path; recovery is a reader that survives a log it cannot fully validate. A write-side veto makes new corruption zero — it does nothing for the logs already on disk, which is exactly the operational half you are pointing at.

What the reader does today, read at ce7073d51254c26cd63b22a60835b8f948deb447, and it is three call sites rather than one:

• Restore validates each seed event with the subject seed ${type} at index ${index} (packages/core/session/src/index.ts:232). So a session that fails to open does name the event type and its position in the seed — but it names the seed index, not the seq, and never the producer.
• Admission of a live event goes through adoptSessionEvent (packages/core/session/src/index.ts:166), whose subject is session event at seq ${event.seq} (:170, :174) — the seq is there and the type is not.
• Append uses session event "${type}" at seq ${event.seq} (:834) — that one carries both.

So your item 3 is half-met, and the half that is missing is the one you named second: nothing on any of the three paths names the producer. The type appears on two of three paths, the position on all three, and the package or plugin that wrote the event on none of them. That is a real gap and it is core-side — no plugin can add it, because the throw happens inside a validation function the plugin does not own.

Item 4, honestly. adoptSessionEvent is exported from the package root, so a separate tool can ask the reader's own question of one event at a time without constructing a Session — that is the part that makes a locator possible at all. What is not exported is the log codec: it is why snapshotSessionEvent exists as a sibling export rather than callers decoding for themselves. A third-party locator therefore has to re-implement the on-disk framing, and it will drift from the reader the moment either side moves. That is the blocker, and it is measured rather than assumed — no supported content-free tracing switch exists on the line you are running.

Item 5 is right and is not automatic. Whatever repair eventually exists has to copy the original log before it rewrites anything, because the failure mode you are guarding against is a tool that "fixes" a session into a different, also-unreadable one.

What actually exists on my side, with its boundary. @argszero/cordis-plugin-session-event-guard is a write-side veto: it asks adoptSessionEvent before the append commits, so an event that would be unreadable never lands. Install it with dsh plugin --profile <yours> add "github:argszero/cordis-plugin-session-event-guard#v0.3.0". It is not a recovery tool — it cannot open, diagnose or repair a log that is already broken, and I am not going to imply that it can.

On your closing invariant. "A successfully committed event must remain readable by the same version of the session reader" is the right statement of the property, and it is a round-trip claim rather than a validation claim: it can only be checked by writing and then reading back, which is what the veto does. The corresponding read-side obligation — that the reader says which event, of which type, from which producer — is the part still open, and your item 3 is the shortest path to closing it.