@yadsh/dsh-session-audit

Session audits as a first-class part of a DeepSeek Harness session: an Audit view beside Chat and Trajectory, driven by audit artifacts on disk.

An audit is a pair of files an auditor writes into $DSH_HOME/audits:

$DSH_HOME/audits/session-41b4e63f/
├── analysis.json     verdict, scores, findings, recommendations
└── REPORT.md         the full human-readable review

Copy a directory in and it appears in the session it names — no restart, no command, no configuration. Modify it and the view follows. Remove it and the view goes back to its empty state.

Features

• A fourth session view. Chat | Trajectory | Audit, with three tabs: the report rendered from REPORT.md (tables, lists and a table of contents), the structured findings from analysis.json, and the raw document as a tree or text.
• Nothing to configure. trajectory.sessionId in the analysis decides which session an audit belongs to. The directory name is only a fallback, and a name that could mean two sessions attaches to neither.
• An audit no session can show is still announced. A directory that names no session — or one whose analysis.json cannot be parsed — belongs to no view, so every session's Audit view lists it by name with the reason it is not attached. Copying an audit in and seeing nothing is never the answer you are left with.
• It works while DSH runs. A startup scan, a filesystem watcher and a periodic reconciliation: an audit that arrives through a Docker bind mount, a network share or a scp is picked up even where native events do not reach the process.
• Cheap to leave on. A check reads a file only after its size or mtime moved, and reloads the view only when the content actually changed.
• A future schema is not an error. An audit whose schemaVersion this build does not know still shows its report and its raw JSON.
• Untrusted content, treated as such. Size caps before a read, strict UTF-8, symlinks refused rather than followed, no filesystem path on the wire, and a Markdown renderer with no HTML path at all.
• Other plugins can read it. ctx.get("sessionAudit") returns the same record this plugin's own view shows, so @yadsh/dsh-qa-surface badges an audited chat without owning a second scanner.
• Optional in both directions. The plugin needs no other plugin, and a surface that consumes it renders unchanged when it is absent.

Install

dsh plugin --profile web add @yadsh/dsh-session-audit

From a checkout of this repository:

pnpm nx run @yadsh/dsh-session-audit:build
dsh plugin --profile web add ./plugins/dsh-session-audit

--profile is required: dsh plugin add <package> rejects a call without one.

Configuration

Configure the plugin under the session-audit key in the DSH profile.

Option	Type	Default	Description
enabled	boolean	true	Scan, watch and serve audits at all
auditRoot	string	""	Blank resolves from $DSH_AUDIT_ROOT, then $DSH_HOME/audits
watch	boolean	true	Watch the audit root; off leaves the reconciliation timer only
watchMode	auto | events | poll	auto	poll for a bind mount, a network share or a Syncthing folder
settleMs	number	1000	Quiet period after a change before the root is re-read
rescanIntervalMs	number	30000	Reconciliation interval; 0 disables the timer
allowDirectoryPrefixMatch	boolean	true	Allow the fallback binding by directory-name prefix
maxAnalysisBytes	number	10485760	Refuse a larger analysis.json before reading it
maxReportBytes	number	5242880	Refuse a larger REPORT.md before reading it
exposeHeaderBadge	boolean	true	Reserved for a session-header badge

$DSH_AUDIT_ROOT overrides $DSH_HOME/audits when auditRoot is blank. $DSH_HOME itself defaults to ~/.dsh.

Writing an audit

A producer may write its own files, and the watcher's settle window exists for that case. The reliable path is to let @yadsh/dsh-audit-core publish it: it validates the exact bytes it writes, stages both files inside the audit root, and moves the directory into place with a single rename, so a reader never sees a half-copied audit.

import { publishAudit } from "@yadsh/dsh-audit-core/producer";

await publishAudit({
  auditRoot,
  analysis,
  report,
});

A re-audit of the same session publishes beside the previous one rather than over it: the newest valid audit is the active one, and the earlier ones are kept.

Compatibility

• DeepSeek Harness >=0.1.7-rc.2 <0.2.0, tested against 0.1.7-rc.2.
• Node.js ^22.19.0 or >=24.0.0.
• See compatibility.json.

Development

pnpm build       # typert artifacts, declarations and the client bundle
pnpm test
pnpm typecheck
pnpm lint
pnpm check       # the full pipeline, then verify:package

License

MIT