dsh-sessions-diagnosis

Usage

Command line

The CLI is a script in this repo, so it works straight from a checkout with no install step:

node bin/dsh-session-doctor.mjs scan

The examples below drop the node bin/ prefix for readability — read dsh-session-doctor scan as node bin/dsh-session-doctor.mjs scan. To get the bare command instead, run npm link once from the repo root (it writes to your global npm prefix); after that dsh-session-doctor is on PATH like dsh.

dsh-session-doctor scan                    # what is in the store
dsh-session-doctor diagnose                # classify every session
dsh-session-doctor diagnose            # one session, in detail
dsh-session-doctor repair              # dry run — writes nothing
dsh-session-doctor repair  --apply     # perform the repair
dsh-session-doctor repair --all --apply    # repair everything repairable
dsh-session-doctor rollback            # undo a repair this tool made
dsh-session-doctor verify                  # restore every session with DSH's codec
dsh-session-doctor demo                    # create a synthetic broken session
dsh-session-doctor demo --remove --apply   # delete it again
dsh-session-doctor rules                   # list the repair rules

--json on any command for machine-readable output; --dsh-home to point at a non-default store.

Try it without risking your data

dsh-session-doctor demo                          # a retired source.kind (low-risk rule)
dsh-session-doctor demo --scenario descriptor    # a stale descriptor version (medium-risk rule)
dsh-session-doctor demo --cwd D:\my\project      # record a specific working directory
dsh-session-doctor demo --id my-demo-session     # pin the session id

This writes a synthetic broken session — no real conversation is involved. It is a genuine released-v0 log, so DSH refuses it for exactly the reason it refuses a real one, and the same rules repair it.

A demo never goes into your session store. It is a deliberately unreadable session: putting it where DSH actually reads would place a broken conversation beside yours, add a row to a sidebar the demo has no business being in, and make the demo's id part of your harness's durable state. So demo writes to a throwaway store of its own — by default /dsh-session-doctor-demo, relocatable with DSH_DEMO_HOME — and refuses --root pointed at the real store, whatever spelling reaches it:

refusing to create a demo in the real session store (C:\Users\you\.dsh\sessions).
A demo is a deliberately broken session; it must not join your conversations.

The demo store is a complete DSH home, so the whole flow runs against it exactly as it would against yours:

dsh-session-doctor demo                                  # create it
dsh-session-doctor diagnose  --root       # it will not open
dsh-session-doctor repair    --root  --apply
dsh-session-doctor rollback  --root 
dsh-session-doctor demo --remove --apply                  # delete it again

To watch the same flow in the dashboard, point a throwaway harness at that home — never the one you are using:

$env:DSH_HOME = "/dsh-session-doctor-demo"; dsh web

Cleanup is guarded twice, because a demo is an ordinary session once it exists:

• Ownership is proved, not assumed. A demo carries a session.diag-demo.json marker that only this tool writes, and it must name the directory it sits in. The session id is never trusted — an id is just a string, and a real conversation could end up with a demo-looking one. Such a session is invisible to cleanup.
• A demo you have talked in is kept. The marker records the exact bytes that were generated, so cleanup can tell an untouched demo from one that has been resumed. Anything containing content this tool did not write is reported and left alone unless you pass --force.

Earlier versions of this tool did write demos into the real store, and archiving one in the sidebar leaves its id in the workspace registry afterwards. Such a leftover is harmless — a stale id matches nothing, and this tool does not edit that file — and demo --remove still cleans those stores up. New demos are never created there.

Agent tools

Three tools are registered for the model:

• session_store_overview — cheap census (header frames only)
• session_diagnose — full classification, store-wide or one session
• session_repair — dry run by default; writes only with apply: true, and action: "rollback" undoes a repair it made

Dashboard

Settings → Session diagnosis. Scan, inspect a verdict with its exact planned edits, and repair — the button always runs a dry run first and shows you what it will change before it touches anything. What the verdicts mean explains all seven verdicts in the panel, and every badge carries the same sentence as a tooltip, so a label like "unmigrated" never needs a trip to this file to be understood. A session repaired by this plugin shows its repair record and an Undo this repair button. Inspect expands that session's detail directly beneath its own row (click again to collapse it), so opening a session near the bottom of a long list never scrolls you back to the top.