[Research preview] dsh-subagent-contract — durable cross-session subagent canary

[ArmyWas]

Summary

I built dsh-subagent-contract, an independent post-run verifier for durable DeepSeek Harness subagent behavior:

https://github.com/ArmyWas/dsh-subagent-contract

中文摘要：这个项目不评估“最终回答看起来是否正确”，而是重新读取父、子会话的原始持久化日志，验证跨会话关系是否真实成立。目前是 research preview，已经用 @deepseek-ai/dsh-sdk-client@0.1.2-alpha.2 跑通真实四场景，并保留了可复核的结构化证据和 fail-closed 边界。

Why this gap matters

A parent can return plausible text while the durable multi-agent record is wrong: a child may have the wrong parent/depth, a rejected admission may leave an unaccounted session, a follow-up may land in a replacement conversation, or a report/settlement notice may be attributed to the wrong child.

Merged tool counts and LLM scoring cannot prove these properties. The verifier therefore reopens every parent/child log and checks seven cross-session contracts:

1. lineage graph;
2. own descriptor shape/order;
3. admission cardinality;
4. foreground output identity;
5. continuation identity and FIFO;
6. settlement provenance;
7. report provenance.

Duplicate check / scope boundary

This is intentionally narrower than existing work:

• dsh-eval owns YAML benchmark execution, isolation, aggregation, and run comparison;
• dsh-eval-harness owns plugin-regression execution and session-log decoding;
• the official runtime already has an in-process start/end invariant.

This project adds a post-process, cross-session contract layer over durable headers, descriptors, parent tool results, continuation messages, reports, and settlement notices. It does not introduce another benchmark DSL or LLM judge.

Current evidence

On Windows, the fixed four-case matrix against @deepseek-ai/dsh-sdk-client@0.1.2-alpha.2 produced:

• 4 verified / 4 passed;
• 0 failed / 0 inconclusive;
• 0 violations / 0 compatibility errors;
• every case passed on attempt 1;
• 9 session logs and 11 persisted request headers;
• every request header enforced the 4,096 output-token cap.

The checked-in summary binds the artifact to the exact runner, lifecycle observer, retry policy, environment policy, dependency lockfile, and three overlays. It is explicitly labeled self-attested local verification, not a third-party signature. Raw prompts, responses, session ids, paths, and credentials are not committed.

The fail-closed behavior was also exercised during hardening. Separate local runs were rejected when a parent sent an extra FIFO message or started a duplicate report child. Those failures were not retried or presented as passes. Only an exclusive S00_SCENARIO_NOT_EXERCISED may retry; a lifecycle, permission, trace, token, cleanup, compatibility, or contract failure stops the matrix.

Reproducibility and limits

• 44 verifier tests;
• 16 runner lifecycle/policy/environment tests;
• public CI green on Ubuntu Node 22/24 and Windows Node 24;
• SDK initialization smoke green on Ubuntu and Windows;
• full live matrix currently exercised on Windows only;
• npm publication intentionally deferred; the persistent SDK runner remains a source-only experiment.

Research preview release:
https://github.com/ArmyWas/dsh-subagent-contract/releases/tag/v0.1.0-preview.1

Questions for maintainers

1. Is a stable public contract for multi-session run artifacts and subagent provenance something Harness wants to support long-term?
2. Would these checks be more useful as an upstream eval fixture, an official canary, or an independent compatibility tool?
3. Are descriptor/provenance changes planned after v3 that this verifier should treat as explicit compatibility drift rather than guess through?

I would be happy to adapt the matrix or contribute the narrow checks upstream if maintainers prefer a different ownership boundary.