[DeepSeek Harness 2/8] Produce a reproducible DeepSeek Harness candidate runtime
- Dominant language
- TypeScript
- Stars
- 22.5k
- Forks
- 3.1k
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 715
Description
## Summary
Produce the exact, integrity-verifiable DeepSeek Harness runtime artifacts and managed images required for candidate-only NemoClaw qualification.
Parent epic: #9328
Depends on #9329, **[DeepSeek Harness 1/8] Accept product scope, ownership, threat model, and compatibility matrix**.
Gate 3 consumes the entry points and image from this issue. Gates 4 through 7 consume the exact candidate identities and artifacts. Gate 8 alone owns public activation.
## Problem Statement
NemoClaw has no owned DeepSeek Harness agent manifest, locked runtime closure, managed image, startup wrapper, final configuration-overlay location, or candidate publication contract.
Installing `@deepseek-ai/dsh` dynamically does not establish a reproducible runtime. The package is prerelease software with a large workspace-published dependency family, browser artifacts, profile auto-initialization, package symlink repair, and possible native or lifecycle-script dependencies.
An image that installs packages on first boot, uses a floating npm version, omits built Web assets, or accepts writable user patches as managed authority cannot be qualified or safely activated.
## Desired Behavior
The repository contains one DeepSeek Harness agent directory that builds a complete, non-root, dual-architecture candidate runtime from an exact lockfile and reviewed dependency closure.
The candidate image contains every accepted runtime and browser artifact before publication. Startup does not contact a package registry, execute an installer, update DSH, or install a profile plugin.
Protected candidate paths can select each exact image digest. Public agent selection and the shipped all-agent cohort remain unchanged until Gate 8.
## Accepted contract dependency
Implementation must copy the exact accepted Gate 1 values into source-owned contracts rather than silently retaining investigation defaults. This includes:
- package version, integrity, source commit, and Node.js runtime;
- accepted architectures and compute runtime;
- Web/headless surface matrix and entry points;
- accepted preset and tool roster;
- managed final-overlay mechanism;
- state path classification needed by the manifest;
- browser bind and port contract when Web is accepted.
If any value is still undecided, this issue is blocked rather than authorized to choose it.
## Implementation Idea
Use the manifest-first layout:
```text
agents/deepseek-harness/
manifest.yaml
start.sh
generate-config.ts
managed.cordis.patch.yml
policy-additions.yaml
dependency-review.md
package.json
package-lock.json
Dockerfile
Dockerfile.base
```
Exact filenames may follow current repository conventions, but the ownership boundaries must remain visible.
The managed Cordis overlay must live outside writable `$DSH_HOME` state, be owned by the image/runtime envelope, and be passed after shipped, profile, and home layers. Gate 5 supplies the accepted inference configuration and Gate 6 supplies the full policy roster; this issue establishes the immutable precedence mechanism and candidate artifact.
The accepted built-in profiles may auto-initialize deterministically from image-shipped templates. Auto-initialization must not fetch packages or make generated profile/package symlinks portable state.
## Scope
- `agents/deepseek-harness/manifest.yaml` with canonical identity, exact version probe, runtime surfaces, health metadata where accepted, architectures, startup-profile contract, state declarations, and package metadata.
- Exact `package.json` and lockfile for the complete published runtime closure.
- Dependency, license, install-script, native-addon, executable, and browser-artifact review.
- An accepted Node.js base pinned by immutable identity.
- Non-root AMD64 and ARM64 image builds.
- Image-bundled Web frontend and shipped profile/preset resources when Web is accepted.
- Root-owned startup wrapper and final managed overlay.
- Deterministic profile initialization without registry access.
- Version, configuration-dump, binary, frontend, and permission smoke probes.
- Candidate managed-image catalog, repository-map, and protected qualification registration.
- Exact per-architecture image digests and provenance.
- Candidate authority that remains empty until Gate 7 evidence is accepted and Gate 8 activates the runtime.
## Constraints and Non-goals
- Do not use a floating package selector, image tag, base-image tag without immutable resolution, or runtime auto-update.
- Do not run `npm`, `pnpm`, `npx`, profile plugin installation, or another package installer at first boot.
- Do not assume `--ignore-scripts` works. Review every required lifecycle script or native addon and allow only the accepted minimum.
- Do not build the stock image from a Dockerfile during user onboarding.
- Do not download Web assets at runtime.
- Do not put an upstream provider credential, direct-provider API key, route secret, or test credential in the image or build provenance.
- Do not place managed route or policy authority in writable `$DSH_HOME`, `settings.yaml`, a user profile patch, or the invoking workspace.
- Do not restore generated `node_modules`, package symlinks, caches, or auto-initialized shipped profiles as user state.
- Do not add DeepSeek Harness-specific Docker, Podman, lifecycle, snapshot, or recovery code.
- Do not add DeepSeek Harness to public choices or the active shipped-image cohort; Gate 8 owns activation.
- Do not claim Web authentication, inference compatibility, complete policy enforcement, state recovery, or live release qualification in this artifact slice.
## Observable acceptance tests
Repository tests must prove:
1. The manifest parses and its canonical ID, version, architecture, runtime, configuration, and state fields equal the accepted Gate 1 contract.
2. The lockfile resolves one exact version and integrity for every production dependency; an altered integrity, missing package, unexpected package, or unlocked dependency fails.
3. The dependency review enumerates all install scripts, native addons, executable bins, licenses, and shipped browser/profile assets and fails on unreviewed additions.
4. The image build performs no network-dependent package operation after its locked install layer and first boot performs no package operation at all.
5. `/usr/local/bin/dsh --version` reports the exact accepted version on AMD64 and ARM64.
6. Web help and the accepted Web configuration dump work from built artifacts without a source checkout when Web is accepted.
7. The accepted headless configuration dump works without a source checkout when headless is accepted.
8. The image contains the accepted Web frontend, profile templates, preset resources, final managed overlay, and startup wrapper.
9. The runtime user is non-root; `$DSH_HOME` is owner-only; managed artifacts and the final overlay are not writable by that user.
10. A writable home or profile patch cannot outrank or replace a sentinel managed row supplied by the final overlay.
11. First boot with package-registry egress denied still initializes only the accepted deterministic profiles and passes its smoke probes.
12. Image and filesystem scans find no upstream provider credential, direct-provider test key, route secret, `.credentials.yaml`, or populated `.env`.
13. Candidate publication produces exact AMD64 and ARM64 digests and rejects a partial architecture cohort.
14. Protected candidate selection can resolve those exact digests without a host Dockerfile build while public selection still rejects `deepseek-harness`.
15. Shared compute-runtime and managed-image tests can substitute a non-Docker provider identity without changing DeepSeek Harness artifacts.
## Required evidence
Attach or link a bounded candidate evidence manifest containing:
- NemoClaw candidate commit;
- accepted Gate 1 decision revision;
- package version, npm integrity, source commit, lockfile digest, dependency-review digest, and license/SBOM artifact;
- Node.js and base-image identities;
- AMD64 and ARM64 image digests plus build provenance;
- version, frontend, profile, configuration-precedence, permission, and offline-first-boot probe results;
- candidate catalog and publication-contract results;
- a credential scan attestation;
- confirmation that the accepted qualification-receipt list and public shipped cohort remain unchanged.
The repository-owned `dependency-review.md` must explain every approved install script/native addon and the condition that triggers re-review. Package or transitive-closure drift invalidates this evidence.
## Documentation impact
- Document the image-build source as a CI/publication input, not a user onboarding path.
- Record the exact candidate package and image identities in the repository-owned artifact contract.
- Add maintainer instructions for updating the package, regenerating the lockfile, reviewing closure drift, and producing new candidate digests.
- Do not add public user onboarding documentation before Gate 8.
## Acceptance Criteria
- [ ] Gate 1 is accepted and every artifact matches its exact contract.
- [ ] `agents/deepseek-harness/manifest.yaml` defines the candidate runtime without making it public.
- [ ] Package, lockfile, source, dependency review, base image, and per-architecture image identities are immutable and integrity-verifiable.
- [ ] Required install scripts, native addons, executables, licenses, and Web/profile artifacts are explicitly reviewed.
- [ ] AMD64 and ARM64 candidate images build and pass the same non-root artifact probes.
- [ ] The complete accepted runtime works from the image without a source checkout or first-boot package installation.
- [ ] The root-owned final overlay wins over writable home and profile layers in a deterministic negative test.
- [ ] No provider credential or test secret appears in the package inputs, image, environment defaults, provenance, or evidence.
- [ ] Protected qualification resolves exact image digests without a host build.
- [ ] Partial publication, lockfile drift, integrity drift, and missing browser/profile artifacts fail closed.
- [ ] DeepSeek Harness remains absent from public selection and the active shipped-image cohort.
- [ ] No artifact contains a DeepSeek Harness-specific compute-runtime lifecycle branch.
- [ ] The candidate evidence manifest and maintainer artifact documentation are complete.
## Category
Feature
## Checklist
- [x] I searched existing issues and this is not a duplicate.
- [x] I described the problem and desired behavior.
Contributor guide
Research direction
Start by reading dependency issue #9329 and the accepted Gate 1 contract, then compare current agent conventions with the listed agents/deepseek-harness files. Review manifest.yaml, package.json, package-lock.json, Dockerfile, Dockerfile.base, start.sh, generate-config.ts, and dependency-review.md before running the repository’s manifest, image, and offline-start probes. Done means immutable AMD64 and ARM64 candidate artifacts pass the stated acceptance tests without public activation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker, node.js, typescript
- Domain
- build-system, ci-cd, devops, infrastructure
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100